泰国代付（Payout）

商户 API 前缀：/api/v1/merchant。鉴权 Header 见签名规范。

创建代付订单

创建泰国代付订单。成功创建后将冻结商户钱包 netAmount（amount + fee）。国家与币种由商户号绑定，泰国固定为 TH / THB，请求体无需传 countryCode、currency。

接口

项目	值
Method	`POST`
Path	`/api/v1/merchant/payout/create`

请求体

字段	类型	必填	说明
`merchantOrderNo`	string	是	商户订单号，唯一
`amount`	string/number	是	THB 代付金额，最多 2 位小数
`bankCode`	string	是	代付银行编码，见泰国首页 bankCode 枚举
`payee_realname`	string	是	收款人姓名
`payee_account`	string	是	收款银行账号
`payee_mobile`	string	建议	收款人手机号
`payee_email`	string	建议	收款人邮箱
`payee_id_no`	string	否	收款人证件号，可传空字符串
`notifyUrl`	string	否	本单回调；为空则用商户默认 `callbackUrl`
`remark`	string	否	订单备注
`extJson`	object	否	扩展信息；无扩展时传 `{}`

历史字段 bankName 可继续传入，平台会兼容接收但不会参与路由、费率匹配或上游请求；新接入请只传 bankCode。

bankCode 枚举

创建泰国代付订单时，请在请求体中传字段 "bankCode": "{下表编码}"。只传 bankCode 列的值，BankId 和 银行名称 不是请求字段。

BankId	bankCode	银行名称
`1001`	`BAAC`	BANK FOR AGRICULTURE AND AGRICULTURAL COOPERATIVES
`1002`	`BAY`	BANK OF AYUDHYA PUBLIC COMPANY LIMITED
`1003`	`BBL`	BANGKOK BANK PUBLIC COMPANY LTD.
`1004`	`CITI`	CITIBANK, N.A.
`1005`	`GHB`	THE GOVERNMENT HOUSING BANK
`1006`	`GSB`	THE GOVERNMENT SAVINGS BANK
`1007`	`KBANK`	KASIKORNBANK PUBLIC COMPANY LTD.
`1008`	`KTB`	KRUNG THAI BANK PUBLIC COMPANY LTD.
`1009`	`LHBANK`	LAND AND HOUSES BANK PUBLIC COMPANY LIMITED
`1010`	`SCB`	SIAM COMMERCIAL BANK PUBLIC COMPANY LTD
`1012`	`TISCO`	TISCO BANK PUBLIC COMPANY LIMITED
`1014`	`TTB`	TMBTHANACHART BANK PUBLIC COMPANY LIMITED
`1015`	`CIMB`	CIMB THAI BANK PUBLIC COMPANY LTD.
`1023`	`UOBT`	UNITED OVERSEAS BANK (THAI) PUBLIC COMPANY LIMITED
`1018`	`KKP`	KIATNAKIN BANK PUBLIC COMPANY LIMITED

响应 `data` 字段

字段	说明
`orderNo`	平台订单号（`PO` 前缀）
`merchantOrderNo`	商户订单号
`status`	成功创建后通常为 `processing`
`payoutMethod`	泰国银行代付返回 `BANK_TRANSFER`
`netAmount`	实际冻结金额（含手续费）
`createdAt`	Unix 秒级时间戳

cURL 示例

bash

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"PAYOUT-20260719-115249-005","amount":"500","bankCode":"GSB","payee_realname":"NGUYEN VAN A","payee_account":"0123456789","payee_mobile":"84901234567","payee_email":"[email protected]","payee_id_no":"","notifyUrl":"https://merchant.example.com/callback/payout","remark":"","extJson":{}}'

curl -X POST "${API_BASE}/api/v1/merchant/payout/create" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-No: M42" \
  -H "X-Timestamp: 1718198400" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Sign: ${SIGN}" \
  -d "${BODY}"

响应示例

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PO20260608120000123456",
    "merchantOrderNo": "PAYOUT-20260719-115249-005",
    "amount": "500",
    "feeAmount": "25",
    "netAmount": "525",
    "status": "processing",
    "payoutMethod": "BANK_TRANSFER",
    "createdAt": 1784433642
  }
}

失败场景

msg（示例）	原因
`merchant balance insufficient`	钱包可用余额不足
`merchant order no already exists`	`merchantOrderNo` 重复

查询代付订单

接口

项目	值
Method	`GET`
Path	`/api/v1/merchant/payout/query`

Query 参数（二选一）

参数	说明
`orderNo`	平台订单号
`merchantOrderNo`	商户订单号

异步回调

收到回调后的验签、幂等处理、应答 OK 与重试策略，见 异步回调接入指南。

代付订单进入终态（completed / failed / timeout）后，平台 POST 至 notifyUrl 或商户默认 callbackUrl。

Body 示例

json

{
  "orderType": "payout",
  "orderNo": "PO20260608120000123456",
  "merchantOrderNo": "PAYOUT20260608001",
  "status": "completed",
  "amount": "1000.00",
  "feeAmount": "10.00",
  "netAmount": "1010.00",
  "failureReason": "",
  "completedAt": 1718198400
}

Header 签名机制与代收回调相同，使用 平台公钥 验签。

商户响应

HTTP 200 + Body OK

注意事项

终态 completed / failed / timeout 会推送回调
重复通知请幂等处理
代付进行中状态可通过查询接口轮询：created → processing → completed

订单状态

status	说明
`created`	创建中（瞬时）
`market_available`	已上架任务市场
`processing`	平台用户已接单
`completed`	代付完成，已扣款并回调
`failed`	创建或执行失败
`timeout`	上游返回超时，冻结款退回
`cancelled`	已取消，冻结款退回

泰国代付（Payout） ​

创建代付订单 ​

接口 ​

请求体 ​

bankCode 枚举 ​

响应 data 字段 ​

cURL 示例 ​

响应示例 ​

失败场景 ​

查询代付订单 ​