认证

​

API 标准与协议

​

传输与数据格式

​

签名与验签

​

响应判定

1. Check the HTTP status code first
2. Then examine the status, code, label, and errorMessage fields in the response body
3. Extract business data from the data field if the request was successful

​

Unified 响应 Structure

​

请求 参数 Standards

​

商户 Order Number (merchantTradeNo)

​

Transaction Amount

​

Timestamp Format

​

请求 Headers and Signing

​

必填 请求 Headers

​

Signature String Format

<request_timestamp>\n<request_nonce>\n<request_body>\n

• <request_timestamp> is the value of X-GatePay-Timestamp
• <request_nonce> is the value of X-GatePay-Nonce
• <request_body> is the raw JSON body of the request, or an empty string if there is no body

​

Signature Generation 步骤

1. Generate a unique X-GatePay-Timestamp (current UTC time in milliseconds)
2. Generate a random X-GatePay-Nonce (32 characters or less, letters and digits only)
3. Read the raw JSON request body as request_body; use an empty string if there is no body
4. Construct the signature string: timestamp\nnonce\nbody\n
5. Compute HMAC-SHA512 using your Payment API Secret as the key
6. Encode the result in Base64 (if required by your implementation)
7. Place the computed signature into the X-GatePay-Signature header

​

Example 请求 Structure

POST /api/v1/payment/submit HTTP/1.1
Host: openplatform.gateapi.io
Content-Type: application/json
X-GatePay-Certificate-ClientId: your_client_id
X-GatePay-Timestamp: 1234567890000
X-GatePay-Nonce: abc123def456ghi789
X-GatePay-Signature: <computed_hmac_sha512_signature>

{
  "merchantTradeNo": "order_12345",
  "amount": "100.50",
  "currency": "USD"
}

​

Payment Result 回调

​

回调 概述

​

回调 Payload Structure

{
  "bizType": "TRANSFER_ADDRESS",
  "bizId": "329782527190433792",
  "bizStatus": "TRANSFERRED_ADDRESS_DELAY",
  "client_id": "iVNJZdekOCMJIsmV",
  "data": "{\"merchantTradeNo\":\"1894789022551797760\"}"
}

​

Expected 回调 响应

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

{
  "returnCode": "FAIL",
  "returnMessage": "Database connection failed"
}

​

回调 Verification 步骤

1. Extract the X-GatePay-Timestamp header from the incoming 回调 request
2. Extract the X-GatePay-Nonce header from the incoming 回调 request
3. Extract the X-GatePay-Signature header from the incoming 回调 request
4. Read the raw JSON 回调 request body
5. Construct the signature string using the format: timestamp\nnonce\nbody\n
6. Compute HMAC-SHA512 using your Payment API Secret as the key
7. Compare the computed signature with the X-GatePay-Signature header value
8. Only process the 回调 if the signatures match exactly

​

回调 请求 Headers

​

Tools and Resources

​

Signature Verification Tool

• Test signature generation with sample data
• Verify computed signatures match expected values
• Debug signature-related integration issues

​

Error 处理方式

​

Security 最佳实践

1. Secure Key Storage: Store your Payment API Secret and Authorization Secret securely on your server. Never expose these secrets in 客户端 code or version control.
2. Nonce Uniqueness: Ensure each request uses a unique nonce to prevent replay attacks.
3. Timestamp Validation: Always validate that incoming 回调 timestamps are within an acceptable time window (e.g., not older than 5 minutes).
4. Signature Verification: Always verify 回调 signatures before processing any sensitive operations.
5. HTTPS Only: All communication with GatePay must use HTTPS with TLS 1.2 or above.
6. 回调 Idempotency: Design your 回调 handler to be idempotent, as GatePay may 重试 回调 if it does not receive a successful response.
7. Error Messages: Do not expose sensitive information (such as keys or internal system details) in error messages returned to the client.

​

Related Documentation

• Integration 概述 - App configuration and credential setup
• 通知 回调 - Detailed 回调 event handling
• 错误码 and 最佳实践 - Error code reference and troubleshooting