> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> This guide covers the authentication mechanisms, security protocols, request signing, and callback verification required for integrating with the GatePay API.

## API Standards and Protocols

### Transport and Data Format

| Component           | Specification                             |
| ------------------- | ----------------------------------------- |
| Transport Protocol  | HTTPS with TLS 1.2 or above               |
| Data Format         | JSON for both request and response bodies |
| Content-Type Header | `application/json` (required)             |

### Signature and Verification

| Component             | Specification                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------- |
| Signature Algorithm   | HMAC-SHA512                                                                              |
| Request Signing       | All merchant requests must be signed using the HMAC-SHA512 algorithm.                    |
| Callback Verification | All callbacks sent by GatePay must be verified by the merchant using the same algorithm. |

### Response Evaluation

Always evaluate API responses using this process:

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 Response Structure

All GatePay API responses follow this standardized structure:

| Field          | Type                           | Description                                                                        |
| -------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| `status`       | string                         | Result status: `SUCCESS` indicates successful execution; `FAIL` indicates failure. |
| `code`         | string                         | Error code (empty in successful responses).                                        |
| `label`        | string                         | Error name or identifier (empty in successful responses).                          |
| `errorMessage` | string                         | Human-readable error description (empty in successful responses).                  |
| `data`         | object / array / string / null | Business data returned by the API. Empty in failed responses.                      |

## Request Parameter Standards

### Merchant Order Number (`merchantTradeNo`)

The merchant order number is a unique identifier you assign to each transaction:

| Property       | Specification                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| Character Set  | ASCII half-width characters only: letters (a-z, A-Z), digits (0-9), hyphen (-), underscore (\_)                  |
| Maximum Length | 100 characters                                                                                                   |
| Uniqueness     | Must be unique within your merchant account                                                                      |
| Retry Policy   | When retrying the same business transaction, you must reuse the original `merchantTradeNo` to ensure idempotency |

### Transaction Amount

| Property                     | Specification                             |
| ---------------------------- | ----------------------------------------- |
| Data Type                    | String (numeric value as a string)        |
| Decimal Precision            | Up to 6 decimal places                    |
| Minimum Per Transaction      | 0.0001                                    |
| Maximum Per Transaction      | 5,000,000                                 |
| Maximum QR Collection Amount | 10,000 (for personal QR code collections) |

### Timestamp Format

| Property | Specification                                 |
| -------- | --------------------------------------------- |
| Format   | Unix timestamp in milliseconds (UTC timezone) |

## Request Headers and Signing

### Required Request Headers

Every API request must include these headers:

| Header                           | Description                                                                                                                             |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `X-GatePay-Certificate-ClientId` | Your `ClientId` as assigned when you created your application (see [Integration Overview](/essentials/version/100/en/generalOverview)). |
| `X-GatePay-Timestamp`            | Current UTC timestamp in milliseconds when the request is created. Requests with a time drift greater than 10 seconds will be rejected. |
| `X-GatePay-Nonce`                | A random string to prevent replay attacks. Recommended length is 32 characters or less, containing only letters and digits.             |
| `X-GatePay-Signature`            | The computed request signature (see Signature Generation steps below).                                                                  |
| `X-GatePay-On-Behalf-Of`         | (Optional) Institution sub-account ID if using delegated access.                                                                        |

### Signature String Format

The signature is computed from a string containing three lines, each ending with a newline character (`\n`):

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

Where:

* `<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 Steps

Follow these steps to compute the `X-GatePay-Signature` header value:

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 Request Structure

```json  theme={null}
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 Callbacks

### Callback Overview

GatePay sends asynchronous payment notifications to your configured callback URL via HTTP POST requests. These notifications inform your system of payment status changes.

For comprehensive details on callback events and handling, refer to the [Notification Callback](/essentials/version/100/en/notificationCallback) guide.

### Callback Payload Structure

GatePay will POST a JSON payload with the following structure:

```json  theme={null}
{
  "bizType": "TRANSFER_ADDRESS",
  "bizId": "329782527190433792",
  "bizStatus": "TRANSFERRED_ADDRESS_DELAY",
  "client_id": "iVNJZdekOCMJIsmV",
  "data": "{\"merchantTradeNo\":\"1894789022551797760\"}"
}
```

Where:

| Field       | Type   | Description                                                                           |
| ----------- | ------ | ------------------------------------------------------------------------------------- |
| `bizType`   | string | The type of business event (e.g., `TRANSFER_ADDRESS`, `PAYMENT_ORDER`).               |
| `bizId`     | string | The unique identifier for the payment order or business transaction.                  |
| `bizStatus` | string | The current status of the transaction (e.g., `TRANSFERRED_ADDRESS_DELAY`, `SUCCESS`). |
| `client_id` | string | The `client_id` associated with the payment order.                                    |
| `data`      | string | Business-specific data as a JSON string. The structure depends on `bizType`.          |

### Expected Callback Response

Your callback endpoint must respond with a JSON object indicating successful processing:

| Field           | Values              | Description                                                                                      |
| --------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `returnCode`    | `SUCCESS` \| `FAIL` | `SUCCESS` indicates the callback was processed successfully; `FAIL` indicates processing failed. |
| `returnMessage` | string              | Human-readable message explaining the result (empty string for success).                         |

**Success Response Example:**

```json  theme={null}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
```

**Failure Response Example:**

```json  theme={null}
{
  "returnCode": "FAIL",
  "returnMessage": "Database connection failed"
}
```

### Callback Verification Steps

Every callback you receive must be verified to ensure it originated from GatePay and has not been tampered with:

1. Extract the `X-GatePay-Timestamp` header from the incoming callback request
2. Extract the `X-GatePay-Nonce` header from the incoming callback request
3. Extract the `X-GatePay-Signature` header from the incoming callback request
4. Read the raw JSON callback 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 callback if the signatures match exactly

**Important:** If the signatures do not match, reject the callback as it may be fraudulent or corrupted.

### Callback Request Headers

When GatePay sends a callback to your endpoint, it includes these headers:

| Header                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `X-GatePay-Timestamp` | The timestamp when GatePay sent the callback.  |
| `X-GatePay-Nonce`     | A random string included in the signature.     |
| `X-GatePay-Signature` | The HMAC-SHA512 signature computed by GatePay. |

## Tools and Resources

### Signature Verification Tool

GatePay provides an online tool to help you debug and verify signatures during development:

[GatePay Signature Verification Tool](https://www.gate.com/zh/gatepay/public/signUtil)

This tool allows you to:

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

## Error Handling

For a comprehensive list of error codes and best practices for handling API errors, see the [Error Codes and Best Practices](/essentials/version/100/en/errorCodesBestPractices) guide.

## Security Best Practices

1. **Secure Key Storage:** Store your Payment API Secret and Authorization Secret securely on your server. Never expose these secrets in client-side 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 callback timestamps are within an acceptable time window (e.g., not older than 5 minutes).

4. **Signature Verification:** Always verify callback signatures before processing any sensitive operations.

5. **HTTPS Only:** All communication with GatePay must use HTTPS with TLS 1.2 or above.

6. **Callback Idempotency:** Design your callback handler to be idempotent, as GatePay may retry callbacks 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 Overview](/essentials/version/100/en/generalOverview) - App configuration and credential setup
* [Notification Callback](/essentials/version/100/en/notificationCallback) - Detailed callback event handling
* [Error Codes and Best Practices](/essentials/version/100/en/errorCodesBestPractices) - Error code reference and troubleshooting


Built with [Mintlify](https://mintlify.com).