跳到主要内容

结算机制

Pelago 如何聚合支付并结算至商户钱包。

结算概述​

Pelago 采用批量结算以优化成本与效率：

结算模式​

即时结算​

适用于高优先级支付：

  • 立即链上转账
  • 较高费率（0.5% vs 0.1%）
  • 适合大额交易
const payment = await pelago.payments.create({
  amount: 10000.00,
  settlementMode: 'instant', // 👈 即时结算
  // ...
});

批量结算（默认）​

标准结算模式：

  • 与其他支付聚合处理
  • 更低费率
  • 15-30 分钟结算窗口
const payment = await pelago.payments.create({
  amount: 100.00,
  settlementMode: 'batch', // 👈 默认行为
  // ...
});

定时结算​

自定义结算计划：

  • 每日、每周或每月
  • 预设时间段
  • 最低金额阈值选项
// 配置商户结算计划
await pelago.merchants.updateSettings({
  settlementSchedule: {
    frequency: 'daily',
    time: '18:00',
    timezone: 'UTC',
    minimumAmount: 100.00
  }
});

结算时间线​

费率结构​

结算类型费率处理时间
即时0.5%< 1 分钟
批量（默认）0.1%15-30 分钟
定时0.08%下一个窗口

费用计算​

结算费用 = 支付金额 × 费率
网络 Gas = 批次共摊（每笔极低）

示例：$100 支付，批量结算
- 费用：$100 × 0.1% = $0.10
- 商户到手：$99.90

结算报告​

查询结算历史​

// 获取结算历史
const settlements = await pelago.settlements.list({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  status: 'completed'
});

for (const settlement of settlements.data) {
  console.log(`
    ID: ${settlement.id}
    金额: $${settlement.amount}
    支付笔数: ${settlement.paymentCount}
    交易哈希: ${settlement.transactionHash}
    结算时间: ${settlement.settledAt}
  `);
}

结算 Webhook​

{
  "id": "evt_settle_123",
  "type": "settlement.completed",
  "created": "2025-02-08T22:30:00Z",
  "data": {
    "settlementId": "stl_abc123",
    "merchantId": "mer_xyz789",
    "totalAmount": 1250.00,
    "currency": "USDC",
    "paymentCount": 15,
    "fees": 1.25,
    "netAmount": 1248.75,
    "transactionHash": "abc123...def456",
    "wallet": "GXXXXX..."
  }
}

结算对账​

支付到结算的映射​

对账 API​

// 获取结算中的支付详情
const details = await pelago.settlements.getDetails('stl_abc123');

console.log('结算:', details.id);
console.log('总额:', details.totalAmount);
console.log('支付明细:');

for (const payment of details.payments) {
  console.log(`  - ${payment.id}: $${payment.amount}`);
}

多币种结算​

对于接受多种货币的商户：

// 配置首选结算币种
await pelago.merchants.updateSettings({
  settlementCurrency: 'USDC',
  autoConvert: true
});

结算失败处理​

重试逻辑​

  1. 检测到结算失败
  2. 5 分钟后自动重试
  3. 最多重试 3 次
  4. 全部失败则人工介入

失败 Webhook​

{
  "type": "settlement.failed",
  "data": {
    "settlementId": "stl_abc123",
    "reason": "insufficient_gas",
    "retryCount": 2,
    "nextRetryAt": "2025-02-08T22:45:00Z"
  }
}

最佳实践​

  1. 监控结算：设置失败告警
  2. 每日对账：匹配支付与结算
  3. 谨慎使用即时结算：费率更高，积少成多
  4. 设置阈值：避免微额结算

下一步​