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.
Protocol rules
| Parameter | Description |
|---|
| Transmission mode | HTTPS with TLS 1.2 or higher |
| Data format | JSON format for both request and response |
| Signature algorithm | HMAC-SHA512 |
| Signature requirement | Both requesting and receiving data require signature verification |
| Judgmental logic | First check protocol status, then business return, finally transaction status |
| Field | Type | Description |
|---|
| status | string | SUCCESS or FAIL |
| code | string | Error code |
| label | string | Error name |
| errorMessage | string | Error description |
| data | string | JSON format business response data |
Success example
{
"status": "SUCCESS",
"code": "000000",
"label": "Success",
"errorMessage": "",
"data": "{...}"
}
Failure example
{
"status": "FAIL",
"code": "300001",
"label": "Parameter error",
"errorMessage": "merchantTradeNo cannot be empty",
"data": ""
}
Parameter specification
Merchant’s order number
The merchant can customize the order number, which should be a combination of English half-width characters such as letters, numbers, dash-, and underscore_, but should not contain Chinese characters or full-width characters, the length should be limited to 100 characters. A unique order number should be generated for each deal (it is recommended to generate the order number based on the current system time plus in a random sequence). To initiate a repayment, the original order number should be submitted to avoid repeated payments.
Amount
All amount parameters are transmitted in strings with an accuracy of 6 decimal places, such as order amount, refund amount, etc. The minimum transaction amount of a single transaction amount is 0.0001, and the maximum is 5000000. The maximum amount that can be transferred using a personal QR code is 10000.
Currency type
For the currencies supported by GatePay, refer to the supported currencies section.
Time
Unless otherwise specified, all time fields should be in the form of millisecond-level Unix timestamps.
| Head field | Description |
|---|
| X-GatePay-Certificate-ClientId | The clientId assigned when registering the application in the Gate merchant background |
| X-GatePay-On-Behalf-Of | Institution delegated header. It is required for all institution APIs except account create, account query, and account list. |
| X-GatePay-Timestamp | UTC timestamp in milliseconds when the request was generated. GatePay does not process requests where the gap between receipt time and this timestamp exceeds 10 seconds |
| X-GatePay-Nonce | Random string, recommended length ≤32 characters, alphanumeric |
| X-GatePay-Signature | Request signature. GatePay uses this signature to verify request validity |
Signature
Signature specification
Constructing signature string rules
We expect the merchant’s technical developers to construct the signature string according to the rules agreed in the current documentation. GatePay will construct the signature string in the same way. If the merchant constructs the signature string in the wrong way, the signature verification will not pass. The specific format of the signature string is explained first.
Each line has one parameter. The end of the line is terminated by \n (a line feed, ASCII value 0x0A). If the parameter itself ends with \n, an additional \n is also required.
timestamp\nnonce\nbodyString\n
Signature algorithm
Golang
import (
"crypto/hmac"
"crypto/sha512"
"encoding/hex"
"fmt"
)
// GenerateSignature: generate the request signature
// timestamp: UTC timestamp converted to a string, precision is millisecond
// nonce: random string
// body: request body
// secretKey: api_secret provided by Gate
// return: string signature
func GenerateSignature(timestamp string, nonce string, body string, secretKey string) string {
payload := fmt.Sprintf("%s\n%s\n%s\n", timestamp, nonce, body)
mac := hmac.New(sha512.New, []byte(secretKey))
mac.Write([]byte(payload))
signature := mac.Sum(nil)
return hex.EncodeToString(signature)
}
Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
public class Main {
private static final String HMAC_SHA512 = "HmacSHA512";
private static String toHexString(byte[] bytes) {
Formatter formatter = new Formatter();
for (byte b : bytes) {
formatter.format("%02x", b);
}
return formatter.toString();
}
public static String calculateHMAC(String data, String key)
throws InvalidKeyException, NoSuchAlgorithmException {
SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), HMAC_SHA512);
Mac mac = Mac.getInstance(HMAC_SHA512);
mac.init(secretKeySpec);
return toHexString(mac.doFinal(data.getBytes()));
}
public static void main(String[] args) throws Exception {
String timeStamp = "1673613945439";
String nonce = "3133420233";
String body = "{\"code\":\"ac8B7Pl7C-XgfH6zxtd3SidYt7XIfWKU\",\"grant_type\":\"authorization_code\",\"redirect_uri\":\"https://gate.bytetopup.com\",\"client_id\":\"2Ugf9YGMCFRk85Yy\"}";
String data = String.format("%s\n%s\n%s\n", timeStamp, nonce, body);
String key = "zgsN5DntmQ2NCQiyJ4kJLyyEO25ewdDHydOSFIHdGrM=";
String hmac = calculateHMAC(data, key);
System.out.println(hmac);
}
}
Python
import hashlib
import hmac
def generate_signature(timestamp: str, nonce: str, body: str, secret: str) -> str:
'''
generate the request signature
:param timestamp: UTC timestamp converted to a string, precision is millisecond
:param nonce: random string
:param body: request body
:param secret: api_secret provided by GatePay
:return: string signature
'''
payload = '%s\n%s\n%s\n' % (timestamp, nonce, body)
signed = hmac.new(secret.encode(), payload.encode(), hashlib.sha512)
return signed.digest().hex()
PHP
<?php
function generateSignature($timestamp, $nonce, $body, $secretKey) {
$payload = "$timestamp\n$nonce\n$body\n";
$signature = hash_hmac('sha512', $payload, $secretKey, true);
return bin2hex($signature);
}
$timestamp = "1631257823000";
$nonce = "abcd1234";
$body = 'the post request body content';
$secretKey = "your_secret_key";
$signature = generateSignature($timestamp, $nonce, $body, $secretKey);
echo "Signature: " . $signature;
Payment callback handling
Callback description
Gate Pay sends the callback message to the callback URL via a POST request. The request body contains JSON-formatted notification parameters. The parameter list is as follows:
| Name | Type | Description |
|---|
| bizType | string | Enum for asynchronous callback type: “PAY” for non-address payment, “PAY_BATCH” for asynchronous batch reward, “PAY_ADDRESS” for address-based payment, “PAY_FIXED_ADDRESS” for fixed collection QR code address-based payment, “TRANSFER_ADDRESS” for address transfer |
| bizId | string | Payment order ID |
| bizStatus | string | Order status |
| client_id | string | The client_id associated with the payment order |
| data | json format | Varies depending on the business type; refer to the relevant business documentation for details |
Callback signature verification and response
Upon receiving the callback notification, the merchant must verify the signature and respond to the callback.
Merchant response fields after signature verification:
| Parameter | Description |
|---|
| returnCode | Whether the callback was successfully processed. “SUCCESS” indicates successful processing; Gate Pay will not resend the callback. “FAIL” indicates processing failure; Gate Pay will retry sending the callback |
| returnMessage | Failure reason (string), optional |
Response JSON format:
{
"returnCode": "SUCCESS",
"returnMessage": ""
}
Callback handling steps
Signature verification steps:
The callback request will include signature information in the HTTP headers, used for verifying the signature. Details are as follows:
| Parameter | Description |
|---|
| X-GatePay-Timestamp | Timestamp for signature verification |
| X-GatePay-Nonce | Random string for signature verification |
| X-GatePay-Signature | Signature value for verification |
To verify the signature, the merchant should construct a signature verification string using the X-GatePay-Timestamp, X-GatePay-Nonce, and the JSON-formatted notification parameters in the request body (see the Signature Algorithm section for details on the signature construction). Then, use the merchant’s payment key to compute the signature and compare it with the X-GatePay-Signature value to ensure the callback is genuinely from Gate Pay.
Merchant developers can use this tool to troubleshoot the reasons why signature verification fails.
Signature Verification Tool