跨境支付沙盒 · 接入文档Cross-border Payment Sandbox · Integration Docs

本沙盒是一个 Antom(Alipay+)兼容的模拟收单环境。把你对接 Antom 的代码网关指向本沙盒、用你的 sandbox API Key,即可联调收银台、回调、多钱包、各类失败场景;调通后把网关换回真 Antom + 真凭据,代码直接复用。沙盒全程模拟,不扣真钱。

1. 快速开始 / Quick Start

在首页选择行业(游戏 / 跨境)→ 同意服务协议 → 付 199 RM 技术服务接入费。
付款成功后页面显示你的 sandbox API Key(仅显示一次,请立即保存)。
用该 Key 调用下面的端点,照场景跑通对接。

Base URL: https://jiandtc.space/api/sandbox/v1

自检 Key 是否可用:

curl -H "X-API-Key: <你的KEY>" https://jiandtc.space/api/sandbox/v1/ping
# → {"ok":true,"scopes":["sandbox:test"],"industry":"game"}

2. 鉴权 / Authentication

每个请求带请求头 X-API-Key: <你的KEY>。沙盒 Key 仅能访问 /api/sandbox/v1/*,不能访问生产接口。

3. 端点 / Endpoints

POST /payments/create — 建支付(充值/内购/收款)

curl -X POST https://jiandtc.space/api/sandbox/v1/payments/create \
  -H "X-API-Key: <KEY>" -H "Content-Type: application/json" \
  -d '{
    "paymentRequestId": "your_unique_id_001",
    "order": { "referenceOrderId": "role#8821",
               "orderAmount": { "currency": "MYR", "value": "990" } },
    "paymentMethod": { "paymentMethodType": "TNG" },
    "paymentNotifyUrl": "https://你的服务器/antom/callback"
  }'
# → { "result":{"resultStatus":"S"}, "paymentRequestId":"...", "paymentId":"...",
#     "paymentSessionData":"...", "normalUrl":"https://jiandtc.space/sandbox/cashier/..." }

钱包 paymentMethodType:TNG / BOOST(MYR)、ALIPAY_CN(CNY)、ALIPAY_HK(HKD)。约 2 秒后我们向你的 paymentNotifyUrl 发送签名结果通知(见第 5 节)。

POST /payments/inquiry — 查支付状态(超时自查)

curl -X POST .../payments/inquiry -H "X-API-Key: <KEY>" \
  -d '{"paymentRequestId":"your_unique_id_001"}'
# → {"result":{...},"paymentStatus":"SUCCESS|PROCESSING|FAIL"}

POST /refunds — 退款

curl -X POST .../refunds -H "X-API-Key: <KEY>" \
  -d '{"paymentId":"<上一笔 paymentId>","refundAmount":{"currency":"MYR","value":"990"}}'

POST /agreements/sign + /payments/auto-debit — 订阅 / 自动扣款 / 续费

# 1) 签约拿 accessToken
curl -X POST .../agreements/sign -H "X-API-Key: <KEY>" -d '{"agreementRequestId":"sub_001"}'
# → {"accessToken":"sbxtoken_..."}
# 2) 用 accessToken 扣款(续费 = 用同一 token 再调一次)
curl -X POST .../payments/auto-debit -H "X-API-Key: <KEY>" \
  -d '{"accessToken":"sbxtoken_...","paymentAmount":{"currency":"MYR","value":"1990"},
       "paymentNotifyUrl":"https://你的服务器/antom/callback"}'

⚠️ 订阅/自动扣款在沙盒可模拟测试;真上线需向 Antom 单独开通 Auto Debit 合约。

GET /scenarios?industry=game|crossborder — 行业测试包

返回该行业的测试场景清单(每个场景含端点、示例参数、magic value、预期结果)。

4. 失败场景主动触发 / Failure Simulation(核心)

用金额尾数主动触发各种结果,测你的系统对失败的处理:

金额 value 尾数	结果	回调行为
正常(如 990)	SUCCESS 成功	~2s 后成功通知
`…11`(如 911)	DECLINED 拒付	失败通知 `PAYMENT_FAILED`
`…22`(如 922)	TIMEOUT 超时	不发回调 → 用 inquiry 自查
`…33`(如 933)	WEBHOOK_FAIL	第1次坏签名(你应拒绝)+ 重试发正确(你应接受且幂等)
`…44`(如 944)	INSUFFICIENT_BALANCE	失败通知 `INSUFFICIENT_BALANCE`

5. 回调通知与验签 / Webhook & Signature

支付结果由我们 POST 到你的 paymentNotifyUrl,通知体为 Antom 形态:

{ "notifyType":"PAYMENT_RESULT",
  "result":{"resultStatus":"S","resultCode":"SUCCESS"},
  "paymentRequestId":"your_unique_id_001", "paymentId":"sbxpay_...",
  "paymentAmount":{"currency":"MYR","value":"990"} }

请求头带签名(与 Antom 一致):

client-id: CUBE_SANDBOX
request-time: 2026-06-03T15:00:00.000+08:00
signature: algorithm=RSA256,keyVersion=1,signature=<urlencoded base64>

验签(SHA256withRSA):签名串 = "POST " + 你的回调path + "\n" + client-id + "." + request-time + "." + body,用沙盒公钥验。沙盒公钥:/assets/sandbox_webhook_public_key.pem

切换到真 Antom 时:验签代码不变,只把公钥换成 Antom 平台公钥、client-id 从请求头动态读取即可。

6. 切回真 Antom / Go Live

网关地址:沙盒 https://jiandtc.space/api/sandbox/v1 → 真 Antom https://open-sea-global.alipay.com
凭据:沙盒 Key → 你自己的 Antom clientId + 私钥
验签公钥:沙盒公钥 → Antom 平台公钥
请求/响应/回调体结构一致,业务代码无需改。

7. 服务边界 / Scope

本服务为支付对接测试环境技术服务,非真实收单,不持有客户资金。详见《跨境支付沙盒服务协议》。