5 分钟测通你的对接
用我们公开的 沙箱 API 环境,配套共享的测试凭证。不会有真实扣款,订单也不会到达真正的支付服务商。
第 1 步:拿到沙箱凭证
打开 /sandbox,复制 App ID、API Key(用于签名)和 Query Key(用于查单)。
第 2 步:创建一笔测试订单
用沙箱页面上的表单,或者向 /api/createorder 发一个带签名的 POST:
curl -X POST "https://your-domain.com/api/createorder" \
-H "Content-Type: application/json" \
-d '{
"appid": "YOUR_SANDBOX_APPID",
"action": "createorder",
"clientip": "127.0.0.1",
"amount": "9.99",
"currency": "USD",
"paymentMethod": "alipay",
"description": "Test order",
"notify_url": "https://your-domain.com/api/sandbox/webhook-receiver",
"sign_type": "MD5",
"sign": "CALCULATED_MD5_SIGN"
}'MD5 签名沙箱页面会替你算好。算法见 API 文档的签名一节。
第 3 步:模拟支付
打开创建订单响应里的 redirectUrl(或者在沙箱页面上点 Simulate pay)。点 Simulate Success,网关就会把一个 Webhook 排队发到你的 notify_url。
第 4 步:验证 Webhook 签名
回调用 GET 发送,查询参数里包含 sign 和 sign_type=MD5。用和创建订单相同的算法、配你的 API Key 来验证。
// Node.js example (conceptual)
const crypto = require('crypto');
function verifyCallback(params, apiKey) {
const copy = { ...params };
delete copy.sign;
delete copy.sign_type;
const keys = Object.keys(copy).filter(k => copy[k] != null).sort();
const str = keys.map(k => k + '=' + copy[k]).join('&') + apiKey;
const expected = crypto.createHash('md5').update(str).digest('hex');
return expected === params.sign;
}你的服务器必须返回纯文本 success(不区分大小写)。
第 5 步:查询订单状态
GET /api/order?action=order&appid=APPID&key=QUERY_KEY&paymentId=ORDER_ID或者轮询这个公开接口:GET /api/order/status/:orderId
准备上生产
- 注册商户账号,换成你生产环境的
appid、apikey和key。 - 在账户设置里,或者按单设置你真实的
notify_url。 - 绝对不要把 API Key 暴露在前端代码里。
- Webhook 签名一律在服务端验证。