Security and Signature

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

Response format

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.

Request Headers

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	Millisecond timestamp; the difference from server time must not exceed 30 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.

Signature verification tool

Merchant developers can use this tool to troubleshoot the reasons why signature verification fails. Signature Verification Tool

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Protocol rules

Response format

Success example

Failure example

Parameter specification

Merchant’s order number

Amount

Currency type

Time

Request Headers

Signature

Signature specification

Signature algorithm

Payment callback handling

Callback description

Callback signature verification and response

Callback handling steps

Signature verification tool

​Protocol rules

​Response format

​Success example

​Failure example

​Parameter specification

​Merchant’s order number

​Amount

​Currency type

​Time

​Request Headers

​Signature

​Signature specification

​Signature algorithm

​Payment callback handling

​Callback description

​Callback signature verification and response

​Callback handling steps

​Signature verification tool

Protocol rules

Response format

Success example

Failure example

Parameter specification

Merchant’s order number

Amount

Currency type

Time

Request Headers

Signature

Signature specification

Signature algorithm

Payment callback handling

Callback description

Callback signature verification and response

Callback handling steps

Signature verification tool