请求与响应

了解如何构建 API 请求和解析响应。

请求格式

请求头

头部	必填	说明
`Authorization`	是	Bearer Token 认证
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	幂等性键（POST 请求推荐）

Header	Required	Description
`Authorization`	Yes	Bearer Token authentication
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Idempotency key (recommended for POST)

请求示例

curl -X POST https://api.stablepay.co/v1/payment/sessions \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique_request_id" \
  -d '{
    "merchant_id": "merchant_123",
    "amount": {
      "value": "10000",
      "currency": "USDT"
    }
  }'

响应格式

成功响应

{
  "base": {
    "code": 0,
    "message": "success"
  },
  "data": {
    "session_id": "sess_123",
    "status": "PENDING",
    "payment_url": "https://checkout.stablepay.co/sess_123"
  }
}

错误响应

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid amount format",
    "param": "amount.value"
  }
}

幂等性

对于 POST 请求，使用 Idempotency-Key 头确保请求只被处理一次：

curl -X POST https://api.stablepay.co/v1/payment/sessions \
  -H "Idempotency-Key: order_12345_payment_v1" \
  ...