泰国代收（Payin）

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

创建代收订单

创建一笔泰国代收订单。merchantOrderNo 在商户维度须唯一。国家与币种由商户号绑定，泰国固定为 TH / THB，请求体无需传 countryCode、currency。

接口

项目	值
Method	POST
Path	/api/v1/merchant/payin/create

请求体

字段	类型	必填	说明
merchantOrderNo	string	是	商户订单号，唯一
amount	string/number	是	THB 代收金额，最多 2 位小数
bankCode	string	是	固定传 QR
notifyUrl	string	否	本单回调地址；为空则使用商户默认配置
remark	string	否	订单备注
payer_mobile	string	否	付款人手机号
payer_realname	string	否	付款人姓名
payer_email	string	否	付款人邮箱
payer_id_no	string	否	付款人证件号
extJson.accountNo	string	是	QR 代收账户号

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

bankCode 枚举

创建泰国代收订单时，请在请求体中传字段 "bankCode": "QR"。

bankCode	说明
QR	泰国 QR 代收

响应 data 字段

字段	说明
orderNo	平台订单号（PI 前缀）
merchantOrderNo	商户订单号
amount / feeAmount / netAmount	金额字符串
status	成功创建后通常为 processing
payUrl / payQr	支付链接 / 二维码内容
createdAt	Unix 秒级时间戳

cURL 示例

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"PAYIN-20260719-115013-002","amount":"1000","bankCode":"QR","notifyUrl":"https://merchant.example.com/callback/payin","remark":"","payer_mobile":"","payer_realname":"","payer_email":"","payer_id_no":"","extJson":{"accountNo":"5555"}}'
# 按 /signature 规则对 BODY 字段 + timestamp + nonce 签名后填入 SIGN

curl -X POST "${API_BASE}/api/v1/merchant/payin/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}"

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PI20260608120000123456",
    "merchantOrderNo": "PAYIN-20260719-115013-002",
    "amount": "1000",
    "feeAmount": "50",
    "netAmount": "950",
    "status": "processing",
    "payUrl": "https://card-h5-test.forapayhub.com/#/CEndRepayment?orderNo=PAYIN2078689080662335488",
    "payQr": "https://card-h5-test.forapayhub.com/#/CEndRepayment?orderNo=PAYIN2078689080662335488",
    "createdAt": 1784433071
  }
}

查询代收订单

接口

项目	值
Method	GET
Path	/api/v1/merchant/payin/query

Query 参数（二选一）

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

GET 请求签名参数来自 Query，并追加 Header 的 timestamp、nonce。

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PI20260608120000123456",
    "merchantOrderNo": "PAYIN20260608001",
    "amount": "2000.00",
    "feeAmount": "20.00",
    "netAmount": "1980.00",
    "status": "completed",
    "completedAt": 1718200200,
    "createdAt": 1718198400
  }
}

异步回调

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

平台在代收订单进入终态（completed / failed / timeout）后，向创建时传入的 notifyUrl 发起 POST。

回调请求

Headers（与商户 API 相同机制）：

Header	说明
Content-Type	application/json
X-Merchant-No	商户号
X-Timestamp	Unix 秒
X-Nonce	UUID
X-Sign	平台 RSA2 签名

Body 示例：

{
  "orderType": "payin",
  "orderNo": "PI20260608120000123456",
  "merchantOrderNo": "PAYIN20260608001",
  "status": "completed",
  "amount": "2000.00",
  "feeAmount": "20.00",
  "netAmount": "1980.00",
  "failureReason": "",
  "completedAt": 1718198400
}

验签时将 Body 字段扁平化后，与 timestamp、nonce 一并参与签名（规则同 签名文档）。

商户响应

处理成功须返回：

• HTTP 200
• Body 纯文本 OK

注意事项

1. 终态 completed / failed / timeout 会推送回调
2. 可能重复通知，请按 merchantOrderNo / orderNo 幂等更新
3. 必须先验签 再改订单状态

订单状态

status	说明
created	已创建，待平台确认入款
processing	处理中
partial_paid	部分支付
completed	已完成，已入账并回调
failed	失败
timeout	上游返回超时
cancelled	已取消