生产环境
大约 3 分钟
本文梳理生产环境接入流程，覆盖：商户配置、密钥与参数准备、可用接口及回调联调方式。
1. 生产环境信息
- 商户号：所有生产请求的
mchNo都必须用生产商户号。 - 回调联调：回调发送到下单时的
downNotifyUrl，需确保地址可公网访问；代付联调若有 IP 白名单限制，请先确认出口 IP 已加入。
域名说明
| 类型 | 域名 | 适用范围 | 说明 |
|---|---|---|---|
| 统一域名（推荐） | openapi.toppayment.com | 全部法币国家及数字货币 | 法币路径带国家码；数字货币路径为 /crypto/...；原域名可继续使用 |
| 国别域名（兼容） | global-{countryCode}-openapi.toppayment.com | 全部法币国家 | 例如 global-ng-openapi.toppayment.com |
| 数字货币原域名（兼容） | global-digit-openapi.toppayment.com | 数字货币 | 路径仍为 /crypto/... |
示例：
- 推荐（法币）：
https://openapi.toppayment.com/{countryCode}/... - 推荐（数字货币）：
https://openapi.toppayment.com/crypto/... - 兼容老域（法币）：
https://global-{countryCode}-openapi.toppayment.com/{countryCode}/... - 兼容老域（数字货币）：
https://global-digit-openapi.toppayment.com/crypto/...
2. 生产接入前准备
- 获取生产商户配置
在商户后台查看生产 API 配置，获取生产商户号xxxxxx，并配置商户公钥。 - 生成密钥对
建议使用 RSA PKCS#8（推荐 2048 位；仅历史商户可继续使用 1024 位，见签名规则）；保留商户私钥用于签名，公钥上传至后台。
- 平台公钥
从后台获取平台公钥，用于验签平台回调。 - 参数与回调地址
mchNo：生产商户号（必填）sign：按接口规则生成（见签名文档）downNotifyUrl：代收、代付各自的回调地址- 代付联调需确认调用方 IP 在白名单内（如有）
3. 常用接口（生产）
按上表选择 Host 拼接路径。法币推荐：https://openapi.toppayment.com/{countryCode}/...；数字货币推荐：https://openapi.toppayment.com/crypto/...
| 场景 | 路径（生产） | 说明 |
|---|---|---|
| 代收下单 | /{countryCode}/pay/prePay | method 见支付方式表 |
| 代收查询 | /{countryCode}/pay/query | 支持 orderNum / platOrderNum |
| 代付下单 | /{countryCode}/disbursement/cash | bankCode 见代付银行表 |
| 代付查询 | /{countryCode}/disbursement/query | 支持 orderNum / platOrderNum |
| 账号校验 | /{countryCode}/disbursement/bankVerify | 印尼已开放；仅生产环境；同步返回，无回调 |
| 余额查询 | /{countryCode}/balance/v1 | 传入 currency |
countryCode对照：ph（菲律宾）、id（印尼）、ng（尼日利亚）、in（印度）、th（泰国）、vn（越南）、pe（秘鲁）、br（巴西）、mx（墨西哥）、co（哥伦比亚）、bo（玻利维亚）、pk（巴基斯坦）、bd（孟加拉）。
4. 回调与状态模拟
- 下单时填写的
downNotifyUrl会在生产内被调用（代收、代付各自独立）。 - 业务侧请记录回调并按签名规则验签。