数币收单开放 API 文档Digital Acquire Open API

环境与访问方式Environment & access

商户在开放平台完成开户后获得 X-App-Id、RSA 密钥材料、是否 IP 白名单等。路由与权限由平台后台配置。After onboarding you receive X-App-Id, RSA key material, optional IP allowlists, etc. Routes and permissions are configured in the platform console.

请求约定Request conventions

HTTP 头（必填）Required HTTP headers

Content-Type: application/json

请求体Request body

外层固定为密文包装：Outer envelope is always encrypted:

{ "data": "<RSA ciphertext Base64>" }

明文为各接口业务 JSON（UTF-8），使用平台下发的加密公钥加密。签名字符串：Plaintext is per-API business JSON (UTF-8), encrypted with the platform encryption public key. Sign string:

X-App-Id + ";" + X-Timestamp + ";" + X-Nonce + ";POST;" + plaintext JSON

使用商户签名私钥签名；网关用平台验签公钥校验。密钥命名以运营说明为准。Sign with the merchant signing private key; the gateway verifies with the platform public key. Key naming follows operations’ guide.

响应体Response body

{
  "code": "0000",
  "message": "Success",
  "data": "<RSA ciphertext Base64>"
}

使用商户解密私钥解密 data。内层常见字段：Decrypt data with the merchant private key. Inner fields often include:

响应头可能含 X-Sign、X-Timestamp、X-Nonce，验签规则以运营细则为准。Response may include X-Sign, X-Timestamp, X-Nonce; verify per operations’ rules.

收单类开放接口（7 个）Acquire APIs (7)

以下路径接在 {BASE}/api/route 之后。若环境配置了版本或前缀，以运营确认为准。Append these paths after {BASE}/api/route. Version or prefix overrides follow operations.

示例（占位）：Example (placeholder): POST {BASE}/api/route/orderApi/createPaymentOrder

测试环境完整示例：UAT full URL example: POST http://open.saferoute.global:16000/api/route/orderApi/createPaymentOrder

查询链路 / 币种 — getDepositInfoChains & tokens — getDepositInfo

请求明文Request plaintext

响应 data（数组）Response data (array)

链路列表元素字段：Each chain item includes: chainName, regular, chainId, coinTokenModels.

coinTokenModels

创建收单订单 — createPaymentOrderCreate order — createPaymentOrder

请求明文Request plaintext

响应 dataResponse data

收单订单列表 — queryAcquireOrderListOrder list — queryAcquireOrderList

商户范围由网关根据 X-App-Id 识别，请求体一般无需再传 memberId。Merchant scope comes from X-App-Id; you usually omit memberId in the body.

请求明文Request plaintext

响应 data（分页）Response data (page)

rows 单项rows item

收单订单详情 — queryAcquireOrderOrder detail — queryAcquireOrder

请求明文Request plaintext

响应 data 字段Response data fields

paymentResult

refundInfo

创建退款 — createRefundOrderCreate refund — createRefundOrder

请求明文Request plaintext

响应 dataResponse data

查询退款 — queryRefundOrderQuery refund — queryRefundOrder

请求明文Request plaintext

响应 data 字段Response data fields

更新收单支付信息 — updatePayInfoUpdate pay info — updatePayInfo

请求明文Request plaintext

响应 dataResponse data

异步通知（商户服务端）Webhooks (merchant server)

收单订单状态 — memberNotifyUrlOrder status — memberNotifyUrl

订单状态变更后 POST JSON，常见字段包括：memberOrderNo、outTradeNo、chainId、description、quoteCurrencySymbol、quoteAmount、userWalletAddress、saltHash、paymentStatus、时间字段、支付金额/手续费/币种、remark，以及退款相关字段（有则返回）。On status change, platform POSTs JSON. Typical fields: memberOrderNo, outTradeNo, chainId, description, quoteCurrencySymbol, quoteAmount, userWalletAddress, saltHash, paymentStatus, timestamps, paid amount/fee/currency, remark, and refund fields when applicable.

回执： HTTP Body 建议返回 JSON，且 code 整型为 200 表示接收成功，否则平台可能重试。Ack: Respond with JSON whose integer code is 200 for success; otherwise retries may occur.

退款结果 — refundCallbackUrlRefund result — refundCallbackUrl

常见字段：refundOrderNo、memberOrderNo、outTradeNo、refundAmount、refundSymbol、amountFee、toAddress、refundStatus、refundRemark、refundHash。成功回执约定同上。Typical fields: refundOrderNo, memberOrderNo, outTradeNo, refundAmount, refundSymbol, amountFee, toAddress, refundStatus, refundRemark, refundHash. Same ack rules as above.

安全与联调清单Security & UAT checklist

• 密钥勿入仓库；生产与测试密钥分离。Never commit keys; separate prod and test secrets.
• 仅调用本文档列出的开放路径。Call only documented open paths.
• 时间戳、随机串、流水号与 HTTPS 通知按规范实现。Implement timestamps, nonce, request id, and HTTPS webhooks per spec.

商户侧检查清单Merchant checklist

• 已获得 X-App-Id 与 RSA 密钥材料Received X-App-Id and RSA key material
• 已实现请求加密、签名及响应解密、验签Request encrypt/sign and response decrypt/verify implemented
• 已在测试环境验证 7 个接口All seven APIs verified in test
• 已实现异步通知并按约定返回成功标识Webhooks implemented with correct success marker
• 已确认幂等与时间戳窗口策略Idempotency and timestamp window agreed