SunPay 接口文档

简体中文

English

简体中文

English

外观

代付(出款) ​

受控代付:平台先冻结你的可用余额,再进入审批/出款流程;大额或命中风控的订单转人工审批。最终结果以回调/查询为准。

下单 POST /payout/create ​

请求业务参数(另带 公共参数):

字段必填说明
mch_order_no是商户订单号,商户内唯一
product_code是代付产品标识
amount是金额(该币种最小单位)
currency是币种(平台为你开通的;未开通返回 1001)
payee_name是收款人姓名
payee_account是收款账号
bank_code是银行/钱包编码,按币种、须与 currency 匹配,见 银行代码。不在码表 → 2006;该币种暂无可承接通道 → 1001
attach否透传数据(字符串)

请求示例:

json
{
  "merchant_no": "M100001",
  "app_id": "app_10001",
  "key_version": 1,
  "timestamp": 1769990400,
  "nonce": "c3d4e5f6a1b2c3d4",
  "sign_type": "RSA2",
  "mch_order_no": "PO20260601001",
  "product_code": "PAYOUT",
  "amount": 500000,
  "currency": "PHP",
  "payee_name": "Juan Dela Cruz",
  "payee_account": "09171234567",
  "bank_code": "PH_GXI",
  "sign": "BASE64_SIGNATURE"
}

响应 data 字段:

字段说明
platform_order_no / mch_order_no订单号
amount / fee / currency金额 / 手续费 / 币种(最小单位)
statusAPPROVED(已通过,进入出款)或 FROZEN(转人工审批)
review_required是否需人工审批(true 时 status=FROZEN)

响应示例:

json
{
  "code": "0",
  "msg": "OK",
  "data": {
    "platform_order_no": "P20260601123456efgh",
    "mch_order_no": "PO20260601001",
    "amount": 500000,
    "fee": 6000,
    "currency": "PHP",
    "status": "APPROVED",
    "review_required": false
  }
}

查询 POST /payout/query ​

请求业务参数(另带 公共参数):

字段必填说明
mch_order_no二选一商户订单号
platform_order_no二选一平台订单号(建议只传一个)

请求示例:

json
{
  "merchant_no": "M100001",
  "app_id": "app_10001",
  "key_version": 1,
  "timestamp": 1769990800,
  "nonce": "d4e5f6a1b2c3d4e5",
  "sign_type": "RSA2",
  "platform_order_no": "P20260601123456efgh",
  "sign": "BASE64_SIGNATURE"
}

响应 data 字段:

字段说明
platform_order_no / mch_order_no订单号
amount / fee / currency金额 / 手续费 / 币种(最小单位)
status订单状态,见 订单状态
finished_at终态时间(Unix 秒;终态时返回)
reversed_at冲正时间(Unix 秒;订单被冲正时返回)
fail_reason失败原因(失败时返回)

响应示例:

json
{
  "code": "0",
  "msg": "OK",
  "data": {
    "platform_order_no": "P20260601123456efgh",
    "mch_order_no": "PO20260601001",
    "amount": 500000,
    "fee": 6000,
    "currency": "PHP",
    "status": "SUCCESS",
    "finished_at": 1769991200
  }
}

异步回调通知 ​

代付订单到达终态时,平台 POST 通知到你配置的代付回调地址。验签与应答规则同 代收回调(平台私钥签名、按 key_version 选平台公钥、先验签后处理、回 success、递增重试)。

通知字段:

字段说明
platform_order_no / mch_order_no订单号
amount / fee / currency金额 / 手续费 / 币种(最小单位)
status终态:SUCCESS / FAILED / REJECTED,见 订单状态
fail_reason失败原因(失败/拒绝时返回)
key_version平台回调密钥版本
timestamp / nonce / sign_type / sign平台签名公共参数

通知报文示例(成功):

json
{
  "platform_order_no": "P20260601123456efgh",
  "mch_order_no": "PO20260601001",
  "amount": 500000,
  "fee": 6000,
  "currency": "PHP",
  "status": "SUCCESS",
  "key_version": 1,
  "timestamp": 1769991205,
  "nonce": "e5f6a1b2c3d4e5f6",
  "sign_type": "RSA2",
  "sign": "PLATFORM_SIGN_BASE64"
}

通知报文示例(失败):

json
{
  "platform_order_no": "P20260601123456efgh",
  "mch_order_no": "PO20260601001",
  "amount": 500000,
  "fee": 6000,
  "currency": "PHP",
  "status": "FAILED",
  "fail_reason": "UPSTREAM_REJECTED",
  "key_version": 1,
  "timestamp": 1769991205,
  "nonce": "e5f6a1b2c3d4e5f6",
  "sign_type": "RSA2",
  "sign": "PLATFORM_SIGN_BASE64"
}

应答(验签通过且处理成功后,HTTP 200,响应体恰为):

text
success

查询与通知的差别

通知体为终态快照(不含 finished_at/attach);需要终态时间或透传数据时请调用 查询接口。

冲正通知(payout.reversed) ​

代付订单到达终态 SUCCESS 之后,仍可能因上游退票/资金回拨被平台冲正。冲正时平台向同一个代付回调地址追加一条通知,验签与应答规则与上文一致。

  • 识别:冲正通知带 event="payout.reversed",不带 status 字段;普通终态通知带 status、不带 event。请仅按 event 字段路由处理。
  • 订单状态不变:仍为 SUCCESS;查询接口 以 reversed_at 体现。你应将该笔出款在自己系统里标记为已冲正并做资金处理。
  • 幂等:同一订单的冲正通知至多一条(投递重试除外)。去重键 = platform_order_no + 通知类型——不要只按订单号去重,否则冲正通知会被当成已处理的终态通知而忽略。

通知字段:

字段说明
event固定 payout.reversed
reversed_at冲正时间(Unix 秒)
platform_order_no / mch_order_no订单号
amount / fee原单金额 / 原单手续费(最小单位)
currency币种
reversal_amount本次冲正金额(最小单位)
fee_refund退回手续费(最小单位)
key_version / timestamp / nonce / sign_type / sign平台签名公共参数

通知报文示例(冲正):

json
{
  "event": "payout.reversed",
  "reversed_at": 1770099205,
  "platform_order_no": "P20260601123456efgh",
  "mch_order_no": "PO20260601001",
  "amount": 500000,
  "fee": 6000,
  "currency": "PHP",
  "reversal_amount": 500000,
  "fee_refund": 6000,
  "key_version": 1,
  "timestamp": 1770099210,
  "nonce": "a1b2c3d4e5f6a1b2",
  "sign_type": "RSA2",
  "sign": "PLATFORM_SIGN_BASE64"
}

应答规则同上:验签通过且处理成功后返回 HTTP 200 + 纯文本 success。