巴基斯坦代付（Payout）

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

国家与币种

countryCode、currency 由 商户号 自动识别，创建订单时 无需 传递。

notifyUrl 说明

notifyUrl 仅用于平台向商户推送完成通知，不会 传给上游。详见 异步回调指南。

创建代付订单

创建巴基斯坦代付订单。成功后将冻结商户钱包 netAmount（amount + fee）。

接口

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

请求体

字段	类型	必填	说明
merchantOrderNo	string	是	商户订单号，唯一
amount	string/number	是	代付金额（给收款人的金额）
bankCode	string	是	出款渠道编码，大写，见 代付 bankCode 枚举
payee_realname	string	是	收款人姓名
payee_account	string	是	收款账号（银行账号或钱包号）
payee_mobile	string	建议	收款人手机
payee_email	string	建议	收款人邮箱
payee_id_no	string	建议	收款人证件号（CNIC）
notifyUrl	string	否	本单完成回调；为空则使用商户默认 callbackUrl
remark	string	否	备注
extJson	object	否	扩展字段；不要 使用 metadata

已废弃字段

请勿再传 countryCode、currency、metadata，以及旧字段 receiverName、receiverAccount、receiverBankCode、receiverBankName、receiverPhone。

兼容说明

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

收款字段填写规则

bankCode 类型	主要填写	说明
钱包（JAZZCASH、EASYPAISA）	payee_mobile	payee_account 可填钱包绑定号作备用
银行（其余 bankCode）	payee_account	payee_mobile 仍建议填写

完整 bankCode 列表见 附录。

响应 data 字段

字段	说明
orderNo	平台订单号（PO 前缀）
merchantOrderNo	商户订单号
amount / feeAmount / netAmount	金额字符串
payoutTaskId	关联的平台代付任务 ID（P2P 模式）
status	创建后可能为 created、processing、market_available 等
createdAt	创建时间

请求示例（钱包）

{
  "merchantOrderNo": "PKPAYOUT20260622001",
  "amount": "500.00",
  "bankCode": "JAZZCASH",
  "payee_realname": "Ali Khan",
  "payee_account": "03001234567",
  "payee_mobile": "03001234567",
  "payee_email": "pay@example.com",
  "payee_id_no": "8220296123456",
  "notifyUrl": "https://merchant.example.com/pk/payout/cb",
  "remark": "payout",
  "extJson": {}
}

请求示例（银行）

{
  "merchantOrderNo": "PKPAYOUT20260622002",
  "amount": "50000.00",
  "bankCode": "HBL",
  "payee_realname": "Ali Khan",
  "payee_account": "0123456789012",
  "payee_mobile": "03001234567",
  "payee_email": "pay@example.com",
  "payee_id_no": "4220112345678",
  "notifyUrl": "https://merchant.example.com/pk/payout/cb",
  "extJson": {}
}

cURL 示例

API_BASE="https://api.soranopro.com"
BODY='{"merchantOrderNo":"PKPAYOUT20260622001","amount":"500.00","bankCode":"JAZZCASH","payee_realname":"Ali Khan","payee_account":"03001234567","payee_mobile":"03001234567","payee_email":"pay@example.com","payee_id_no":"8220296123456","notifyUrl":"https://merchant.example.com/pk/payout/cb","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}"

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "orderNo": "PO20260622120000999999",
    "merchantOrderNo": "PKPAYOUT20260622001",
    "amount": "500.00",
    "feeAmount": "5.00",
    "netAmount": "505.00",
    "status": "processing",
    "createdAt": "2026-06-22T14:00:00Z"
  }
}

失败场景

msg（示例）	原因
merchant balance insufficient	钱包可用余额不足
merchant order no already exists	merchantOrderNo 重复
upstream bank mapping not found	bankCode 不在支持列表中

创建前请调用 商户钱包 确认 balance >= netAmount。

查询代付订单

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

Query：orderNo 或 merchantOrderNo 二选一。

异步回调

详见 异步回调接入指南。

代付 完成（status=completed）后，平台 POST 至 notifyUrl 或商户默认 callbackUrl。

{
  "orderType": "payout",
  "orderNo": "PO20260622120000999999",
  "merchantOrderNo": "PKPAYOUT20260622001",
  "status": "completed",
  "amount": "500.00",
  "feeAmount": "5.00",
  "netAmount": "505.00",
  "completedAt": 1718198400
}

商户响应：HTTP 200 + Body OK。

订单状态

status	说明
created	已创建
market_available	已上架任务市场（P2P 模式）
processing	处理中
completed	代付完成，已扣款并回调
failed	失败
cancelled	已取消，冻结款退回