Guides
英文/English中文/Chinese

收单业务流程

DogPay 提供了一个标准的、非托管式的 Web3 收单网关。商户只需通过 API 创建订单并获取 payUrl（托管收银台链接），DogPay 将自动处理后续的链上地址分配、汇率锁定、链上资金监听与确认。

🗺️ 1. 核心时序图 (Sequence Diagram)

以下是 DogPay Web3 收单端到端的标准交互流程：

sequenceDiagram
    autonumber
    
    participant U as 终端用户 (User)
    participant M as 商户系统 (Merchant)
    participant D as DogPay 支付网关
    participant C as 区块链网络 (Blockchain)

    Note over U, D: 阶段 1：订单创建与收银台展示
    U->>M: 1. 在商户侧发起结账请求
    
    M->>D: 2. [可选] 获取支持的币种与公链配置
    Note right of M: GET /open-api/v1/pay/currency-config
    
    M->>D: 3. 创建支付订单
    Note right of M: POST /open-api/v1/pay
    D-->>M: 返回订单详情及托管收银台链接 (payUrl)
    
    M->>U: 4. 向用户展示支付链接 (页面跳转/内嵌/二维码)
    
    Note over U, C: 阶段 2：用户支付与链上广播
    U->>C: 5. 用户通过 Web3 钱包扫描或调用合约完成转账
    
    Note over D, M: 阶段 3：链上监听与状态流转
    C-->>D: 6. 侦测到交易在内存池中 (Tx Unconfirmed)
    Note over D: 系统更新: waitAmountOnChain (等待确认金额) 增加
    
    D-->>M: 7. 订单状态更新通知 (Webhook)
    Note right of M: Event: pay.transaction.update
    
    C-->>D: 8. 交易所在区块达到安全确认数 (Tx Confirmed)
    Note over D: 系统更新: doneAmountOnChain 增加，订单状态变更为 completed
    
    D-->>M: 9. 支付最终完成通知 (Webhook)
    Note right of M: Event: pay.transaction
    
    M-->>U: 10. 商户后端放行/发货，并在前端展示成功页面
    
    Note over D, M: 阶段 4：资金清算 (Settlement)
    D->>D: 11. 资金结算入账至商户的加密货币钱包 (Crypto Wallet)

⚙️ 2. 订单状态机详解 (Order State Machine)

为了准确掌握订单生命周期，您的系统需要理解并映射 DogPay 返回的以下三类状态字段：

📌 2.1 主状态 (status)

决定订单最终成败的核心指标，商户发货应严格依赖此状态。

状态值描述说明处理建议
pending处理中：订单已创建，等待用户支付，或用户的链上交易正在等待区块确认。请勿发货。在前端提示用户等待。
completed已完成：链上资金已到达设定的区块确认数，且金额匹配成功。安全发货/放行服务。
failed失败：订单由于各种原因未能成功（如超时未支付）。停止交易或引导用户重新下单。

📌 2.2 过程状态 (processStatus)

用于辅助判断订单当前处于何种细分阶段。

状态值描述说明
pending默认初始状态。
cancelled订单被主动取消。
timeout超过了创建订单时设定的 expireTime，订单已超时失效。
combine_completed多笔交易合并完成（例如用户分两次转账，总计金额达到了订单要求）。

📌 2.3 资金清算状态 (settleStatus)

标识该笔订单的资金是否已经落账到您的商户钱包（Crypto Wallet）中。

状态值描述说明
unsettled未清算：订单可能正在处理中，或者虽然已支付成功但尚未完成系统内部对账。
settled已清算：资金已安全增加到您的 DogPay 钱包余额中，可随时调用 发起提现接口 接口进行链上提现。

⛓️ 3. 链上金额确认机制 (On-Chain Amount Confirmation)

由于区块链的特性，一笔交易从发出到最终确认需要经过一段时间（例如以太坊可能需要几分钟，波场则更快）。为了让前端能展示实时的进度状态，我们在订单详情中提供了以下两个字段：

  • waitAmountOnChain (等待确认金额)：网络已侦测到用户的转账广播，但尚未达到安全区块确认数。此时资金并不绝对安全（存在被回滚或双花的极低风险）。
  • doneAmountOnChain (已确认金额)：交易已彻底固化在区块链上。只有当 doneAmountOnChain 大于或等于订单金额时，订单的 status 才会流转为 completed。
⚠️

最佳实践警示

请勿仅凭借 waitAmountOnChain 大于 0 就执行发货动作。务必以接收到订单 status = completed 的 Webhook 通知为唯一发货凭证。

Updated 5 days ago