Skip to main content

​
Authentication and Security

This page provides a comprehensive reference for GatePay API authentication, security protocols, and signature generation.

​
Protocol Requirements

All GatePay API requests must adhere to the following specifications:
AspectRequirement
TransportHTTPS, TLS 1.2 or higher
Data FormatJSON (Content-Type: application/json)
Signature AlgorithmHMAC-SHA512

​
Unified Response Structure

All API responses follow a consistent format with the following fields:
FieldTypeDescription
statusstringAPI result: SUCCESS or FAIL
codestringError code (null on success)
labelstringError name (null on success)
errorMessagestringError description (null on success)
dataobject/array/string/nullBusiness data payload
Example Response (Success): 
{
  "status": "SUCCESS",
  "code": null,
  "label": null,
  "errorMessage": null,
  "data": {
    "prepayId": "123456789",
    "location": "https://checkout.gateapi.io/...",
    "qrContent": "..."
  }
}
Example Response (Failure): 
{
  "status": "FAIL",
  "code": "INVALID_REQUEST",
  "label": "Invalid Request",
  "errorMessage": "Missing required field: merchantTradeNo",
  "data": null
}

​
Request Headers

All API requests must include the following headers:
HeaderDescriptionExample
X-GatePay-Certificate-ClientIdClientId assigned after app creation. Uniquely identifies your application.app_abc123def456
X-GatePay-On-Behalf-Of(Optional) Institution sub-account ID. Include only when making requests on behalf of a sub-account.sub_account_123
X-GatePay-TimestampUTC timestamp in milliseconds. Requests with timestamp drift greater than 10 seconds are rejected.1704067200000
X-GatePay-NonceRandom string for replay prevention. Recommended length ≤ 32 characters; alphanumeric only (letters and digits).abc123xyz789
X-GatePay-SignatureRequest signature computed using HMAC-SHA512. See signature generation below.<64-char-hex-string>

​
Signature Generation

The signature ensures request integrity and authenticity. Follow these steps to generate a valid signature:

​
Signature String Format

The signature string consists of three lines, each ending with a newline character (\n): 
{timestamp}
{nonce}
{body}
  • Line 1: X-GatePay-Timestamp value
  • Line 2: X-GatePay-Nonce value
  • Line 3: Raw JSON request body (empty string if no request body)
  • Trailing newline: Always include a final newline after line 3

​
Signature Generation Steps

  1. Generate Headers: Create X-GatePay-Timestamp (current UTC time in milliseconds) and X-GatePay-Nonce (random string, ≤ 32 alphanumeric characters).
  2. Prepare Request Body: Extract the raw JSON request body as a string. If there is no request body (e.g., GET requests), use an empty string.
  3. Build Signature String: Concatenate the timestamp, nonce, and body with newlines: 
    {timestamp}\n{nonce}\n{body}\n
  4. Compute HMAC-SHA512: Use your Payment API Secret as the key to compute the HMAC-SHA512 hash of the signature string. Output the result as a hexadecimal string.
  5. Set Header: Set the computed hash as the X-GatePay-Signature request header.

​
Example: Signature Generation (POST Request)

Request Details:
  • Timestamp: 1704067200000
  • Nonce: abc123xyz789
  • Payment API Secret: my_secret_key
  • Request body: {"merchantTradeNo": "order_123", "currency": "USDT", "orderAmount": "100"}
Signature String (before hashing): 
1704067200000
abc123xyz789
{"merchantTradeNo": "order_123", "currency": "USDT", "orderAmount": "100"}
Computed Signature (hexadecimal): 
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3

​
Example: Signature Generation (GET Request)

For GET requests with no body: Request Details:
  • Timestamp: 1704067200000
  • Nonce: xyz789abc123
  • Payment API Secret: my_secret_key
  • Request body: (empty)
Signature String (before hashing): 
1704067200000
xyz789abc123

​
Callback Verification

When GatePay sends callbacks to your webhook endpoint, verify the callback signature using the same method:

​
Callback Headers

Callbacks include the following headers for signature verification:
HeaderDescription
X-GatePay-TimestampUTC timestamp when the callback was sent
X-GatePay-NonceRandom string used during signature generation
X-GatePay-SignatureCallback signature

​
Callback Verification Steps

  1. Extract the callback headers: X-GatePay-Timestamp, X-GatePay-Nonce, and X-GatePay-Signature.
  2. Read the raw callback body (JSON).
  3. Build the signature string: 
    {timestamp}
{nonce}
{body}
  4. Compute HMAC-SHA512 using your Payment API Secret as the key.
  5. Compare the computed signature with the X-GatePay-Signature header. If they match, the callback is authentic.
  6. Additionally, verify that the timestamp is within an acceptable range (e.g., within the last 5 minutes) to prevent replay attacks.
Important: Always verify callbacks before processing the enclosed data.

​
Signature Verification Tool

For testing and debugging signature verification, use the GatePay Signature Utility: GatePay Signature Verification Tool This tool allows you to:
  • Generate test signatures
  • Verify signature correctness
  • Debug signature mismatches

​
Best Practices

  • Timestamp Validation: Always validate that the request timestamp is within 10 seconds of your server’s current UTC time.
  • Nonce Uniqueness: Use a unique nonce for each request to prevent replay attacks. Consider storing used nonces in a cache with a short TTL (e.g., 15 minutes).
  • Secret Management: Store your Payment API Secret and Authorization Secret securely. Never hardcode secrets in your source code or commit them to version control.
  • HTTPS Only: All requests must use HTTPS with TLS 1.2 or higher. Reject any non-HTTPS requests.
  • Callback Security: Always verify callback signatures before processing. Implement idempotency checks on your callback endpoint to handle duplicate deliveries.
  • Error Handling: For signature errors, respond with HTTP 400 (Bad Request) and log the mismatch for investigation.