Skip to main content

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.

​
Payment Callbacks and Order Queries

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 retry at the following intervals: 15 seconds / 30 seconds / 3 minutes / 10 minutes / 20 minutes / 30 minutes / 60 minutes / 3 hours / 6 hours)

​
Refund Flow

  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 the Payment Callback and Order Query Implementation Guidelines section.

​
Best security practices

​
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 or higher. No self-developed encrypted transmission algorithm is recommended because they will have security issues.

​
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.

​
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.

​
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.

​
Frequently Asked Questions

Q: How long is the QR code generated through the pre-order interface valid? A: Merchants can specify the order expiration time. The maximum validity period is 1 hour for Gate payments and 24 hours for address payments. Q: Which currencies are supported for placing orders? A: Orders can be created using either cryptocurrency or fiat currency. If fiat currency is selected, the amount is converted to cryptocurrency using the real-time exchange rate at the time of order creation.