沙箱环境
大约 3 分钟
本文梳理沙箱环境接入流程，覆盖：沙箱/正式差异、商户配置、密钥与参数准备、可用接口及回调联调方式。
1. 沙箱要点
- 商户号前缀：沙箱商户号需带
SD前缀，例如正式123456→ 沙箱SD123456。所有沙箱请求的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/sandbox/{countryCode}/... - 推荐（数字货币）：
https://openapi.toppayment.com/crypto/sandbox/... - 兼容老域（法币）：
https://global-{countryCode}-openapi.toppayment.com/sandbox/{countryCode}/... - 兼容老域（数字货币）：
https://global-digit-openapi.toppayment.com/crypto/sandbox/...
2. 对接前准备
- 获取沙箱商户配置
在商户后台查看沙箱 API 配置，获取沙箱商户号SDxxxxxx，并配置商户公钥。 - 生成密钥对
建议使用 RSA PKCS#8（推荐 2048 位；仅历史商户可继续使用 1024 位，见签名规则）；保留商户私钥用于签名，公钥上传至后台。
- 平台公钥
从后台获取平台公钥，用于验签平台回调。 - 参数与回调地址
mchNo：沙箱商户号（必填）sign：按接口规则生成（见签名文档）downNotifyUrl：代收、代付各自的回调地址- 代付联调需确认调用方 IP 在白名单内（如有）
3. 常用接口（沙箱）
按上表选择 Host 拼接路径。法币推荐：https://openapi.toppayment.com/sandbox/{countryCode}/...；数字货币推荐：https://openapi.toppayment.com/crypto/sandbox/...
| 场景 | 路径（沙箱） | 说明 |
|---|---|---|
| 代收下单 | /sandbox/{countryCode}/pay/prePay | method 见支付方式表 |
| 代收查询 | /sandbox/{countryCode}/pay/query | 支持 orderNum / platOrderNum |
| 代付下单 | /sandbox/{countryCode}/disbursement/cash | bankCode 见代付银行表 |
| 代付查询 | /sandbox/{countryCode}/disbursement/query | 支持 orderNum / platOrderNum |
| 余额查询 | /sandbox/{countryCode}/balance/v1 | 传入 currency |
countryCode对照：ph（菲律宾）、id（印尼）、ng（尼日利亚）、in（印度）、th（泰国）、vn（越南）、pe（秘鲁）、br（巴西）、mx（墨西哥）、co（哥伦比亚）、bo（玻利维亚）、pk（巴基斯坦）、bd（孟加拉）。
4. 回调与状态模拟
- 下单时填写的
downNotifyUrl会在沙箱内被调用（代收、代付各自独立）。 - 若需手动模拟：可在后台的订单详情页使用“更改订单状态”“发送通知”等按钮，改变订单状态并触发回调。
- 业务侧请记录回调并按签名规则验签。