巴基斯坦 · 介绍
本文档描述 SoPay 在巴基斯坦的 商户对接 API：代收（Payin）、代付（Payout）、商户钱包与异步回调。
环境与地址
| 环境 | API Base（示例，以运维下发为准） |
|---|---|
| 生产 | https://api.soranopro.com |
| 沙盒 | https://sandbox-api.soranopro.com |
完整路径示例：POST {API_BASE}/api/v1/merchant/payin/create
详见 环境说明。
商户身份与密钥
| 项目 | 说明 |
|---|---|
商户号 merchantNo | 开户后分配，放在 Header X-Merchant-No |
| 商户 RSA 密钥对 | 商户私钥签名 出站请求；公钥提交给平台 |
| 平台 RSA 公钥 | 用于验证 平台异步回调 签名 |
| 国家/币种 | 由商户号绑定；创建与查询代收/代付响应均不返回 countryCode、currency |
鉴权与签名详见 签名与商户 API 规范。
回调链路（重要）
商户 API 请求 notifyUrl → 仅存平台订单，不转发上游
平台 → 上游下单 → 使用平台自有 webhook
上游 → 平台 → 验签、更新订单
平台 → 商户 notifyUrl → RSA2 签名 POST，商户验签后返回 OK商户只需实现 接收平台回调；无需关心上游渠道地址。
API 一览
| 能力 | Method | Path |
|---|---|---|
| 创建代收 | POST | /api/v1/merchant/payin/create |
| 查询代收 | GET | /api/v1/merchant/payin/query |
| 创建代付 | POST | /api/v1/merchant/payout/create |
| 查询代付 | GET | /api/v1/merchant/payout/query |
| 商户钱包 | GET | /api/v1/merchant/wallet |
| 钱包流水 | GET | /api/v1/merchant/wallet/transactions |
请求体规范摘要
| 类型 | 必填要点 |
|---|---|
| 代收 | merchantOrderNo、amount；payer_mobile 必填（真实巴基斯坦手机号）；建议 bankCode、payer_realname、payer_email |
| 代付 | merchantOrderNo、amount、bankCode、payee_realname、payee_account；建议 payee_mobile、payee_email、payee_id_no |
- 付款人字段前缀：
payer_* - 收款人字段前缀：
payee_* - 扩展信息：
extJson（对象），勿用metadata - 备注：顶层
remark
业务流程概览
代收（Payin）
- 商户 创建代收 → 可能返回
payUrl等收银信息 - 付款完成 → 订单
completed，商户钱包增加netAmount（amount - fee） - 平台向
notifyUrl发送status=completed回调
代付（Payout）
- 商户 创建代付 → 冻结
netAmount（amount + fee） - 出款完成 → 订单
completed - 平台向
notifyUrl（或默认callbackUrl）发送回调
代付前请保证钱包 可用余额 充足。
巴基斯坦业务要点
| 项 | 说明 |
|---|---|
| 币种 | PKR，金额最多 2 位小数 |
代收 bankCode | 见 附录 · 代收 bankCode |
代付 bankCode | 见 附录 · 代付 bankCode（含银行与钱包） |
手续费说明
| 类型 | 计费 | 商户侧金额 |
|---|---|---|
| 代收 Payin | fee = amount × rate + fixed | netAmount = amount - fee（入账） |
| 代付 Payout | fee = amount × rate + fixed | netAmount = amount + fee（出账冻结） |
具体费率由运营在后台为商户配置。