中国 · 介绍
本文档描述 SoPay 在中国境内的 商户对接 API：代收（Payin）、代付（Payout）、商户钱包与异步回调。
环境与地址
| 环境 | API Base（示例，以运维下发为准） |
|---|---|
| 生产 | https://api.soranopro.com |
| 沙盒 | https://sandbox-api.soranopro.com |
完整路径示例：POST {API_BASE}/api/v1/merchant/payin/create
详见 环境说明。
商户身份与密钥
| 项目 | 说明 |
|---|---|
商户号 merchantNo | 开户后分配，如 M42，放在 Header X-Merchant-No |
| 商户 RSA 密钥对 | 商户私钥签名请求；公钥提交给平台 |
| 平台 RSA 公钥 | 用于验证平台异步回调签名 |
| 国家/币种 | 中国商户固定为 countryCode=CN、currency=CNY（与开户配置一致） |
鉴权与签名详见 签名与商户 API 规范。
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 |
业务流程概览
代收（Payin）
- 商户调用 创建代收 → 订单状态
created - 平台运营确认入款后完成订单 → 商户钱包增加
netAmount（amount - fee） - 平台向
notifyUrl发送status=completed回调
代付（Payout）
- 商户调用 创建代付 → 冻结钱包
netAmount（amount + fee），创建代付任务 - 平台用户接单并完成付款 → 订单状态
completed - 平台向
notifyUrl（或商户默认callbackUrl）发送回调
代付创建前请保证商户 CNY 钱包 可用余额 充足。
中国业务要点
| 项 | 说明 |
|---|---|
| 币种 | 人民币 CNY |
| 代付 | 一般为 银行转账（BANK_TRANSFER），须填写开户行与账号 |
| 联行号 | receiverBankCode 可填联行号 / 渠道编码（以运营字典为准） |
| 实名 | receiverName 须与银行卡开户名一致 |
| 合规 | 商户须已完成中国侧 KYC/签约；具体准入联系商务 |
手续费说明
| 类型 | 计费 | 商户侧金额 |
|---|---|---|
| 代收 Payin | fee = amount × rate + fixed | netAmount = amount - fee（入账） |
| 代付 Payout | fee = amount × rate + fixed | netAmount = amount + fee（出账冻结） |
具体费率由运营在后台为商户配置。