巴基斯坦代付（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	是	代付金额（给收款人的金额）
pay_type	string	否	出款方式：BANK_TRANSFER 或 EWALLET；不传时默认 BANK_TRANSFER
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。

钱包代付必须指定 pay_type

使用 JAZZCASH、EASYPAISA 等电子钱包代付时，必须传 "pay_type":"EWALLET"。平台会按 bankCode 匹配启用且支持代付的 EWALLET 支付工具。银行转账可省略 pay_type，或明确传 "pay_type":"BANK_TRANSFER"。

pay_type 是请求 JSON 的一部分，必须使用最终发送的完整请求体生成 X-Sign。

收款字段填写规则

bankCode 类型	主要填写	说明
钱包（JAZZCASH、EASYPAISA）	payee_mobile	必须传 pay_type=EWALLET；payee_account 可填钱包绑定号作备用
银行（其余 bankCode）	payee_account	pay_type 省略或传 BANK_TRANSFER；payee_mobile 仍建议填写

完整 bankCode 列表见 附录。

响应 data 字段

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

请求示例（钱包）

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

请求示例（银行）

{
  "merchantOrderNo": "PKPAYOUT20260622002",
  "amount": "50000.00",
  "pay_type": "BANK_TRANSFER",
  "bankCode": "HBL",
  "payee_realname": "Ali Khan",
  "payee_account": "0123456789012",
  "payee_mobile": "03001234567",
  "payee_email": "[email protected]",
  "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","pay_type":"EWALLET","bankCode":"JAZZCASH","payee_realname":"Ali Khan","payee_account":"03001234567","payee_mobile":"03001234567","payee_email":"[email protected]","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",
    "payoutMethod": "EWALLET",
    "status": "processing",
    "createdAt": "2026-06-22T14:00:00Z"
  }
}

失败场景

msg（示例）	原因
merchant balance insufficient	钱包可用余额不足
merchant order no already exists	merchantOrderNo 重复
pay_type must be BANK_TRANSFER or EWALLET	pay_type 不是允许值
bankCode is required when pay_type is EWALLET	钱包代付未传 bankCode
EWALLET payment tool not found or payout is disabled for bankCode	未找到与 bankCode 匹配且启用代付的 EWALLET 支付工具
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	已取消，冻结款退回