接入与认证
接入凭证#
平台按测试和生产环境分别提供 API Base URL、merchant_id(Merchant Code)、api_key 和 api_secret。两个环境的地址、凭证和订单互不通用;Secret 只保存在商户服务端。
代收、代付均使用自由匹配 Key(merchant_global),不绑定特定通道。一个 Key 可获授权多个支付类型和交易币种。
每笔请求只传一个 currency,由创建接口决定代收或代付,并要求对应权限。收银台仅展示当前商户已启用且符合订单条件的通道,由用户选择。
| 接口 | 权限 | 用途 |
|---|---|---|
POST /api/v1/pay/create |
create_pay_order |
创建代收会话 |
POST /api/v1/pay/query |
query_pay_order |
查询代收 |
POST /api/v1/payout/create |
create_payout_order |
创建代付会话 |
POST /api/v1/payout/query |
query_payout_order |
查询代付 |
POST /api/v1/balance/query |
query_balance |
查询余额 |
POST /api/v1/currency/options |
仅有效 API Key token | 查询平台币种目录 |
POST /api/v1/bank/options |
仅有效 API Key token | 按币种查询平台银行与支付代码 |
POST /api/v1/channel/options |
按选项类型,见 5.2.3 | 查询通道可用选项 |
通用请求参数#
所有接口使用 HTTPS、POST 和 Content-Type: application/json。currency/options 与 bank/options 仅使用 API Key token,见 5.2.1、5.2.2;其他接口要求以下签名字段,接口参数表只列业务字段。
| 字段 | 类型 | 说明 |
|---|---|---|
api_key |
string | 当前环境对应的 API Key |
merchant_id |
string | API Key 绑定的 Merchant Code |
timestamp |
string | 当前 Unix 秒时间戳 |
nonce |
string | 每次请求生成的新随机串 |
sign |
string | 64 位小写 HMAC-SHA256 签名 |
请求体须为单层 JSON 对象,不接受数组、嵌套对象、null、重复字段或尾随 JSON;最大 64 KiB、最多 64 个字段。金额使用十进制字符串,币种使用大写代码。时间字段使用 RFC 3339,示例中的 Z 表示 UTC。
X-Request-ID 可选,允许 1–64 个 ASCII 字母、数字、.、_、:、-。签名接口配置 IP 白名单后,调用服务器公网 IP 必须命中;未配置时不限制来源 IP。
签名#
签名算法:HMAC-SHA256
- 从请求参数中移除
sign。 - 移除值为空字符串的字段。
- 按字段名 ASCII 升序排序。
- 使用原始标量字符串拼接
key=value。 - 使用
&连接,不进行 URL Encode。 - 使用
api_secret作为 HMAC key 计算 SHA-256。 - 输出 64 位小写十六进制字符串。
固定签名示例:
API Secret: test_secret_123
Canonical String:
api_key=test_key&merchant_id=merchant_1001&nonce=nonce_001&platform_order_no=P202608120001×tamp=1786502400
Signature:
03b28189b1d613de76f444db1ffb834daefd609e2eee65d4871b34db8818bd73
时间窗口由平台配置,通常为前后 300 秒。同一 API Key 在有效窗口内不得重复使用 nonce;每次重试重新生成 timestamp、nonce 和 sign。