巴基斯坦代收（Payin）

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

国家与币种

巴基斯坦商户的 countryCode、currency 由 商户号 自动识别（PK / PKR），创建订单时 无需 在请求体中传递。

notifyUrl 说明

请求中的 notifyUrl 仅用于 平台向商户 推送订单结果，不会 转发给任何上游渠道。平台向上游下单时使用自己的回调地址；上游通知平台后，平台再 POST 到您的 notifyUrl。详见 异步回调指南。

创建代收订单

创建一笔巴基斯坦代收订单。merchantOrderNo 在商户维度须唯一。

接口

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

请求体

字段	类型	必填	说明
merchantOrderNo	string	是	商户订单号，唯一
amount	string/number	是	代收金额，> 0，最多 2 位小数
bankCode	string	建议	支付渠道编码，见 代收 bankCode 枚举
notifyUrl	string	否	本单完成回调地址；为空则不推送（仍可用查询接口）
remark	string	否	备注
payer_mobile	string	是	付款人手机，必填且须为真实巴基斯坦号码：03 开头共 11 位（如 03001234567）。平台会校验格式并用于上游下单，请勿传虚拟号或占位号
payer_realname	string	建议	付款人姓名
payer_email	string	建议	付款人邮箱
payer_id_no	string	否	付款人证件号（如 CNIC）
extJson	object	否	扩展字段（对象），平台存库；不要 使用已废弃的 metadata

已废弃字段

请勿再传 countryCode、currency、metadata。付款人信息请使用 payer_* 前缀字段；扩展信息使用 extJson。

兼容说明

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

PKR 代收 · payer_mobile

巴基斯坦 PKR 代收创建时 payer_mobile 必填，且须为付款人真实在用的巴基斯坦手机号（03 + 9 位数字，共 11 位）。格式错误或虚假号码可能导致下单失败或渠道拒单。

响应 data 字段

字段	说明
orderNo	平台订单号（PI 前缀）
merchantOrderNo	商户订单号
amount / feeAmount / netAmount	金额字符串
status	初始多为 created 或 processing
payUrl	收银链接（路由到上游渠道时可能返回）
payQr	支付码（部分渠道）
createdAt	创建时间

请求示例

{
  "merchantOrderNo": "PKPAYIN20260622001",
  "amount": "1000.00",
  "bankCode": "QRANDLAUNCH",
  "notifyUrl": "https://merchant.example.com/pk/payin/cb",
  "remark": "pay",
  "payer_mobile": "03001234567",
  "payer_realname": "Jack",
  "payer_email": "pay@example.com",
  "payer_id_no": "4220112345678",
  "extJson": {}
}

cURL 示例

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"PKPAYIN20260622001","amount":"1000.00","bankCode":"QRANDLAUNCH","notifyUrl":"https://merchant.example.com/pk/payin/cb","payer_mobile":"03001234567","payer_realname":"Jack","payer_email":"pay@example.com","extJson":{}}'

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": "PI20260622140000888888",
    "merchantOrderNo": "PKPAYIN20260622001",
    "amount": "1000.00",
    "feeAmount": "10.00",
    "netAmount": "990.00",
    "status": "processing",
    "payUrl": "https://checkout.example.com/pay/xxx",
    "createdAt": "2026-06-22T14:00:00Z"
  }
}

查询代收订单

接口

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

Query 参数（二选一）

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

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

异步回调

收到回调后的验签、幂等处理、应答 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": "PI20260622140000888888",
  "merchantOrderNo": "PKPAYIN20260622001",
  "status": "completed",
  "amount": "1000.00",
  "feeAmount": "10.00",
  "netAmount": "990.00",
  "completedAt": 1718202000
}

商户响应

处理成功须返回 HTTP 200，Body 纯文本 OK。

注意事项

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

订单状态

status	说明
created	已创建
processing	处理中（含上游收银）
completed	已完成，已入账并回调
failed	失败
cancelled	已取消