跳到主要内容

支付流程

了解 Pelago 支付从创建到结算的完整生命周期。

支付状态​

状态说明​

状态描述Webhook 事件
created支付请求已初始化-
pending等待客户操作-
processing交易进行中-
completed支付成功payment.completed
failed支付失败payment.failed
expired支付超时payment.expired
settled资金已转至商户payment.settled
refunded支付已退款payment.refunded

详细流程​

第一阶段：创建支付​

请求：

{
  "amount": 100.00,
  "currency": "USD",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "merchantWallet": "GXXXXX...",
  "redirectUrl": "https://store.com/success",
  "webhookUrl": "https://store.com/webhook",
  "expiresIn": 1800
}

响应：

{
  "id": "pay_abc123",
  "status": "created",
  "amount": 100.00,
  "currency": "USD",
  "cryptoAmount": "100.000000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "url": "https://pay.pelago.tech/pay_abc123",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2025-02-08T22:30:00Z"
}

第二阶段：客户支付​

第三阶段：确认与 Webhook​

Webhook 负载：

{
  "id": "evt_xyz789",
  "type": "payment.completed",
  "created": "2025-02-08T22:15:30Z",
  "data": {
    "paymentId": "pay_abc123",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "cryptoAmount": "100.000000",
    "cryptocurrency": "USDC",
    "network": "stellar",
    "transactionHash": "abc123...def456",
    "merchantWallet": "GXXXXX...",
    "customerWallet": "GCUST...",
    "metadata": {
      "orderId": "order_12345"
    }
  }
}

第四阶段：结算​

边缘场景处理​

网络拥堵​

当区块链拥堵时：

  1. 支付在 processing 状态停留更久
  2. Pelago 持续监控确认
  3. 客户看到"确认中"状态
  4. 仅在确认后发送 Webhook

支付不足​

当客户支付金额低于要求：

  1. 支付标记为 partial
  2. 通过 Webhook 通知商户
  3. 可选择接受部分支付或要求补足

超额支付​

当客户支付金额超过要求：

  1. 支付标记为 overpaid
  2. 超出部分自动退还
  3. 或充入客户余额

超时处理​

最佳实践​

  1. 幂等性：在 metadata 中使用唯一 orderId
  2. Webhook 验证：始终验证签名
  3. 状态轮询：作为漏发 Webhook 的备选方案
  4. 过期处理：及时告知客户超时信息

下一步​