中国代收（Payin）

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

创建代收订单

创建一笔中国代收订单。merchantOrderNo 在商户维度须唯一。

接口

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

请求体

字段	类型	必填	说明
merchantOrderNo	string	是	商户订单号，唯一
countryCode	string	是	CN
currency	string	是	CNY
amount	string/number	是	代收金额，> 0
notifyUrl	string	否	本单回调地址；为空则使用商户默认配置
metadata	object	否	付款方信息、业务单号等

响应 data 字段

字段	说明
orderNo	平台订单号（PI 前缀）
merchantOrderNo	商户订单号
amount / feeAmount / netAmount	金额字符串
status	初始为 created
createdAt	创建时间

cURL 示例

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"CNPAYIN20260608001","countryCode":"CN","currency":"CNY","amount":"5000.00","notifyUrl":"https://merchant.soranopro.com/cn/payin/cb"}'

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": "PI20260608150000666666",
    "merchantOrderNo": "CNPAYIN20260608001",
    "countryCode": "CN",
    "currency": "CNY",
    "amount": "5000.00",
    "feeAmount": "15.00",
    "netAmount": "4985.00",
    "status": "created",
    "createdAt": "2026-06-08T15:00:00Z"
  }
}

查询代收订单

接口

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

Query 参数（二选一）

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

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

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PI20260608150000666666",
    "merchantOrderNo": "CNPAYIN20260608001",
    "countryCode": "CN",
    "currency": "CNY",
    "amount": "5000.00",
    "feeAmount": "15.00",
    "netAmount": "4985.00",
    "status": "completed",
    "completedAt": "2026-06-08T15:30:00Z",
    "createdAt": "2026-06-08T15:00:00Z"
  }
}

异步回调

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

平台在代收订单 完成（status=completed）后，向创建时传入的 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": "PI20260608150000666666",
  "merchantOrderNo": "CNPAYIN20260608001",
  "status": "completed",
  "amount": "5000.00",
  "feeAmount": "15.00",
  "netAmount": "4985.00",
  "currency": "CNY",
  "countryCode": "CN",
  "completedAt": 1718209200
}

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

商户响应

处理成功须返回：

• HTTP 200
• Body 纯文本 OK

注意事项

1. 仅 终态 completed 会推送回调（失败/取消无回调，以查询接口为准）
2. 可能重复通知，请按 merchantOrderNo / orderNo 幂等更新
3. 必须先验签 再改订单状态

订单状态

status	说明
created	已创建，待平台确认入款
processing	处理中（预留）
completed	已完成，已入账并回调
failed	失败
cancelled	已取消