# 1.1 Online service address

https://openplatform.gateapi.io

# 1.2 Configure new applets

• Log in to the merchant background, via the background address: https://www.gate.com/zh/merchant#/get-started
• Fill in the basic information and apply to become a merchant
• Configure the new application on the configuration page -View the list of configured applications and obtain the application ClientId

# 1.3 Generate payment key

• Enter the developer page and generate a "Payment API Secret Key" for calculating signature verification
• Enter the developer page and generate an "Authorize Secret Key" for calculating signature verification

# 1.4 Key parameters

• Payment API key, used to request a signature
• ClientId, used to identify the identity and verify the signature together with the payment API key

# 2.1 Protocol rules

# 2.1.1 The following rules must be followed when the merchant accesses and calls API:

All interface returns are in JSON format, and users need to convert and extract data by themselves.

# 2.2.1 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. 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.

# 2.2.2 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.000001, and the maximum is 5000000.

# 2.2.3 Currency type

For the currencies supported by GatePay, refer to the supported currencies section

# 2.2.4 Time

Unless otherwise specified, all time fields should be in the form of millisecond-level Unix timestamps.

# 2.3 API protocol header specification

In order to ensure that the request received by GatePay API comes from an authorized legal third-party platform, the GatePay API interface will check the required fields of the HTTP request header and perform a verification signature of the request.

# 2.3.1 New V2 Version protocol header

The new version of the protocol header, which uses the secret key generated in the merchant's background to calculate the signature.

# 2.4 Interface signature

# 2.4.1 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

See the example of the signature algorithm on the right

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

Signature Verification Tool

# 3.1 Check merchant payment account balance

• Data type: JSON （content-type：application/json）
• Request method: GET
• Path: /v1/pay/balance/query
• Verification method: Merchant signature verification
• request body type: none

BalanceItem:

# 4.1 Asynchronous notification of order status

1. When the order status changes, such as when the payment is successful, the payment time is exceeded, or the order is canceled, the GatePay backend will send an order status notification to the merchant at the callback url provided by the merchant during registration.
2. If the notification fails due to network or other unknown reasons, GatePay backend will retry 10 times every 3 seconds. If the retry also fails, the merchant can get the order status by calling the order status inquiry interface.
3. Merchants receive asynchronous notification messages and must verify the message signature parameter to validate the message's legitimacy.

# 4.3 BizType enumeration value

# 4.4 BizStatus value

bizType is eitherPAY,TRANSFER_ADDRESS,RECEIVED_CONVERT_DELAY_ADDRESS`

# 6.1 Payment callback and order query implementation guidelines

Background

Due to network issues or system fluctuations, the merchant side may fail to receive the payment result notification even if the user completes the payment, and the order might be displayed as unpaid. This is the case that will give rise to user complaints and even repeated payments.

Target

The purpose is to let the merchant get the payment status of the order in a timely and accurate manner even when it fails to receive the payment result notification, so as to improve the robustness of the merchant system and reduce user complaints caused by out-of-sync notification of order status.

Merchant backend service processing

The merchant background needs to accurately and efficiently process the asynchronous payment result notification sent by GatePay, and return the processing result to GatePay according to the interface specification.

Regular polling query

If the merchant fails to receive the payment result notification for a long time, the merchant’s background should initiate the regular polling query (order status query interface /v1/pay/order/query) to query the order status.

Plan 1

Based on the time when the order is successfully placed, query the order status by calling the order status query interface (/v1/pay/order/query) every 5 seconds/10 seconds/30 seconds/1 minute/3 minutes/5 minutes/10 minutes/30 minutes. If no successful payment notice returns at the last query, stop the query, and call the closing order interface (/v1/pay/order/close) to close the order. (Merchants can set the interval and times for polling query flexibly according to their own business scenarios)

Plan 2

The regular polling query is performed every 30 seconds to find out the orders that have been created and not paid in the last 10 minutes, and the order status query interface is called (/v1/pay/order/query) to query the order status. The system records the number of order inquiries, and if no successful payment notice returns after 10 inquiries, stops the query, and calls the closing order interface (/v1/pay/order/close) to close the order. (Merchants can set the interval and times for polling query flexibly according to their own business scenarios)

Note: After the payment is completed, GatePay will send the relevant payment result to the merchant in the form of a data stream, and the merchant needs to receive and process it, and return a response according to the specification.

1. The same notification may be sent to the merchant system multiple times, so the merchant system must be able to handle repeated notifications.

2. When interacting with asynchronous notifications in the background, if GatePay receives a response from the merchant that does not meet the specifications or fails to receive the response in the agreed time, the system will determine that the notification failed to be sent and then will resend the notification until it is successfully sent. (GatePay will send the notice 10 times every 5 seconds until it is sent successfully)

# 6.2 Implementation guidelines for the refund process

1. The merchant calls the refund interface (/v1/pay/order/refund) to create a refund order. Note that the refund is an asynchronous process, and the success of calling this interface does not represent the successful completion of the refund.

2. Wait for the refund callback notification. If merchants receive the GatePay asynchronous callback notification and get the refund result, they don’t need to call the query interface.

3. If the refund status notification is not received within 10s, call the (/v1/pay/order/refund/query) interface to query the status of the refund order. For details, please refer to Payment Callback and Order Query Implementation Guidelines.

# 6.3 Best security practices

# 6.3.1 Data transmission

Use HTTPS to ensure network transmission security. Do not use insecure protocols and algorithms such as SSL, it is recommended to use TLS1.2. No self-developed encrypted transmission algorithm is recommended because they will have security issues.

# 6.3.2 Data storage

Sensitive information should not be contained in the log. Those that must be used should be desensitized. Sensitive data in the cache and DB needs to be encrypted Key authentication, such as passwords, must be stored in salted encryption.

# 6.3.3 Data access

External requests for data access must be authenticated. Internal data access should be strictly controlled to reduce the risk of user information leakage.

# 6.3.4 Prevent vulnerabilities caused by improper logic processing

GatePay signature verification is required for the successful payment callback notification to avoid malicious attacks. The judgment logic of the merchant's price is carried out in the background to avoid the client from tampering with the price and therefore causing the merchant's loss. Merchant Securekey should not appear in App or website pages.

# Q: How long is the QR code generated through the pre-order interface valid?

A: Merchants can specify the order expiration time, the maximum and default validity of the order is one hour.

# 8.1 Address payment

5 currencies are supported for address payment:

"USD", "USDT", "BTC", "ETH", "GT"

# 8.2 Normal payment

21 currencies are supported for payment:

"BTC", "USDT", "USD", "GT", "ETH", "EOS", "DOGE", "DOT", "SHIB", "LTC", "ADA", "BCH", "FIL", "ZEC", "BNB", "UNI", "XRP", "STEPG", "SUPE", "LION", "FROG"