收单回调文档（Webhook 通知）

概述

当支付交易完成后（无论成功或失败），系统将向商户系统提供的 notify_url 发送 HTTP POST 请求，通知交易状态。

商户需对通知进行验证、处理，并返回 HTTP 200 表示成功接收。

若返回非 200 状态或超时，系统将自动进入 指数退避重试机制。

Webhook 回调的请求体字段如下所示：

请求体字段结构

{
  "data": {
    "id": "pi_xxxx",
    "amount": 10000,
    "currency": "USD",
    "merchant_id": "acct_123456",
    "merchant_order_id": "order_id_123456",
    "result": {
      "result_code": "SUCCEEDED",
    },
    "metadata": {
      "shop": "happy",
      "domain": "example.com"
    }
  }
}

字段说明

data 对象字段

字段名	类型	必填	描述
id	string	是	平台支付单号
amount	integer	是	支付金额，单位为分
currency	string	是	支付币种（ISO 4217 标准三位码，如 USD）
merchant_id	string	是	商户编号，由平台分配
merchant_order_id	string	是	商户原始订单号
result	object	是	支付结果对象，包含状态码和信息
metadata	object	否	自定义透传字段，原样返回给商户（如店铺名、域名等）

result 子对象字段

字段名	类型	必填	描述
result_code	string	是	支付结果状态
result_message	string	否	错误说明，仅在失败时提供，例如：card_declined、insufficient_funds 等

result_code 取值说明

result_code	含义	说明/处理建议
SUCCEEDED	支付成功	交易已成功，商户可按此入账发货
FAILED	支付失败	交易未成功，商户应标记订单失败，不可入账或发货

示例值参考

支付成功示例

{
    "data": {
        "id": "pi_xxxx",
        "amount": 10000,
        "result": {
            "result_code": "SUCCEEDED"
        },
        "currency": "USD",
        "metadata": {
            "shop": "happy",
            "domain": "example.com"
        },
        "merchant_id": "acct_123456",
        "merchant_order_id": "order_id_123456"
    }
}

支付失败示例

{
    "data": {
        "id": "pi_xxxx",
        "amount": 10000,
        "result": {
            "result_code": "FAILED",
            "result_message": "insufficient_funds"
        },
        "currency": "USD",
        "metadata": {
            "shop": "happy",
            "domain": "example.com"
        },
        "merchant_id": "acct_123456",
        "merchant_order_id": "order_id_123456"
    }
}