基本信息

• 接口地址：/api/payment
• 请求方式：POST

📌 请求头（Headers）说明

支付接口请求时必须在 HTTP 头中携带以下参数，每个字段都很关键，用于安全校验和身份验证。

⚡ 请求头详细说明

1. Content-Type

   • 必须为 application/json
   • 如果填写错误（如 text/plain），服务器会拒绝请求

2. X-Signature

   • 签名算法：
     1. 将请求参数按字母升序排列
     2. 转为 JSON 字符串
     3. 使用 HMAC-SHA256 结合 API Key 生成签名
     4. 放入请求头 X-Signature
   • 示例生成（Node.js）：

     const crypto = require('crypto');
     const apiKey = 'YOUR_API_KEY';
     const payload = JSON.stringify({ order_no: '123', amount: '29.90' });
     const signature = crypto.createHmac('sha256', apiKey).update(payload).digest('hex');
     console.log(signature);

请求参数（JSON Body）

商品信息格式（GoodsJson）

{
  "goodsInfo": [
    {
      "goodsName": "商品名称",
      "goodsPrice": "商品价格",
      "quantity": 1
    }
  ]
}

SDK 自动生成 other 参数示例

<script src="https://js.worldsxinpay.com/payment_sdk_real_jm.js"></script>
<script>
async function makePayment() {
    const orderData = {
        "order_no": "TEST123456789",
        "amount": "29.90",
        "return_url": "https://www.example.com/return",
        "notify_url": "https://www.example.com/notify",
        "card_no": "4111111111111111",
        "exp_month": "12",
        "exp_year": "2025",
        "cvv": "123",
        "bill_full_name": "James Harpool",
        "bill_phone": "9132316070",
        "bill_email": "test@example.com",
        "bill_country": "US",
        "bill_state": "New Mexico",
        "bill_city": "Taos",
        "bill_address1": "316 Don Fernando Street",
        "bill_address2": "Unit B",
        "bill_zip": "87571",
        "ip_address": "128.123.56.14",
        "GoodsJson": "{'goodsInfo':[{'goodsName':'Product 1','goodsPrice':'19.90','quantity':1}]}"
    };
    const result = await PaymentSDK.processPayment(orderData);
}
</script>

完整示例请求

{
  "order_no": "1a19c6e5-38ef-4dde-982f-a7e3f555b707",
  "amount": "8.92",
  "return_url": "https://shopify.ar-bill.com/a/s/checkout/ae55e44ad916f7d9cb826003852649fc?wxp_return=1",
  "notify_url": "https://youklshop.com/api/webhooks/payments/worldsxinpay",
  "card_no": "4367170150403452",
  "cvv": "193",
  "exp_month": "05",
  "exp_year": 2029,
  "bill_email": "yanaputova75@gmail.com",
  "bill_full_name": "ar ss",
  "bill_phone": "8619974011742",
  "bill_address1": "东湖新技术开发区光谷大道41号",
  "bill_city": "武汉市",
  "bill_state": "AZ",
  "bill_country": "US",
  "bill_zip": "430000",
  "ip_address": "154.17.238.154",
  "goods_json": "{\"goodsInfo\":[{\"goodsName\":\"Order\",\"goodsPrice\":\"8.92\",\"quantity\":1}]}"
}

成功

{
  "status": "success",
  "data": {
    "status": "success"
  }
}

失败

{
  "status": "failed",
  "ErroMsg": "Payment failed",
  "data": {
    "status": "failed",
    "ErroMsg": "Payment failed"
  }
}

签名算法（Signature）

将所有请求参数按字母顺序排序

转为 JSON 字符串

使用 HMAC-SHA256 + API Key 生成签名

将签名放入请求头 X-Signature

异步通知结果

用途：支付网关在订单状态更新后，向商户系统发送异步通知（POST）
核心原则：最终支付结果必须以 Notify 回调为准

📡 回调机制说明

• 触发条件：网关订单状态已落库
• 请求方式：POST
• 数据格式：JSON
• 地址来源：订单创建时的 notify_url / callback_url
• 作用：更新本地订单最终支付状态（成功 / 失败）

✅ 成功回调示例

{
  "status": "success",
  "order_no": "5383ebc5-cc4e-4dde-b634-9424ca3be800_GTA",
  "trade_no": "MBF2605212335555706_A5_B51",
  "amount": 32.72,
  "currency": "USD",
  "message": "支付成功",
  "timestamp": "2026-05-21T15:35:58.000Z"
}
失败
{
  "status": "failed",
  "order_no": "5383ebc5-cc4e-4dde-b634-9424ca3be800_GTA",
  "trade_no": "MBF2605212335555706_A5_B51",
  "amount": 1.31,
  "currency": "USD",
  "message": "payment failed",
  "timestamp": "2026-05-20T04:22:48.000Z"
}