# Gate Pay DOCS > This file is very large and may be truncated. For an index of this content, please refer to https://docs.gate.com/llms.txt instead. # Best Practices Source: https://docs.gate.com/global/api-reference/version/100/en/common/bestPractices Provides recommended implementation patterns for callbacks, order queries, refunds, and security controls. ## 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. # Error Codes Source: https://docs.gate.com/global/api-reference/version/100/en/common/errorCodes Summarizes common GatePay error codes, their meanings, and recommended handling actions. | HTTP Status | Error Code | Description | Solution | | - | - | - | - | | `500` | `300000` | System error | System exception, please retry with the same parameters | | `500` | `300001` | Internal error | System exception, please retry with the same parameters | | `500` | `400000` | Unknown error | System exception, please retry with the same parameters | | `200` | `400001` | Request parameter format error | Check request data parameters and format | | `200` | `400002` | Signature verification failed | Check if the merchant's signature is correct | | `200` | `400003` | Request timestamp timed out | Check the timestamp field in the request header | | `200` | `400004` | API identity key invalid | Check whether the `GatePay-Api-Key` request header is configured correctly | | `200` | `400005` | Client identifier invalid | Check whether the `GatePay-Client-Id` request header is configured correctly | | `200` | `400007` | Unsupported media type | Check the media type set in the interface | | `200` | `400020` | Signature random number error | Please check whether the random number is empty | | `200` | `400201` | Merchant order number already exists | Please verify whether the merchant order number has been submitted repeatedly | | `200` | `400202` | Order does not exist | Check whether the order has been traded or whether the order number is correct | | `200` | `400203` | Merchant number does not exist | Check whether the merchant number is correct | | `200` | `400204` | Order status is incorrect | Check whether the order has expired, canceled, or closed, and use the query interface if necessary | | `200` | `400205` | Invalid currency | Check the currency type of the order | | `200` | `400304` | Refund ID does not exist | Check the requested refund ID | | `200` | `400305` | Merchant channel information does not exist | Check whether `channelId` is correct and not deleted | | `200` | `400603` | Order timed out | Please verify whether the order has expired | | `200` | `400604` | Invalid refund-related transaction order | Check whether the refund transaction order is in a completed state | | `200` | `400605` | Insufficient balance in the payment account | Insufficient balance in the payment account | | `200` | `400607` | Too many refunds | The number of refunds exceeds the limit | | `200` | `400608` | Refund amount exception | Please check the refund amount | | `200` | `400620` | Duplicate order payment | Please verify whether the merchant order number has been submitted repeatedly | | `200` | `400621` | Incorrect payment amount | Check the requested amount | | `200` | `400622` | Exchange rate fluctuations result in payment failure | You can try to apply again | | `200` | `400623` | Unsupported currency payment | Check the payment currency | | `200` | `400624` | Invalid order status notification address | Check whether the callback address provided by the merchant is valid | | `200` | `400701` | An active subscription already exists for the same user and product | Please confirm whether an active subscription already exists for the same product | | `200` | `400702` | Merchant has not enabled channel payment permission | Please confirm whether the merchant has enabled the corresponding channel payment permission | | `200` | `500008` | Corresponding merchant not found | Check whether the requested merchant ID is correct | | `200` | `500100` | Payment QR code expired | Reorder and generate a new QR code | | `200` | `500101` | Duplicate payment QR code | Please verify the order status | | `200` | `500103` | Address payment exchange currency error | Exchange rate fluctuations affect the conversion | | `200` | `500203` | Unable to query order details for address payment | Please check whether the address is correct | | `200` | `500204` | Invalid recipient ID for refund transaction order | Please confirm that the recipient of the refund is a Gate user | | `200` | `500205` | Refund currency does not match | Please ensure that the refund currency is one of the order currency or the user's payment currency | | `200` | `500206` | Refund amount exceeds limit | Please check the refund amount of the order | | `200` | `500207` | Unable to find the refund order for address payment | Please confirm whether the refund was successful or check whether the address is correct | | `200` | `500208` | Cannot refund orders without a converted address | Please confirm the type of refund order | | `200` | `550307` | OTC transaction limit exceeded | Please add additional information through the following page to increase your limit: [https://www.gate.com/otc/global_apply/add_info](https://www.gate.com/otc/global_apply/add_info) | | `200` | `550008` | Subaccount status abnormal | Retry later with the same parameters; contact support if the failure persists | | `200` | `550018` | Risk control engine rejected this transaction | Check the transaction characteristics or contact operations | | `200` | `550020` | Source IP / region is on the sanctions list | Please switch to a compliant network environment | | `200` | `550143` | Surcharge amount is invalid | Adjust the surcharge to a non-negative value that does not exceed the configured upper limit | | `200` | `550200` | Institution delegate permission insufficient | Confirm whether `X-GatePay-On-Behalf-Of` is passed and the request is made under your own merchant identity | | `200` | `550203` | Tolerance amount is invalid | Ensure the tolerance amount is >= 0 and less than the payable amount | | `200` | `550205` | Amount precision is invalid | Check whether the decimal precision of the order amount and surcharge meets requirements | | `200` | `5502724` | Channel name contains invalid characters | `channelId` only allows Chinese, English letters, numbers, underscores, hyphens, and spaces; remove special characters and retry | | `200` | `5502740` | Subaccounts do not support creating orders | Use the main account or an account with the appropriate permissions | | `200` | `5502761` | Request conflict | Use a different merchant order number, or retry idempotently with the same parameters | | `200` | `5504080` | Security item change limit exceeded within 24h | Please wait 24 hours after the security item change before retrying | # Institution Headers Source: https://docs.gate.com/global/api-reference/version/100/en/common/institutionalCommonHeaders Explains the required headers for institution APIs and how to use X-GatePay-On-Behalf-Of. Institution APIs include dedicated institution endpoints and a full set of institution merchant APIs exposed under institution-prefixed paths. For the signature algorithm and verification rules, see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). ## Request headers | Header | Required | Description | | - | - | - | | X-GatePay-Certificate-ClientId | Yes | The clientId assigned when the merchant registers an application in the Gate merchant console | | X-GatePay-Timestamp | Yes | Millisecond timestamp; the difference from server time must not exceed 30 seconds. | | X-GatePay-Nonce | Yes | Random string. Recommended length within 32 characters, composed of digits and letters | | X-GatePay-Signature | Yes | Request signature. GatePay uses this signature to verify whether the request is valid | | X-GatePay-On-Behalf-Of | Required on selected institution APIs | The initiating account ID for the current request. Institution merchant APIs typically use the target sub-account ID; charge and transfer APIs can use either an institution account ID or a sub-account ID. It is not used by the account APIs or the fee-setting APIs. | ## Endpoints that do NOT require X-GatePay-On-Behalf-Of The following dedicated institution APIs are **institution master-account–scoped**. Do **not** send **X-GatePay-On-Behalf-Of** in the request header; the first four common headers are sufficient: **Accounts** * Create sub-account * Query sub-account * List sub-accounts (paginated) Charge APIs, transfer APIs, and institution merchant APIs **must** include **X-GatePay-On-Behalf-Of**. Institution merchant APIs typically use the target sub-account ID; charge and transfer APIs can use the initiating account ID for the current transaction (either an institution account ID or a sub-account ID). Account APIs and fee-setting APIs do not use this header. # Merchant Access Source: https://docs.gate.com/global/api-reference/version/100/en/common/merchantAccess Explains the base URL, credential preparation, and common request headers used by GatePay merchants. ## Base URL `https://openplatform.gateapi.io` If this is your first time reading the GatePay documentation, start with [Quickstart](/global/essentials/version/100/en/common/quickstart) and the [Merchant Access guide](/global/essentials/version/100/en/common/accessguide), then return to this reference section after your application, signing, and callback setup are ready. ## Integration Setup 1. Sign in to the GatePay merchant portal at [https://www.gate.com/zh/merchant#/get-started](https://www.gate.com/zh/merchant#/get-started) 2. Complete the required business information and merchant application 3. Open the application configuration page and create a new application 4. View the configured application list and obtain the application ClientId ## Generate Secrets 1. Open the developer page and generate a **Payment API Secret Key** for payment API signing and callback verification 2. Generate an **Authorization Secret Key** for authorization-related signing flows 3. Configure the callback URL so asynchronous notifications can be verified and processed ## Key Parameters | Parameter | Description | | - | - | | Payment API key | Used for payment request signing and callback verification | | ClientId | Used to identify your application | ## Common request headers Standard merchant APIs use the following common headers: | Header | Description | | - | - | | X-GatePay-Certificate-ClientId | Application ClientId | | X-GatePay-Timestamp | Millisecond timestamp; the difference from server time must not exceed 30 seconds. | | X-GatePay-Nonce | Request nonce | | X-GatePay-Signature | Request signature calculated with the signing rules | ## SDK The latest official SDK and client repositories are maintained under [https://github.com/gate](https://github.com/gate). Current public multi-language support includes: * [gatepay-sdk-java](https://github.com/gate/gatepay-sdk-java) * [gatepay-sdk-go](https://github.com/gate/gatepay-sdk-go) * [gatepay-sdk-python](https://github.com/gate/gatepay-sdk-python) * [gatepay-sdk-android](https://github.com/gate/gatepay-sdk-android) * [gatepay-sdk-ios](https://github.com/gate/gatepay-sdk-ios) * [gatepay-call-payment-sdk-android](https://github.com/gate/gatepay-call-payment-sdk-android) * [gatepay-call-payment-sdk-iOS](https://github.com/gate/gatepay-call-payment-sdk-iOS) For institution merchant APIs, see [Institution Headers](/global/api-reference/version/100/en/common/institutionalCommonHeaders). # Security and Signature Source: https://docs.gate.com/global/api-reference/version/100/en/common/securityAndSignature Explains protocol rules, shared response structure, request headers, and the GatePay signing algorithm. ## 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 ```json theme={null} { "status": "SUCCESS", "code": "000000", "label": "Success", "errorMessage": "", "data": "{...}" } ``` ### Failure example ```json theme={null} { "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** ```go theme={null} 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** ```java theme={null} 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** ```python theme={null} 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 theme={null} \n\n\n ``` Where: * `` is the value of `X-GatePay-Timestamp` * `` is the value of `X-GatePay-Nonce` * `` 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 as a hexadecimal string 7. Place the computed signature into the `X-GatePay-Signature` header ### Example Request Structure The following example is provided only to explain how the signing string is constructed. It is not a complete business-ready request body for a specific endpoint. For actual required fields, always follow the corresponding API Reference page and OpenAPI definition. ```json theme={null} POST /v1/pay/checkout/order 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: { "merchantTradeNo": "order_12345", "orderAmount": "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](/global/essentials/version/100/en/common/notification) guide. ### Callback Payload Structure The payload below is shown to explain the common callback envelope. The object carried in `data` varies by product and business type, so it should always be read together with the relevant product guide and callback reference. 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. | ## Time Window Clarification Two different time windows appear in this documentation, and they apply to different scenarios: | Scenario | Time Window | Meaning | | - | - | - | | Merchant-initiated API request | 10 seconds | GatePay request-acceptance window for the request timestamp. Requests outside this drift may be rejected. | | Merchant-side callback verification | 5 minutes (recommended) | Recommended local anti-replay validation window for incoming callbacks. It is not the same as the platform request-acceptance threshold. | Read them as follows: * `10 seconds` applies to requests you send to GatePay. * `5 minutes` is a recommended merchant-side validation window when verifying callbacks. * If your security model requires a stricter callback window, you can reduce it as long as normal network delay is still tolerated. ## 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](/global/essentials/version/100/en/common/error) 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:** Keep merchant-initiated request timestamps within the 10-second acceptance window, and use a local callback-validation window such as 5 minutes for anti-replay checks. 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](/global/essentials/version/100/en/common/overview) - App configuration and credential setup * [Notification](/global/essentials/version/100/en/common/notification) - Detailed callback event handling * [Error Codes and Best Practices](/global/essentials/version/100/en/common/error) - Error code reference and troubleshooting # Balance Source: https://docs.gate.com/global/essentials/version/100/en/common/balance Account reconciliation is critical for maintaining financial accuracy and trust. This guide covers balance queries, fee verification, and funds ledger tracking for end-of-day and periodic reconciliation. ## Overview GatePay provides multiple reconciliation tools to ensure account accuracy: * **Balance Query**: Real-time available balance by currency * **Order Fee Query**: Verify fees and settlement amounts at the order level * **Funds Ledger Query**: Track all fund movements by transaction For request headers, signature rules, and callback verification, refer to [Authentication & Security](/global/essentials/version/100/en/common/authentication). *** ## Balance Query The balance query API retrieves the available balance of a merchant payment account by currency. For settlement, payout, and risk decisions, real-time query results must be used. ### Common Use Cases * **Pre-settlement validation**: Confirm available balance before initiating settlement * **Period-end snapshots**: Capture balance at close of business for accounting * **Operational monitoring**: Real-time balance alerts and thresholds * **Multi-currency management**: Track balances across different currencies ### API Reference **Endpoint:** `GET /v1/pay/balance/query` **Institutional Endpoint:** `POST /payment/open/institution/v1/balance` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `currencies` | array | No | List of currency codes to query (e.g., \["USDT", "BTC", "USD"]) | If no currencies are specified, the API returns balances for all currencies in the account. #### Response Fields | Field | Type | Description | | - | - | - | | `currency` | string | Currency code | | `available` | string | Balance available for immediate use | | `hold` | string | Amount held by pending orders or payouts | | `total` | string | Total balance (available + hold) | | `last_updated` | timestamp | Timestamp of last balance update | #### Example Request ```bash theme={null} curl -X GET "https://api.gatepay.io/v1/pay/balance/query?currencies=USDT,BTC,USD" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": [ { "currency": "USDT", "available": "10500.50", "hold": "499.50", "total": "11000.00", "last_updated": 1704067205000 }, { "currency": "BTC", "available": "0.25", "hold": "0.05", "total": "0.30", "last_updated": 1704067205000 }, { "currency": "USD", "available": "25000.00", "hold": "0.00", "total": "25000.00", "last_updated": 1704067205000 } ] } ``` ### Integration Steps 1. **Call the balance query API** using `GET /v1/pay/balance/query` with desired currencies 2. **Store balances** by currency in your merchant's local accounting system 3. **Compare with local records** to identify discrepancies 4. **Alert on thresholds** if balance falls below operational minimums *** ## Order Fee Query The order fee query API provides detailed fee breakdown and settlement amounts at the individual order level. Use this for financial reconciliation and exception investigation. ### Common Use Cases * **Financial reconciliation**: Verify fees match merchant expectations * **Multiple or partial payments**: Reconcile complex order scenarios * **Exception investigation**: Identify fee anomalies or discrepancies * **Settlement confirmation**: Confirm amounts before initiating payout ### API Reference **Endpoint:** `GET /api/open/v1/pay/order/fee/query` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `orderId` | string | Conditional | GatePay order ID | | `merchant_order_no` | string | Conditional | Merchant-generated order number | Provide either `orderId` or `merchant_order_no` (at least one required). #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | GatePay order ID | | `merchant_order_no` | string | Merchant order number | | `orderAmount` | string | Original order amount | | `payAmount` | string | Amount customer paid | | `settlementAmount` | string | Amount credited to merchant account | | `gatewayFee` | string | GatePay processing fee | | `networkFee` | string | Blockchain network fee (if applicable) | | `discountAmount` | string | Discounts or rebates applied | | `currency` | string | Settlement currency | | `status` | string | Order status | | `created_at` | timestamp | Order creation time | | `settled_at` | timestamp | Settlement completion time | #### Example Request ```bash theme={null} curl -X GET "https://api.gatepay.io/api/open/v1/pay/order/fee/query?merchant_order_no=ORDER_12345" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": { "orderId": "ORD_abc123", "merchant_order_no": "ORDER_12345", "orderAmount": "1000.00", "payAmount": "1000.00", "settlementAmount": "980.00", "gatewayFee": "20.00", "networkFee": "0.00", "discountAmount": "0.00", "currency": "USDT", "status": "SETTLED", "created_at": 1704067200000, "settled_at": 1704067800000 } } ``` ### Integration Steps 1. **Call the order fee query API** using `GET /api/open/v1/pay/order/fee/query` with order identifier 2. **Store the query result** alongside your local order master data 3. **Compare settlement amounts** with expected values 4. **Flag discrepancies** for manual review if fee structure differs *** ## Funds Ledger Query The funds ledger query provides a complete transaction history of all fund movements in and out of the merchant account. This is essential for audit trails and comprehensive reconciliation. ### Common Use Cases * **End-of-day reconciliation**: Aggregate all fund movements for the day * **Audit tracing**: Track fund origins and destinations for compliance * **Exception investigation**: Identify timing issues or missing transactions * **Financial reporting**: Generate detailed movement reports by type and currency ### API Reference **Endpoint:** `GET /v1/pay/bill/orderlist` **Institutional Endpoint:** `GET /payment/open/institution/v1/pay/bill/orderlist` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `start_time` | timestamp | No | Start of time range (UTC milliseconds) | | `end_time` | timestamp | No | End of time range (UTC milliseconds) | | `page` | integer | No | Page number for pagination (1-indexed, default 1) | | `limit` | integer | No | Records per page (default 20, max 100) | | `currency` | string | No | Filter by currency code | | `type` | string | No | Filter by transaction type (see enumeration below) | | `order_id` | string | No | Filter by related order ID | #### Response Fields | Field | Type | Description | | - | - | - | | `ledger_id` | string | Unique ledger entry identifier (use as deduplication key) | | `type` | string | Transaction type (see enumeration below) | | `currency` | string | Currency of transaction | | `amount` | string | Transaction amount (positive or negative) | | `balance_before` | string | Balance before transaction | | `balance_after` | string | Balance after transaction | | `business_id` | string | Related order, refund, transfer, or payout ID | | `description` | string | Human-readable description | | `created_at` | timestamp | Transaction timestamp (UTC milliseconds) | | `metadata` | object | Additional context (e.g., fee breakdown) | #### Transaction Type Enumeration | Type | Direction | Description | | - | - | - | | `PAYMENT` | Inbound | Customer payment received | | `PAYOUT` | Outbound | Settlement to merchant's bank account | | `REFUND` | Outbound | Refund issued to customer | | `TRANSFER_IN` | Inbound | Funds transferred from institution master account | | `TRANSFER_OUT` | Outbound | Funds transferred to sub-account or peer account | | `CHARGE` | Outbound | Platform commission or fee deduction | | `SWAP` | Neutral | Currency conversion (may show as two entries) | | `ADJUSTMENT` | Variable | Manual adjustment (credit or debit) | | `DEPOSIT` | Inbound | Direct deposit by merchant | #### Example Request ```bash theme={null} curl -X GET "https://api.gatepay.io/v1/pay/bill/orderlist?start_time=1704067200000&end_time=1704153600000&limit=50" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": [ { "ledger_id": "LED_20240101_001", "type": "PAYMENT", "currency": "USDT", "amount": "500.00", "balance_before": "10000.00", "balance_after": "10500.00", "business_id": "ORD_abc123", "description": "Payment from order ORDER_12345", "created_at": 1704067200000, "metadata": { "order_no": "ORDER_12345", "payer": "customer@example.com" } }, { "ledger_id": "LED_20240101_002", "type": "REFUND", "currency": "USDT", "amount": "-100.00", "balance_before": "10500.00", "balance_after": "10400.00", "business_id": "REF_xyz789", "description": "Refund for order ORDER_12346", "created_at": 1704067800000, "metadata": { "order_no": "ORDER_12346", "reason": "Customer requested" } }, { "ledger_id": "LED_20240101_003", "type": "TRANSFER_OUT", "currency": "USDT", "amount": "-1000.00", "balance_before": "10400.00", "balance_after": "9400.00", "business_id": "TRN_20240101", "description": "Transfer to sub-account", "created_at": 1704068400000, "metadata": { "account_id": "SUB_12345", "batch_no": "TRN_20240101" } } ], "pagination": { "page": 1, "limit": 50, "total": 3, "has_next": false } } ``` ### Integration Steps 1. **Pull funds ledger records** by time range with pagination using `GET /v1/pay/bill/orderlist` 2. **Persist ledger records** in your database using `ledger_id` as the primary deduplication key 3. **Associate ledger records** with business orders using `business_id` and metadata 4. **Generate reconciliation summaries** aggregated by: * Currency * Transaction type * Date or time bucket * Related business entity (order, refund, transfer, etc.) 5. **Compare with local records** to identify discrepancies 6. **Flag unmatched records** for investigation *** ## Recommended End-of-Day Reconciliation Flow Follow this step-by-step process for comprehensive daily reconciliation: ### Step 1: Capture Account Balance Snapshot ```bash theme={null} GET /v1/pay/balance/query ``` Store the balance snapshot for each currency at end of business day (e.g., 11:59 PM UTC). Record: * Available balance * Hold amount * Total balance * Snapshot timestamp ### Step 2: Pull Funds Ledger Records ```bash theme={null} GET /v1/pay/bill/orderlist?start_time={start_of_day}&end_time={end_of_day}&limit=100 ``` Retrieve all transactions for the reconciliation period with pagination. Store in local database keyed by `ledger_id`. ### Step 3: Pull Order Fees and Settlement Amounts For each order settled during the day: ```bash theme={null} GET /api/open/v1/pay/order/fee/query?merchant_order_no={order_id} ``` Store fee breakdown and settlement details. ### Step 4: Match and Reconcile Records Create a reconciliation table with the following structure: | Ledger ID | Type | Currency | Amount | Business ID | Matched | Notes | | - | - | - | - | - | - | - | | LED_001 | PAYMENT | USDT | +500 | ORD_123 | ✓ | Matched with order | | LED_002 | REFUND | USDT | -100 | REF_456 | ✓ | Matched with refund | | LED_003 | TRANSFER_OUT | USDT | -1000 | TRN_789 | ✓ | Institution transfer | **Matching logic:** * Match PAYMENT ledger entries to your order system using `business_id` * Match REFUND entries to your refund system * Match TRANSFER_OUT/IN entries to your transfer records * Match PAYOUT entries to your settlement records ### Step 5: Generate Discrepancy Report Identify records that do not match: | Category | Count | Details | | - | - | - | | Missing ledger entries | 0 | Orders with no corresponding ledger entry | | Extra ledger entries | 1 | Ledger entries with no corresponding order | | Amount mismatches | 0 | Matched records with different amounts | | Timing discrepancies | 2 | Entries recorded on different dates | ### Step 6: Perform Manual Review For each discrepancy: 1. **Review the ledger entry** description and metadata 2. **Correlate with business records** (orders, refunds, transfers) 3. **Investigate timing** (same-day vs. next-day settlement) 4. **Document resolution** (matched, explained, or escalated) ### Step 7: Output Reconciliation Result Generate a formal reconciliation statement: ``` End-of-Day Reconciliation Report Date: 2024-01-01 Start Balance (USDT): 10,000.00 Ending Balance (USDT): 9,900.00 Transactions: - Payments In: +5,000.00 - Refunds Out: -2,500.00 - Transfers Out: -1,000.00 - Fees Out: -500.00 - Adjustments: -100.00 Calculated Ending Balance: 9,900.00 Actual Ending Balance: 9,900.00 Status: BALANCED ✓ Discrepancies: 0 Unmatched Records: 0 ``` *** ## Error Handling and Troubleshooting ### Common Issues | Issue | Cause | Resolution | | - | - | - | | Balance differs from local records | Timing of settlement or fee posting | Query again after 5-10 minutes; check for pending transactions | | Missing ledger entries | Delayed posting or query time range misalignment | Expand time range by 1-2 hours; retry query | | Duplicate ledger entries | Database deduplication failure | Use `ledger_id` as primary key to prevent duplicates | | Fee discrepancies | Promotion, rebate, or rate change | Compare with current rate table; check for adjustments | For comprehensive error codes, see [Error Codes & Best Practices](/global/essentials/version/100/en/common/error). *** ## Best Practices ### Data Persistence * **Primary Key**: Use `ledger_id` for ledger entries to ensure idempotency * **Unique Constraints**: Enforce unique constraints on (ledger_id) to prevent duplicates * **Indexing**: Index by (`created_at`, `currency`, `type`) for fast reconciliation queries ### Query Optimization * **Time ranges**: Query in 24-hour buckets for faster response times * **Pagination**: Use `limit=100` and iterate through pages to avoid timeout * **Filters**: Use `currency` and `type` filters to reduce result sets ### Alerting and Monitoring * **Threshold alerts**: Alert when available balance falls below operational minimum * **Discrepancy alerts**: Alert immediately when reconciliation identifies unmatched records * **Timing alerts**: Alert if ledger entries are delayed by more than 2 hours * **Callback failure alerts**: Alert if expected callbacks are not received within SLA ### Documentation and Audit * **Reconciliation logs**: Store reconciliation results with timestamp and user ID * **Discrepancy tracking**: Maintain audit trail of identified and resolved discrepancies * **Rate cards**: Document fee structure and any promotional adjustments * **Settlement terms**: Document when and how funds are settled to merchant accounts *** ## Related Documentation * [Authentication & Security](/global/essentials/version/100/en/common/authentication) * [Institution API](/global/essentials/version/100/en/internalflow/institution) * [Notification & Callbacks](/global/essentials/version/100/en/common/notification) * [Error Codes & Best Practices](/global/essentials/version/100/en/common/error) * [Currency Conversion & Swap](/global/essentials/version/100/en/internalflow/swap) * [General Overview](/global/essentials/version/100/en/common/overview) # Error Source: https://docs.gate.com/global/essentials/version/100/en/common/error This guide covers GatePay API error codes and recommended practices for handling errors, callbacks, and asynchronous operations. ## General Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 400001 | Invalid request parameters | General | Check whether the request parameters are valid | | 400002 | Signature verification failed | General | Check the signature algorithm, signature string, and signing key. See [Authentication and Security](/global/essentials/version/100/en/common/authentication) | | 400003 | Request timestamp expired | General | Check the timestamp header | | 400007 | Unsupported Content-Type | General | Check whether Content-Type meets API requirements | | 400020 | Invalid nonce | General | Check whether X-GatePay-Nonce is empty or malformed | | 400201 | Duplicate merchant order number | Order-creation APIs | Check whether the same merchant order number was submitted repeatedly | | 400202 | Order not found | Query APIs | Check whether the order number is correct | | 400204 | Invalid order status | Order-operation APIs | Check whether the order is expired, cancelled, or closed | | 400603 | Order timed out | [Payment APIs](/global/essentials/version/100/en/inflow/payment/payment) | Confirm whether the order has expired | | 400621 | Incorrect payment amount | [Payment APIs](/global/essentials/version/100/en/inflow/payment/payment) | Check the requested amount | | 400622 | Conversion failed due to exchange-rate fluctuation | Quote / conversion APIs | Retry if permitted by business flow | | 400624 | Invalid callback URL | Order-creation APIs | Check whether the callback URL is valid. See [Notifications and Callbacks](/global/essentials/version/100/en/common/notification) | *** ## Batch Payout Error Codes For detailed payout error handling, see [Payout](/global/essentials/version/100/en/outflow/payout). | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 550233 | Insufficient balance | Batch payout | Check available balance | | 550234 | Memo too long | Batch payout | Check memo length | | 550235 | Amount precision exceeds the allowed range | Batch payout | Check amount precision | | 550238 | Too many sub-orders | Batch payout | Check the number of sub-orders | | 550239 | amount is missing | Batch payout | Provide the amount field | | 550240 | currency is missing | Batch payout | Provide the currency field | | 550241 | address is missing | Batch payout | Provide the address field | | 550242 | chain is missing | Batch payout | Provide the chain field | | 550245 | batch_id already exists | Batch payout | Use a new batch_id or handle as idempotent | | 550249 | Invalid batch_id or withdraw_order_id | Batch payout | Check field format | *** ## Funds Ledger Query Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 5504060 | Invalid orderType parameter (1=merchant order number, 2=GatePay order number, 3=funds ledger number) | Funds ledger query | Correct the orderType parameter | | 5504061 | Query size exceeds the limit (≤ 500) | Funds ledger query | Reduce the number of records requested per call | *** ## QR Payment Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 400000 | Invalid request format | QR payment | Check request data format | | 400002 | Signature verification failed | QR payment | Check whether the merchant signature is correct. See [Authentication and Security](/global/essentials/version/100/en/common/authentication) | | 400003 | Request timestamp expired | QR payment | Check the timestamp header | | 400007 | Unsupported media type | QR payment | Check the API Content-Type | | 400603 | Order timed out | QR payment | Confirm whether the order has expired | | 400621 | Incorrect payment amount | QR payment | Check the requested amount | | 400620 | Duplicate payment order | QR payment | Check whether the merchant order number was submitted repeatedly | | 500008 | Merchant not found | QR payment | Check whether the merchant ID is correct | | 500100 | Payment QR code has expired | QR payment | Create a new order to generate a new QR code | | 500101 | Duplicate QR payment | QR payment | Verify the order status | *** ## Web Payment Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 300000 | System error | Web payment | Retry with the same parameters | | 300001 | System error | Web payment | Retry with the same parameters | | 400000 | Unknown error | Web payment | Record the request, retry, or contact support | | 400001 | Invalid request parameter format | Web payment | Check the request parameters and data format | | 400002 | Signature verification failed | Web payment | Check whether the merchant signature is correct. See [Authentication and Security](/global/essentials/version/100/en/common/authentication) | *** ## Best Practices ### Callback and Query Fallback Strategy Use a "callbacks first, query as fallback" confirmation model for reliable order status management: **Recommended approach:** 1. **Rely on callbacks** as the primary notification mechanism (see [Notifications and Callbacks](/global/essentials/version/100/en/common/notification) for integration details) 2. **Implement signature verification** before processing any callback (see [Authentication and Security](/global/essentials/version/100/en/common/authentication)) 3. **Use idempotency** to handle duplicate callbacks safely 4. **Store notifications durably** before processing 5. **Implement state-machine control** for callback processing **Fallback Query Strategy:** If callbacks are missing or delayed, use progressive backoff for status queries: * 5 seconds * 10 seconds * 30 seconds * 1 minute * 3 minutes * 5 minutes This strategy prevents overwhelming the API while ensuring timely order confirmation. ### Refund Confirmation Refunds are asynchronous operations. A successful refund API response indicates only that the request has been accepted; it does not confirm the refund was actually processed. **Required practice:** * Confirm final refund results through the refund query API or refund callback (see [Payments](/global/essentials/version/100/en/inflow/payment/payment) for refund callback details) * Use the "callbacks first, query as fallback" pattern to verify refund completion * Never consider a refund complete based solely on the API response ### Security Best Practices **Authentication and Signature Verification** * Always verify callback signatures before processing (see [Authentication and Security](/global/essentials/version/100/en/common/authentication)) * Never return `SUCCESS` in a callback response if signature verification fails * Check the request timestamp to prevent replay attacks **Key Management** * Do not expose server-side signing keys or credentials in client applications * Store merchant secrets securely using environment variables or secure vaults * Rotate signing keys periodically and maintain separate keys for test and production environments **Request Validation** * Validate all request parameters before processing * Check Content-Type headers and ensure they match API requirements * Use HTTPS with TLS 1.2+ for all API communications *** ## Related Documentation * [Payments](/global/essentials/version/100/en/inflow/payment/payment) — Payment processing and refund handling * [Payout](/global/essentials/version/100/en/outflow/payout) — Payout error codes and handling * [Notifications and Callbacks](/global/essentials/version/100/en/common/notification) — Callback integration patterns * [Authentication and Security](/global/essentials/version/100/en/common/authentication) — Signature verification and security practices # Merchant MCP Source: https://docs.gate.com/global/essentials/version/100/en/common/merchantMcp Merchant MCP lets clients turn natural-language instructions into GatePay API calls for balance, order, and refund operations. ## Overview Model Context Protocol (MCP) is an open protocol for passing context between clients and external tools. Merchant MCP implements this protocol and acts as a bridge between your client and GatePay APIs. When a user issues a natural-language instruction, Merchant MCP maps it to the appropriate GatePay API request and returns the structured result. > [card] Merchant MCP can be connected through standard MCP clients and used to translate natural-language requests into GatePay API calls. ## How it works 1. The user sends a request such as "Check my USDT balance." 2. The client identifies the intent and calls a Merchant MCP tool such as `balances_get`. 3. Merchant MCP signs and forwards the request to GatePay by using the merchant's restricted API key. 4. GatePay returns the result, and Merchant MCP passes structured data back to the client. 5. The client presents the result in a user-friendly way. ## Installation and configuration ### Prerequisites 1. Complete GatePay merchant onboarding. 2. Create an app and obtain the payment secret, ClientId, and restricted API key. ### Client configuration Add the following JSON block to your MCP client settings. Replace the placeholders with real credentials, then restart or reload the client. ```json theme={null} { "mcpServers": { "gatepay": { "type": "stdio", "command": "npx", "args": ["-y", "payment-mcp"], "env": { "GATEPAY_CLIENT_ID": "CLIENT_ID", "GATEPAY_SECRET_KEY": "SECRET_KEY", "GATEPAY_RESTRICTED_KEY": "RESTRICTED_KEY", "GATEPAY_BASE_URL": "https://openplatform.gateapi.io/payment/open/api/mcp" } } } } ``` > [card] [Source code and additional notes](https://github.com/gate/gatepay-merchant-mcp) ### Restricted API key For production use, create a restricted API key for Merchant MCP and grant only the permissions required by the tools you plan to expose. 1. Sign in to the [GatePay merchant console](https://www.gate.com/zh/pay-merchant). 2. Open the developer center and create the payment secret and application. 3. Create a restricted API key and select only the permissions needed for your enabled tools. 4. Save the payment secret, ClientId, and restricted API key for later configuration. ## Supported tools Merchant MCP currently provides the following tools. | Capability | Tool | | - | - | | Query payout order status | withdrawQuery | | Query refund details by refund ID | v2PayRefundDetails | | Query exchange rates between fiat and crypto | rateQuery | | Query merchant available balance | v1Balance | | Query order details by order ID | v2QueryOrder | | Create a standard refund | v2StandardOrderRefund | | Query supported chains for a given receive currency | v1PayAddressChains | | Query supported currencies for Gate address payment | v1PayAddressCurrencies | | Create a fixed receiving address | fixedAddressCreate | | Create a payment link | payCode | ## FAQ ### Which clients are supported? Any client that supports MCP can connect by adding the `mcpServers` configuration shown above. ### Does Merchant MCP cache API responses? No. Each tool call is forwarded to GatePay in real time so the client receives the latest available data. ### How should API keys be protected? 1. Use a restricted API key with the minimum required permissions. 2. Pass credentials through environment variables instead of hardcoding them. 3. Prefer the hosted deployment model in production environments. ### How should failed tool calls be investigated? 1. Verify that the API key and secret are configured correctly. 2. Confirm that the restricted key includes the required permissions. 3. Confirm that network connectivity is available. 4. Check the Merchant MCP logs and the returned error code. ### Are batch operations supported? Current tools focus on single-request operations. For bulk workflows, clients can run multiple tool calls and aggregate the results at the application layer. # Notification Source: https://docs.gate.com/global/essentials/version/100/en/common/notification GatePay sends asynchronous notifications to your configured callback URL whenever order status changes. This guide covers the notification structure, callback types, and integration best practices. ## Processing Requirements For every callback received, you must: 1. **Verify the signature first** — See [Authentication and Security](/global/essentials/version/100/en/common/authentication) for signature verification details 2. **Parse the business data** and perform idempotent processing 3. **Return the agreed success response** Since the same business event may be delivered more than once, you must implement idempotency using a business-unique identifier. ## Recommended Processing Order To reduce the risk of duplicate processing, premature final-state decisions, or incorrect fund posting, process callbacks in the following order: 1. Validate headers and verify the signature 2. Parse `bizType`, `bizId`, and `bizStatus` 3. Run idempotency checks on the business-unique identifier 4. Update local business state 5. Return the success response 6. Use query APIs for final confirmation on critical fund events For payment, OTC, payout, and other fund-related flows, callbacks should usually be treated as the primary event source, while final confirmation for critical outcomes should still be verified through the relevant query APIs. ## Trigger and Retry Mechanism **Trigger** When the order status changes (payment success, timeout, cancellation, closure, or exception), GatePay sends a notification to your configured callback URL. **Retry** If you do not return the agreed success response or the request times out, GatePay will retry the callback. **Signature Verification** You must verify all callback signatures before processing. See [Authentication and Security](/global/essentials/version/100/en/common/authentication) for details. ## Callback Message Structure All callbacks contain the following top-level fields: | Field | Type | Description | | - | - | - | | bizType | string | Notification category (see [bizType Enumeration](#biztype-enumeration)) | | bizId | string | Order ID or business ID | | bizStatus | string | Business status (varies by bizType) | | client_id | string | Merchant client_id | | data | string | Business payload as a JSON string; call `JSON.parse` before use. Not used on `WITHDRAW` callbacks. Structure varies by `bizType` — see each notification subpage. | **Example Callback:** ```json theme={null} { "bizType": "PAY", "bizId": "6948484859590", "bizStatus": "PAY_SUCCESS", "client_id": "cdhu-fgrfg44-5ggd-cdvsa", "data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}" } ``` ## Callback Acknowledgement Response Return the following JSON response with HTTP 200: ```json theme={null} { "returnCode": "SUCCESS", "returnMessage": "" } ``` HTTP 200 status is recommended to indicate successful receipt. ## bizType Enumeration | Value | Description | | - | - | | PAY | Status change for non-address payment orders | | PAY_REFUND | Status change for refund orders | | PAY_BATCH | Status change for batch reward orders | | PAY_GIFT_BATCH | Status change for batch gift-card payments | | PAY_ADDRESS | Status change for address payment orders | | TRANSFER_ADDRESS | Funds-flow notification for address payments | | CHAIN_ADDRESS | On-chain transaction lifecycle notification for address payments | | PAY_FIXED_ADDRESS | Static-address collection notification | | WITHDRAW | Withdrawal / payout status change | | INSTITUTION | Institution API account-related notification | *** ## General Notes * This notification chapter explains the shared rules for payment, refund, address collection, static-address collection, payout, and institution-related callbacks. * Detailed callback interpretation for each business flow should still be read together with the corresponding product guide and API Reference. * If your integration uses multiple payment methods, route processing by `bizType` rather than assuming all callbacks share the same field set. * Do not rely on a single callback alone to finalize financial state changes in critical flows; combine callbacks with the appropriate query or detail endpoint when needed. ## Payment Product to bizType Mapping If your integration covers multiple payment products, define the internal routing model from product flow to `bizType` first: | Product or Scenario | Primary bizType | Notes | | - | - | - | | Hosted checkout, web launch, and ordinary non-address payment | `PAY` | Used for non-address payment order status changes | | Refund | `PAY_REFUND` | Used for refund-state progression | | Address payment | `PAY_ADDRESS` | Used for address payment order state changes | | Address-payment fund credit | `TRANSFER_ADDRESS` | Used for credit, delayed-credit, or risk-control outcomes | | Address-payment on-chain lifecycle | `CHAIN_ADDRESS` | Used for on-chain sync, compliance passed, and confirmation events | | Static-address collection | `PAY_FIXED_ADDRESS` | Used for static-address collection results | | Payout / withdrawal | `WITHDRAW` | Used for batch and sub-order status changes | | Institution sub-account related events | `INSTITUTION` | Used for institution account-opening results | This page already includes the event catalog summary and terminal-state handling guidance, so you can continue reading the business-specific sections below. ## Hosted Checkout Payment Notification Hosted checkout payments follow the general `PAY` callback model. For non-address payments, interpret the payment amount using `orderAmount`. For more details on payment integrations, see [Payments](/global/essentials/version/100/en/inflow/payment/payment). *** ## Refund Notifications Refund orders use the `PAY_REFUND` callback type. * Use the merchant-side unique identifier `refundRequestId` as the primary key for refund query and reconciliation. * API-initiated refunds and refunds triggered manually in the merchant console are different operational entry points; the callback description in this documentation applies to API integrations. * For reliable refund status handling, combine callbacks with the refund query endpoints. *** ## Address Payment Notifications ### PAY_ADDRESS Status Enumeration | Status | Applicable Mode | Description | | - | - | - | | PAY_SUCCESS | Non-convert / Convert | Payment succeeded | | PAY_ERROR | Non-convert / Convert | Payment failed | | PAY_CLOSE | Non-convert / Convert | Order closed | | PAY_EXPIRED_IN_PROCESS | Non-convert / Convert | Target amount reached within validity period, but still unconfirmed on-chain records | | PENDING | Convert | Pending | | PROCESS | Convert | Processing | | PAID | Convert | Paid | | EXPIRED | Convert | Expired | ### PAY_ADDRESS data Fields | Field | Applicable Mode | Description | | - | - | - | | merchantTradeNo | Non-convert / Convert | Merchant order number | | originalMerchantTradeNo | Non-convert / Convert | Associated original merchant order number (populated for supplementary-order scenarios) | | productType | Non-convert / Convert | Product type | | productName | Non-convert / Convert | Product name | | goodsName | Non-convert / Convert | Goods name | | tradeType | Non-convert / Convert | Transaction type | | terminalType | Non-convert / Convert | Terminal type | | currency | Non-convert / Convert | Pricing currency | | orderAmount | Non-convert / Convert | Order amount | | payerId | Non-convert / Convert | Payer identifier | | createTime | Non-convert / Convert | Creation time | | transactionId | Non-convert / Convert | Platform transaction ID | | waitAmountOnChain | Non-convert / Convert | On-chain amount detected but not yet finally credited | | doneAmountOnChain | Non-convert / Convert | On-chain amount already confirmed and credited | | channelId | Non-convert / Convert | Channel identifier | | chain | Non-convert / Convert | Chain name | | address | Non-convert / Convert | Collection address | | fromAddress | Non-convert / Convert | Payer address | | payCurrency | Convert | Payment currency used for conversion | | payAmount | Convert | Payment amount used for conversion | | rate | Convert | Exchange rate | | overPay | Convert | Overpayment amount | ### TRANSFER_ADDRESS Status Enumeration | Status | Description | | - | - | | TRANSFERRED_ADDRESS_IN_TERM | Credited within the validity period | | TRANSFERRED_ADDRESS_DELAY | Credited after the validity period | | CONVERT_ADDRESS_PAY_DELAY | Convert delayed-payment notification only; no credit | ### TRANSFER_ADDRESS data Fields | Field | Description | | - | - | | merchantTradeNo | Merchant order number | | originalMerchantTradeNo | Associated original merchant order number (populated for supplementary-order scenarios) | | originalOrderId | Associated original order ID (populated for supplementary-order scenarios) | | currency | Currency | | orderAmount | Order amount | | createTime | Creation time | | transactionId | Platform transaction ID | | transferAmount | On-chain transfer amount | | txHash | Blockchain transaction hash | | chain | Chain name | | address | Address | | channelId | Channel identifier | Note: In historical payloads or different business flows, the transaction hash field may appear as `txHash`, `tx_hash`, or `hash`, so parsers should handle these variants compatibly. ### CHAIN_ADDRESS Status Enumeration | Status | Description | | - | - | | PAY_PASSED | On-chain transaction compliance verification passed | | PAY_CONFIRMING | On-chain transaction sync started | | PAY_DONE | On-chain transaction confirmed | ### CHAIN_ADDRESS data Fields | Field | Type | Description | | - | - | - | | merchantTradeNo | string | Merchant order number | | productType | string | `goodsType` at order creation | | productName | string | `goodsName` at order creation | | clientId | string | Merchant `client_id` | | tradeType | string | `terminalType` at order creation | | goodsName | string | Goods name | | terminalType | string | Terminal type | | currency | string | Order currency | | orderAmount | number | Order amount | | payerId | int64 | Payer UID | | createTime | int64 | Order creation time (milliseconds) | | transferAmount | number | On-chain received amount | | txHash | string | On-chain transaction hash | | channelId | string | Channel identifier | | chain | string | Blockchain network | | address | string | Collection address | | fromAddress | string | Payer address | | passedTime | int64 | On-chain transaction compliance verification passed time (milliseconds); returned when `bizStatus=PAY_PASSED` | | confirmingTime | int64 | On-chain transaction sync started time (milliseconds); returned when `bizStatus=PAY_CONFIRMING` | | doneTime | int64 | On-chain transaction confirmed time (milliseconds); returned when `bizStatus=PAY_DONE` | *** ## Static Address Collection Notification **bizType:** `PAY_FIXED_ADDRESS` **bizStatus:** `PAY_SUCCESS` (credit succeeded) ### data Fields | Field | Type | Required | Description | | - | - | - | - | | channel_id | string | Yes | Channel identifier (snake_case; legacy payloads may use `channelId`) | | currency | string | Yes | Currency | | orderAmount | string | No | Order amount | | amount | string | Yes | Actual credited amount | | createTime | number | Yes | Creation time (milliseconds) | | transactionId | string | Yes | Platform transaction ID | | transactionTime | number | Yes | Transaction time (milliseconds) | | chain | string | Yes | Chain name | | address | string | Yes | Collection address | **Success Response:** ```json theme={null} { "returnCode": "SUCCESS", "returnMessage": "" } ``` *** ## Withdrawal / Payout Callbacks For withdrawal and payout operations, see [Payout](/global/essentials/version/100/en/outflow/payout) for detailed callback structures and field descriptions. **bizType:** `WITHDRAW` ### Main Order Fields | Field | Required | Description | | - | - | - | | batch_id | Yes | Batch ID | | merchant_id | Yes | Merchant ID | | status | Yes | INIT / PROCESSING / PARTIAL / FAIL / SUCCESS | | client_id | Yes | client_id used to create the batch | | pay_back_status | Yes | Rollback status | | channel_id | Yes | Channel identifier | ### Sub-order Fields | Field | Required | Description | | - | - | - | | suborder_id | Yes | Sub-order ID | | chain | Yes | Chain | | address | Yes | Address | | currency | Yes | Currency | | amount | Yes | Amount | | fee | Yes | Fee | | txHash | Yes | Transaction hash | | status | Yes | DONE / FAIL | | merchant_withdraw_id | Yes | Merchant withdrawal ID | | fee_type | Yes | 0=internal deduction; 1=external deduction | | finish_time | Yes | Completion time | | sub_amount | Yes | Total sub-order amount | | done_amount | Yes | Actually completed amount | *** ## Institution API Callbacks **bizType:** `INSTITUTION` **bizStatus:** `INSTITUTION_ACCOUNT_SUCCESS` or `INSTITUTION_ACCOUNT_FAIL` For institution account-related notifications, see [Institutional API](/global/essentials/version/100/en/internalflow/institution). ### data Fields (JSON string) | Field | Description | | - | - | | request_id | Request identifier | | account_id | Account ID | | customer_id | Customer ID | | display_name | Account display name | | status | ACTIVE or FAIL | | created | Timestamp in milliseconds | *** ## Callback Integration Guide ### Integration Requirements | Item | Recommendation | | - | - | | **Endpoint** | Use a dedicated path such as `/webhook/gatepay` | | **Protocol** | HTTPS with TLS 1.2+ | | **Processing Strategy** | Verify signature → store idempotently → process business asynchronously → return SUCCESS | | **Signature Verification** | Never return SUCCESS if signature verification fails | | **data Parsing** | The `data` field is a JSON string and requires secondary parsing | | **Duplicate Handling** | Support duplicate notifications using idempotent processing | ### Recommended Processing Flow 1. **Receive** the callback request 2. **Verify** the signature using the merchant secret key (see [Authentication and Security](/global/essentials/version/100/en/common/authentication)) 3. **Extract** and parse the `data` field (JSON string → object) 4. **Check** idempotency key (e.g., transactionId or merchantTradeNo) 5. **Store** the notification durably before processing 6. **Process** the business logic asynchronously 7. **Return** `{"returnCode": "SUCCESS", "returnMessage": ""}` with HTTP 200 This design ensures reliability and prevents duplicate processing. *** ## Related Documentation * [Authentication and Security](/global/essentials/version/100/en/common/authentication) — Signature verification and security practices * [Payments](/global/essentials/version/100/en/inflow/payment/payment) — Payment callback details * [Payout](/global/essentials/version/100/en/outflow/payout) — Payout callback details * [Institutional API](/global/essentials/version/100/en/internalflow/institution) — Institution callback details ## Event Catalog Summary ## Processing Model * Route processing by `bizType` first instead of assuming every callback shares the same field set * Then evaluate `bizStatus` to determine whether the event is intermediate or terminal * Finally apply idempotent updates keyed by business identifiers such as `merchantTradeNo`, `refundRequestId`, or `batch_id` ## Event Catalog | bizType | bizStatus | Business Meaning | Terminal | Recommended Action | | - | - | - | - | - | | `PAY` | `PAY_SUCCESS` | Non-address payment succeeded | Yes | Mark the order successful and continue fulfillment | | `PAY` | `PAY_ERROR` | Non-address payment failed | Yes | Mark the order failed and allow retry or manual handling | | `PAY` | `PAY_CLOSE` | Order closed | Yes | End the flow and stop polling | | `PAY_REFUND` | `REFUND_PROCESS` | Refund is processing | No | Mark refund as processing and continue waiting for callback or query | | `PAY_REFUND` | `REFUND_SUCCESS` | Refund succeeded | Yes | Mark refund as complete and reconcile funds | | `PAY_REFUND` | `REFUND_REJECTED` | Refund rejected | Yes | Mark refund failed and route to manual review | | `PAY_ADDRESS` | `PAY_SUCCESS` | Address payment succeeded | Yes | Mark the order successful and persist chain-side payment details | | `PAY_ADDRESS` | `PAY_EXPIRED_IN_PROCESS` | Target amount reached during validity period but on-chain records are still unconfirmed | No | Continue confirmation handling and avoid prematurely finalizing the order | | `TRANSFER_ADDRESS` | `TRANSFERRED_ADDRESS_IN_TERM` | Funds credited within the valid period | Yes | Mark funds as credited | | `TRANSFER_ADDRESS` | `TRANSFERRED_ADDRESS_DELAY` | Delayed credit | Yes | Mark delayed settlement and apply business-specific handling | | `TRANSFER_ADDRESS` | `CONVERT_ADDRESS_PAY_DELAY` | Delayed convert-address payment notice | No | Continue handling together with query results and order mode | | `CHAIN_ADDRESS` | `PAY_PASSED` | On-chain transaction compliance verification passed | No | Record the status during on-chain transaction and verification | | `CHAIN_ADDRESS` | `PAY_CONFIRMING` | On-chain transaction sync started | No | Record the status during on-chain transaction and verification | | `CHAIN_ADDRESS` | `PAY_DONE` | On-chain transaction confirmed | No | Record the status during on-chain transaction and verification | | `PAY_FIXED_ADDRESS` | `PAY_SUCCESS` | Static-address collection succeeded | Yes | Mark the collection as credited | | `WITHDRAW` | `WITHDRAW_SUCCESS` | Payout batch fully succeeded | Yes | Mark the batch successful and finalize reconciliation | | `WITHDRAW` | `WITHDRAW_PARTIAL` | Payout batch partially succeeded | Yes | Split handling between successful and failed sub-orders | | `WITHDRAW` | `WITHDRAW_FAIL` | Payout batch failed | Yes | Mark failed and route to retry or manual review | | `INSTITUTION` | `INSTITUTION_ACCOUNT_SUCCESS` | Sub-account creation succeeded | Yes | Record successful account creation | | `INSTITUTION` | `INSTITUTION_ACCOUNT_FAIL` | Sub-account creation failed | Yes | Record the failure and route for manual review | ## Terminal-State Handling Rules For terminal events, it is best to advance downstream business only after all of the following are true: 1. the signature has been verified 2. idempotency validation has passed 3. the event has been persisted 4. the local business record is updated consistently with the callback result ## Related Reading * [Notification](/global/essentials/version/100/en/common/notification) * [Quickstart](/global/essentials/version/100/en/common/quickstart) * [Payment](/global/essentials/version/100/en/inflow/payment/payment) * [Payout](/global/essentials/version/100/en/outflow/payout) * [OTC](/global/essentials/version/100/en/otc) # Overview Source: https://docs.gate.com/global/essentials/version/100/en/common/overview This guide introduces the prerequisites, base configuration, service endpoints, app creation, key management, and supported payment networks and currencies for GatePay external APIs. ## Recommended Reading Order If this is your first integration, the recommended reading order is: 1. [Quickstart](/global/essentials/version/100/en/common/quickstart) 2. [Merchant Access](/global/essentials/version/100/en/common/accessguide) 3. [Authentication](/global/essentials/version/100/en/common/authentication) 4. [Notification](/global/essentials/version/100/en/common/notification) 5. The guide and API Reference for your target product flow ## Merchant Onboarding and App Configuration ### Base URL | Component | Value | | - | - | | Service Base URL | `https://openplatform.gateapi.io` | All API paths in this documentation must be combined with the base URL to form the full request URL. ### Create and Configure an App Follow these steps to set up your application in the GatePay Merchant Portal: | Step | Action | | - | - | | 1 | Log in to the GatePay Merchant Portal and complete merchant registration and initial setup. | | 2 | Fill in the required business information and submit your merchant application. | | 3 | Navigate to the app configuration page and create or configure a new application. | | 4 | Retrieve your `ClientId` from the application list. | | 5 | Configure the callback URL as needed to receive asynchronous notifications. | ### Configuration Credentials After completing app configuration, you will receive the following credentials: | Credential | Description | | - | - | | `ClientId` | Unique identifier for your application. Used in all API requests via the `X-GatePay-Certificate-ClientId` header (see [Authentication and Security](/global/essentials/version/100/en/common/authentication) for details). | | Payment API Secret | Server-side signing key for payment-related API requests and signature verification. | | Authorization Secret | Server-side signing key for authorization API requests and signature verification (used only by authorization APIs). | | Callback URL | Endpoint configured to receive asynchronous payment notifications. | **Important:** Any API that uses asynchronous notifications requires a valid callback URL to be configured; otherwise, notifications cannot be delivered. For details on how to verify incoming callbacks, see [Authentication and Security](/global/essentials/version/100/en/common/authentication). ### Common Request Headers For most non-institution APIs, requests commonly use the following headers: | Header | Description | | - | - | | `X-GatePay-Certificate-ClientId` | Application identity | | `X-GatePay-Timestamp` | UTC timestamp in milliseconds | | `X-GatePay-Nonce` | Random nonce | | `X-GatePay-Signature` | Request signature generated from the signing rules | | `X-GatePay-On-Behalf-Of` | Institution-only delegated header. It is required on every institution API except `POST /merchant/open/institution/v1/accounts/create`, `GET /merchant/open/institution/v1/accounts/query`, and `GET /merchant/open/institution/v1/accounts/list`. | For full header, signing, and verification details, refer to the [Authentication and Security](/global/essentials/version/100/en/common/authentication) guide. ### SDK Support The latest official SDK and client repositories are maintained under the Gate GitHub organization: [https://github.com/gate](https://github.com/gate) The currently public multi-language SDK / client resources include: | Repository | Language | Description | | - | - | - | | `gatepay-sdk-java` | Java | GatePay Java repository, [repository](https://github.com/gate/gatepay-sdk-java) | | `gatepay-sdk-go` | Go | GatePay Go repository, [repository](https://github.com/gate/gatepay-sdk-go) | | `gatepay-sdk-python` | Python | GatePay Python SDK repository, [repository](https://github.com/gate/gatepay-sdk-python) | | `gatepay-sdk-android` | Android | GatePay Android SDK repository, [repository](https://github.com/gate/gatepay-sdk-android) | | `gatepay-sdk-ios` | iOS | GatePay iOS SDK repository, [repository](https://github.com/gate/gatepay-sdk-ios) | | `gatepay-call-payment-sdk-android` | Android Call Payment | GatePay Android Call Payment SDK repository, [repository](https://github.com/gate/gatepay-call-payment-sdk-android) | | `gatepay-call-payment-sdk-iOS` | iOS Call Payment | GatePay iOS Call Payment SDK repository, [repository](https://github.com/gate/gatepay-call-payment-sdk-iOS) | Use the Gate GitHub organization page as the source of truth for the latest repository list. If a specific flow does not yet have a ready-made SDK wrapper, you can still integrate directly through the REST APIs documented here. ## Supported Payment Networks and Currencies ### Blockchain Networks and Supported Cryptocurrencies The following networks and tokens are supported for address-based payments: | Blockchain Network | Supported Currencies | | - | - | | Ethereum / ERC20 | ETH, POL, USDC, USDT, USDS, USD1 | | Polygon | POL, USDC, USDT | | Arbitrum One / ERC20 | USDC, USDT | | BNB Smart Chain / BEP20 | BNB, USDT, USD1 | | Solana | SOL, USDC, USDT, BONK, USD1 | | Tron / TRC20 | TRX, USDT, USD1 | | Base | USDC | | The Open Network (TON memo) | USDT | | The Open Network (TON) | USDT | | Bitcoin BRC20 / Ordinals | BTC | | opBNB | USDT, USDC | ### Supported Currencies for Other Payment Channels The following cryptocurrencies and digital assets are supported across other payment methods: BTC, USDT, USD, USD1, GT, ETH, EOS, DOGE, DOT, SHIB, LTC, ADA, BCH, FIL, ZEC, BNB, UNI, XRP, STEPG, SUPE, LION, FROG, XAUT, BONK ## Next Steps * If you want to run the first end-to-end flow quickly, start with [Quickstart](/global/essentials/version/100/en/common/quickstart) * For authentication details and request signing, see [Authentication and Security](/global/essentials/version/100/en/common/authentication) * For payment API integration, refer to your specific payment flow documentation * For error handling and best practices, consult the error codes and troubleshooting guide # Quickstart Source: https://docs.gate.com/global/essentials/version/100/en/common/quickstart Run your first GatePay payment flow with the minimum path: signing, order creation, callback handling, and final query. ## Overview This page provides a minimum runnable path for merchants who want to complete their first GatePay payment flow from end to end. This document set focuses on the production integration flow. Before you begin integration, complete merchant onboarding, app creation, key setup, and callback URL configuration. If this is your first integration, use the following order: 1. Obtain `ClientId` and signing secrets 2. Generate the signed request headers 3. Create your first checkout order 4. Receive and verify the asynchronous callback 5. Use the query endpoint for final confirmation ## Step 1: Prepare Credentials After creating your application in the merchant console, prepare at least the following: | Credential | Purpose | | - | - | | `ClientId` | Sent through the `X-GatePay-Certificate-ClientId` header | | Payment API Secret | Used to sign payment-related requests | | Callback URL | Used to receive asynchronous notifications | If you have not completed this setup, see [Overview](/global/essentials/version/100/en/common/overview) and [Authentication](/global/essentials/version/100/en/common/authentication). ## Step 2: Build the Signed Headers At minimum, GatePay request signing uses these headers: * `X-GatePay-Certificate-ClientId` * `X-GatePay-Timestamp` * `X-GatePay-Nonce` * `X-GatePay-Signature` The core canonical string is: ```text theme={null} timestamp\nnonce\nbody\n ``` Integration recommendations: * use UTC milliseconds for `timestamp` * use a one-time random string for `nonce` * keep `body` exactly identical to the actual request payload * log the canonical string locally before signing during integration debugging ### Python signing example ```python theme={null} import hmac import hashlib timestamp = "1710000000000" nonce = "abc123xyz789" body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}' secret = "your_payment_api_secret" payload = f"{timestamp}\n{nonce}\n{body}\n" signature = hmac.new( secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha512, ).hexdigest() print(signature) ``` ### Node.js signing example ```javascript theme={null} const crypto = require("crypto"); const timestamp = "1710000000000"; const nonce = "abc123xyz789"; const body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}'; const secret = "your_payment_api_secret"; const payload = `${timestamp}\n${nonce}\n${body}\n`; const signature = crypto .createHmac("sha512", secret) .update(payload, "utf8") .digest("hex"); console.log(signature); ``` For the full signing rules, see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). ## Step 3: Create Your First Payment Order The hosted checkout flow is the fastest way to validate signing, order creation, callback handling, and order querying. **Request** ```http theme={null} POST /v1/pay/checkout/order ``` **Minimum request example** Notes: * Standard merchant API examples do not include `X-GatePay-On-Behalf-Of` in this temporary release. * In production integration, populate this header according to your subject-attribution model and the endpoint definition. ```bash theme={null} curl -X POST "https://openplatform.gateapi.io/v1/pay/checkout/order" \ -H "Content-Type: application/json" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1710000000000" \ -H "X-GatePay-Nonce: abc123xyz789" \ -H "X-GatePay-Signature: generated_signature" \ -d '{ "merchantTradeNo": "M202604150001", "currency": "USDT", "orderAmount": "10.00", "goods": { "goodsName": "Demo Order", "goodsDetail": "First payment integration test" }, "callbackUrl": "https://merchant.example.com/webhook/gatepay", "returnUrl": "https://merchant.example.com/result" }' ``` Use only the standard GatePay signed headers for ordinary merchant requests. **Key response fields** | Field | Description | | - | - | | `prepayId` | GatePay pre-order ID used for later queries | | `location` | Hosted checkout redirect URL | | `qrContent` | QR-content URL returned in some modes | After order creation, redirect the user with the returned `location` value directly. Do not construct the checkout page URL manually. ## Step 4: Receive the Callback After the user completes payment, GatePay sends an asynchronous callback to your configured callback URL. **Example callback** ```json theme={null} { "bizType": "PAY", "bizId": "6948484859590", "bizStatus": "PAY_SUCCESS", "client_id": "your_client_id", "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}" } ``` Your callback handler should at minimum: 1. verify the signature 2. apply idempotent business processing 3. update the local order state 4. return HTTP 200 with the agreed acknowledgement body For the unified callback model, see [Notification](/global/essentials/version/100/en/common/notification). ## Step 5: Query for Final Confirmation For payment flows, the recommended operating model is callbacks first and query as fallback. **Request** ```http theme={null} GET /v2/pay/order/query ``` **Minimum query example** ```bash theme={null} curl -X GET "https://openplatform.gateapi.io/v2/pay/order/query?merchantTradeNo=M202604150001" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1710000005000" \ -H "X-GatePay-Nonce: query123" \ -H "X-GatePay-Signature: generated_signature" \ ``` Treat these as two different integration signals: * callbacks for real-time business progression * queries for final confirmation and reconciliation ## Pre-Go-Live Checklist * `ClientId`, secret, and callback URL are confirmed * request signing and callback verification are implemented server-side * `merchantTradeNo` and `prepayId` are persisted * callback idempotency is implemented * query endpoints are integrated as fallback * monitoring and failure alerting are in place ## What to Read Next * For the full collection flow, continue with [Payment](/global/essentials/version/100/en/inflow/payment/payment) * For fiat settlement flows, continue with [OTC](/global/essentials/version/100/en/otc) * For outbound merchant transfers, continue with [Payout](/global/essentials/version/100/en/outflow/payout) # Reconciliation Source: https://docs.gate.com/global/essentials/version/100/en/common/reconciliation This document describes Gate Pay's reconciliation capabilities, applicable for end-of-day reconciliation, financial system synchronization, anomaly investigation, and audit tracking. ## Overview Gate Pay's reconciliation capability allows merchants to batch-pull order details via API within a specified time range. Additional order list query types and fund flow query capabilities will be added incrementally. Common use cases include: * End-of-day reconciliation of Gate Pay collection and payout data against internal ledgers * Integration with BI or data warehouses for scheduled order detail synchronization * Filtering by order number and status to investigate individual or batch anomalies * Serving as a fallback data source for payment/payout callbacks to confirm final status *** ## Prerequisites Before integrating reconciliation capabilities, complete the following preparation steps: 1. **Create an Application**: Create a GatePay application in the merchant backend 2. **Obtain ClientId**: Retrieve the ClientId used for API authentication 3. **Configure Signing Key**: Set up the key required for request signing 4. **Configure Callback URL**: Set the callback endpoint for receiving asynchronous notifications For detailed configuration instructions, refer to [Integration Overview](/global/essentials/version/100/en/common/overview) and [Authentication & Security](/global/essentials/version/100/en/common/authentication). *** ## Reconciliation Integration Steps ### Step 1: Pull Collection Order List Query collection orders paginated by creation time range, with filtering support by order type, status, payment method, etc. **Request Endpoint:** ```http theme={null} GET /payment/open/v1/pay/order/list ``` This endpoint retrieves collection order details within the specified time window, including order number, amount, status, fees, and on-chain information. See the API Reference for complete request and response parameters. ### Step 2: Pull Payout Order List Query payout orders paginated by creation time range, with filtering support by channel, order status, approval status, etc. **Request Endpoint:** ```http theme={null} GET /withdraw/open/v1/withdraw/suborder/query ``` This endpoint retrieves payout sub-order details within the specified time window, including batch number, amount, status, and on-chain information. See the API Reference for complete request and response parameters. ### Step 3: Reconcile with Internal Systems Compare the order data pulled in the previous two steps with the merchant's internal ledger, business systems, or financial records as needed to confirm data consistency. The specific reconciliation dimensions and process are defined by the merchant based on their own business requirements. ### Step 4: Fallback Query List queries can serve as a fallback mechanism to verify complete callback delivery, investigate discrepancies, or trace historical data. It is recommended to use callback processing and list pulling as complementary approaches rather than relying solely on one. *** ## Order Status ### Collection Order Status Common status values for collection orders: | Status | API Enum Value | Description | | - | - | - | | Pending Payment | `WAIT_PAY` | Order created, payment not yet completed | | Processing | `PAYING` | Payment processing | | Payment Successful | `PAY_SUCCESS` | Payment completed, eligible for credit reconciliation | | Payment Failed | `PAY_FAIL` | Payment unsuccessful | | Expired | `EXPIRED` | Exceeded valid payment time | | Cancelled | `CANCELLED` | Order cancelled | ### Payout Order Status Common status values for payout orders: | Status | API Enum Value | Description | | - | - | - | | Created | `CREATED` | Order created | | Pending | `PENDING` | Awaiting processing | | Under Review | `UNDER_REVIEW` | In approval workflow | | Processing | `PROCESSING` | Funds being processed | | Payout Successful | `PAYOUT_SUCCESS` | Payout completed, eligible for debit reconciliation | | Payout Failed | `PAYOUT_FAIL` | Payout unsuccessful or reversed | *** ## Error Handling The following typical issues may be encountered when querying lists: | Scenario | Description | Recommended Handling | | - | - | - | | Invalid Time Range | `endTime` / `end_time` is earlier than the start time, or the span exceeds limits | Split windows by day or hour; comply with span limits in the API Reference | | Pagination Parameter Error | `count` missing or exceeds maximum | Set a reasonable `count`, use `page` to paginate through large ranges | | Status Filter Mismatch | `status` passed does not belong to the current order type enumeration | Cross-reference the "Order Status" section and API Reference enum table | | Authentication Failure | Signature error or Key lacks query permissions | Check Payment API Secret, `X-GatePay-Signature`, and Key permission scope | | Data Volume Too Large | Single response timeout or rate limit triggered | Reduce time window, lower concurrency, schedule during off-peak hours if necessary | Recommendation: Use exponential backoff retry for transient errors like network timeouts; for permanent errors such as invalid parameters or insufficient permissions, fix the issue before making another request. *** ## Reconciliation & Audit ### End-of-Day Reconciliation Process It is recommended to regularly reconcile Gate Pay order data with internal system records: 1. **Define the Reconciliation Window**: Set `startTime` / `endTime` (collection) or `start_time` / `end_time` (payout) by business day 2. **Page Through List**: Call the collection and payout list endpoints respectively until there are no more pages 3. **Verify Amount Fields**: Confirm that amounts, fees, and settlement/received amounts match internal expectations 4. **Verify Final States**: Confirm that the number of final-state orders is consistent with callback processing records 5. **Retain Discrepancy Records**: Orders that cannot be automatically matched enter the manual review queue ### Discrepancy Investigation If an order is inconsistent with internal records, investigate using the following steps: 1. **Confirm Correlation Keys**: Verify that `merchantTradeNo` and `orderId` (collection), or `merchantWithdrawId` and `suborderId` (payout), correspond to the same transaction 2. **Check Order Status**: Confirm whether it is in an intermediate state (e.g., `PAYING`, `PROCESSING`) 3. **Verify Refunds and Partial Success**: Check `refund_amount` or payout failure reasons 4. **On-Chain Evidence**: In Web3 scenarios, use `hashes` / `txId` for secondary confirmation on a block explorer 5. **Fallback Single Query**: If necessary, call the single order detail endpoint or [Merchant MCP](/global/essentials/version/100/en/common/merchantMcp) tools for additional fields *** ## Request Signing & Verification All reconciliation requests must be signed using the Gate Pay unified signing mechanism: * Use the Payment API Secret to compute HMAC-SHA512 on the request body following the `timestamp\nnonce\nbody\n` pattern * Place the signature result in the request header `X-GatePay-Signature` For details on request signing and signature generation, refer to the [Authentication & Security](/global/essentials/version/100/en/common/authentication) documentation. *** ## Best Practices * **Split Pulls by Window**: For large time ranges, make batched requests by day or hour to avoid excessive data volume per request * **Dual-Channel Verification**: Use callbacks for real-time status and list endpoints for end-of-day fallback * **Unified Reconciliation Keys**: Establish fixed mapping rules for `merchantTradeNo` / `merchantWithdrawId` in internal systems * **Retain Raw Responses**: Keep raw API JSON from reconciliation tasks for audit and replay purposes * **Monitor Intermediate State Accumulation**: Set alerts for orders that remain in `PAYING` or `PROCESSING` for extended periods * **On-Chain Cross-Verification**: Use `hashes` / `txId` for secondary confirmation of critical Web3 transactions * **Daily Reconciliation**: Complete the previous day's full reconciliation by T+1 end of day * **Protect Signing Keys**: Payment API Secret must not appear in logs or be exposed to unauthorized personnel * **Monitor Rate Limits**: Control concurrency and request frequency during large-scale batch pulling * **Discrepancy Resolution Loop**: Establish manual review and supplementary order processes for records that cannot be automatically matched *** ## Related Documentation * [Integration Overview](/global/essentials/version/100/en/common/overview) * [Authentication & Security](/global/essentials/version/100/en/common/authentication) * [Notification & Callbacks](/global/essentials/version/100/en/common/notification) * [Balance](/global/essentials/version/100/en/common/balance) * [Payout](/global/essentials/version/100/en/outflow/payout) * [Error Codes & Best Practices](/global/essentials/version/100/en/common/error) # Sandbox Environment Source: https://docs.gate.com/global/essentials/version/100/en/common/sandbox The sandbox is an environment isolated from production for API integration testing and flow validation. No real funds are transferred. Sandbox data is test data only. Sandbox credentials and production credentials cannot be used interchangeably. ## Environment URLs | Environment | Base URL | Description | | - | - | - | | Sandbox | `https://openplatform-sandbox.gateapi.io` | Testing and integration | | Production | `https://openplatform.gateapi.io` | Production environment with real fund movements | Unless otherwise stated, API paths, signing rules, and response structures are the same as in production. ## Quick Start | Step | Action | | - | - | | 1. Register or sign in | [Open the Sandbox Merchant Console](https://www.gate.com/pay-merchant?source=doc) and register or sign in with email verification. | | 2. Obtain credentials | Get your `ClientId` and Payment API Secret in the merchant console, then configure a callback URL. See [Merchant Access](/global/essentials/version/100/en/common/accessguide). | | 3. Call APIs | Use the sandbox base URL to call the target APIs. Verify query APIs first, then create test orders or static payment QR codes. See [Quickstart](/global/essentials/version/100/en/common/quickstart). | | 4. Simulate payment | Trigger a simulated payment from the order details page, checkout page, or static payment QR code list to verify status transitions. | | 5. Verify callbacks | Confirm that webhook signature verification, idempotency, and status synchronization work correctly. | ## Currently Supported APIs Continuously expanding,API capabilities are released in phases. Refer to this list before integration testing.
Module API capability API path
Customer Management Create customer `/v1/pay/channelmanage/save`
Query customer `/v1/pay/channelmanage/list`
Update customer `/v1/pay/channelmanage/update`
Delete customer `/v1/pay/channelmanage/delete`
Static Address / Static Payment QR Code Query supported networks and currencies `/v1/pay/fixedaddress/chains`
Create a static payment address `/v1/pay/fixedaddress/save`
Create a static payment address on an EVM network `/merchant/open/v1/pay/fixedaddress/evm/save`
Query static payment address list `/v1/pay/fixedaddress/list`
View static payment address details `/v1/pay/fixedaddress/detail`
Delete static payment address `/v1/pay/fixedaddress/delete`
Query static payment QR code bill list `/v1/pay/fixedaddress/order/query`
Checkout Create checkout order `/v1/pay/checkout/order`
Query checkout order details `/v2/pay/order/query`
Address Payment Query supported chain list `/v1/pay/address/chains`
Query supported currency list `/v1/pay/address/currencies`
Query currencies available for conversion by order currency `/v1/pay/address/supportedconvertcurrencies`
Create order `/v1/pay/address/create`
Query payment order details `/v1/pay/address/query`
Query on-chain transaction details `/v1/pay/address/transactiondetail`
Verify address payment callbacks Subject to the current sandbox callback configuration
Refund Create refund `/v2/standard/order/refund`
Query refund details `/v2/pay/refund/details`
Query refund supported networks `/v2/refund/support/chains`
Address payment direct refund `/v1/pay/address/refund`
Web payment refund `/v1/pay/order/refund`
Query Web payment refund `/v1/pay/order/refund/query`
Withdrawal Create withdrawal order `/v1/pay/withdraw`
Query withdrawal order `/v1/pay/withdraw/query`
Query supported chains by currency `/v1/pay/wallet/currency_chains`
Query withdrawal fee `/v1/pay/wallet/withdraw_status`
Query withdrawal records `/v1/pay/wallet/withdrawals`
OTC OTC quote `/withdraw/open/otc/api/v1/quote`
Create deposit order `/payment/open/otc/api/recharge`
Confirm deposit payment `/payment/open/otc/api/recharge/confirm`
Cancel deposit order `/payment/open/otc/api/recharge/cancel`
Deposit order list `/payment/open/otc/api/recharge/list`
Deposit order detail `/payment/open/otc/api/recharge/detail`
Create withdrawal order `/withdraw/open/otc/api/order/create`
Withdrawal order list `/withdraw/open/otc/api/order/list`
Withdrawal order detail `/withdraw/open/otc/api/order/detail`
Query bank countries `/withdraw/open/otc/api/bank/country/list`
Query bank account list `/withdraw/open/otc/api/bank/list`
Create bank account `/withdraw/open/otc/api/bank/create`
Submit bank account materials `/withdraw/open/otc/api/bank/material/supplement`
Delete bank account `/withdraw/open/otc/api/bank/delete`
Institution Create transfer `/transfer/open/institution/v1/pay/transfer`
Query transfer details `/transfer/open/institution/v1/pay/transfer/detail`
Create charge `/transfer/open/institution/v1/pay/charge`
Query charge details `/transfer/open/institution/v1/pay/charges/detail`
Create sub-account `/merchant/open/institution/v1/accounts/create`
Update sub-account `/merchant/open/institution/v1/accounts/update`
Query sub-account details `/merchant/open/institution/v1/accounts/query`
List sub-accounts `/merchant/open/institution/v1/accounts/list`
Get certification URL `/cashier/open/v1/certification/url`
Query certification status `/cashier/open/v1/certification/verify/query`
Create fee rule `/rate/commission_rule`
Upgrade fee rule `/rate/commission_rule/upgrade`
Query fee rule details `/rate/commission_rule`
List fee rules `/rate/commission_rule/list`
## Simulation Capabilities The sandbox does not provide real clearing or settlement. Payments and refunds are triggered through simulation entry points only to verify status transitions and callbacks. | Business | Simulation | Entry point | | - | - | - | | Collection | Payment | Order details page Checkout page (checkout orders only) | | Static Payment QR Code | Payment | Static payment QR code list | | Refund | Refund | Collection order details page | ## Webhooks Notification payloads, signing methods, and retry rules are the same as in production. Trigger callbacks with simulated payments or refunds to validate signature verification and idempotent processing. See [Notification](/global/essentials/version/100/en/common/notification). ## Switch to Production * Change the base URL to `https://openplatform.gateapi.io` * Replace sandbox `ClientId` and API Secret with production credentials * Configure the production callback URL * Confirm that signing, signature verification, idempotency, and callback retry logic have passed testing * Complete a small real-order validation # Gift Card Source: https://docs.gate.com/global/essentials/version/100/en/inflow/payment/giftcard Gift card functionality allows merchants to create, manage, and track digital gift cards with customizable designs and templates. This guide covers the complete gift card lifecycle. ## Overview Gift cards are digital payment instruments that enable merchants to: * Create branded gift cards with custom cover designs * Issue cards with specified amounts and currencies * Track card status and redemption via the query API * Query merchant account currency balances (separate from any single card) when needed For request headers, signature rules, and callback verification, refer to [Authentication & Security](/global/essentials/version/100/en/common/authentication). ## API Reference ### Create Gift Card **Endpoint:** `POST /v1/pay/gift/create` Creates a new gift card with specified parameters. Responses use the standard `status` / `code` / `label` / `errorMessage` / `data` wrapper. On success, card fields such as `card_num`, `card_key`, and numeric `status` are inside `data`. #### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `title` | string | Yes | Gift card title or name. It must be a string; boolean, numeric, array, and object values are rejected | | `templateId` | string | Yes | Cover template ID for the gift card design | | `currency` | string | Yes | Gift card currency (e.g. `USDT`; use values supported by Gate Pay) | | `amount` | string | Yes | Gift card initial amount | #### Response Fields Responses use the common wrapper: `status`, `code`, `label`, `errorMessage`, and `data`. On success, the gift card payload is in `data`: | Field | Type | Description | | - | - | - | | `card_num` | string | Unique gift card number | | `card_key` | string | Redemption code | | `amount` | string | Gift card amount | | `currency` | string | Gift card currency | | `status` | integer | Gift card status (see [Gift card status codes](#gift-card-status-codes)) | | `card_temp_id` | string | Template (cover) ID | | `creator` | integer | Creator user ID | | `creator_name` | string | Creator display name | | `exchange_uid` | integer | Redeemer user ID (0 if none) | | `owner` | integer | Owner user ID | | `give_count` | integer | Number of times the card was gifted | | `last_give_time` | integer | Last gift time (timestamp; 0 if never) | | `create_time` | integer | Create time (Unix timestamp in milliseconds) | | `batchId` | string | Gift card batch id | #### Example Request ```json theme={null} { "title": "api create gift card1", "templateId": "255267012439183360", "currency": "USDT", "amount": "0.99" } ``` #### Example Response ```json theme={null} { "status": "SUCCESS", "code": "000000", "label": "", "errorMessage": "", "data": { "card_num": "2002356433468640", "card_key": "yJgkiqAVCwS0tC8W5D+t9iFqwtxp9CUSHGBFYDDJ608=", "amount": "0.99", "currency": "USDT", "status": 1, "card_temp_id": "255267012439183360", "creator": 10002, "creator_name": "GateUser-8118f6f8", "exchange_uid": 0, "owner": 10002, "give_count": 0, "last_give_time": 0, "create_time": 1737942105582, "batchId": "G545273793309741056" } } ``` If `title` is not a string, the request is rejected before a gift card is created and no business data is written: ```json theme={null} { "status": "FAIL", "code": "400001", "label": "MERCHANT_INVALID_REQUEST_PARAM", "errorMessage": "title must be a string", "data": {} } ``` ### Query Gift Card Cover Templates **Endpoint:** `GET /v1/pay/gift/temp/list` Retrieves available cover templates for gift card customization. #### Response Fields Successful responses use the common wrapper; templates are returned in `data` as an array. Each item has: | Field | Type | Description | | - | - | - | | `card_temp_id` | string | Cover (template) ID — use this value as `templateId` when creating a card | | `image_url` | string | Cover image URL | | `title_en` | string | English title | | `title_cn` | string | Chinese title | | `cover_type` | string | Cover type (e.g. `theme`,`festival`,`all`) | #### Example Response ```json theme={null} { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": [ { "card_temp_id": "293389550603997184", "image_url": "https://test-gateio-nft.s3.ap-northeast-1.amazonaws.com/image/688c908c72b1cb9b78039de44003b4f8de4009f5.jpg", "title_en": "anlitest", "title_cn": "anlitest常用", "cover_type": "theme" } ] } ``` ### Query merchant account balances **Endpoint:** `GET /v1/pay/balance` Returns balances for **all currencies available on the current merchant account** (account-level balances), not a single gift card. There are no query parameters; authentication headers apply as for other Pay APIs. #### Response Fields | Field | Type | Description | | - | - | - | | `data` | object | Map of currency code to balance string (e.g. `"USDT": "1000.50"`) | #### Example Response ```json theme={null} { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "ADA": "313.99963295", "ALGO": "0", "USDT": "1000.50" } } ``` ### Query Gift Card Details **Endpoint:** `POST /v1/pay/gift/query` Retrieves gift card details by **card number** or **redemption code**. Send a JSON body (not query string). Provide `card_number` and/or `key`; if both are sent, **`key` takes priority**. #### Request body | Field | Type | Required | Description | | - | - | - | - | | `card_number` | string | One of two | Gift card number | | `key` | string | One of two | Redemption code | #### Response Fields (`data`) | Field | Type | Description | | - | - | - | | `card_num` | string | Gift card number | | `key` | string | Redemption code | | `title` | string | Title | | `creator_name` | string | Creator display name | | `amount` | string | Gift card amount | | `status` | integer | Status code (see below) | | `currency` | string | Currency | | `card_temp_id` | string | Cover ID | | `create_time` | integer | Create time (milliseconds) | | `exchange_uid` | integer | Redeemer ID | | `exchange_time` | integer | Exchange time (milliseconds) | | `batch_id` | string | Gift card batch id | #### Example Request ```json theme={null} { "card_number": "5202710871862281" } ``` #### Example Response ```json theme={null} { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "card_num": "5607423016280059", "key": "94Q1UV7RMUEMNINL", "title": "anliAPI", "creator_name": "xuyi006", "amount": "0.0001", "status": 3, "currency": "USDT", "create_time": 1744717081334, "exchange_uid": 39992131, "exchange_time": 1776838077478, "card_temp_id": "346749173549240320", "batch_id": "G545273793309741056" } } ``` ### Batch query gift cards **Endpoint:** `POST /v1/pay/gift/batch/query` Returns a paginated list of gift cards created by the current merchant, filtered by batch ID or creation time range. When you provide both `batch_id` and a time range, the API returns records that match both filters. #### Request body | Field | Type | Required | Description | | - | - | - | - | | `batch_id` | string | Conditionally | Gift card batch ID, up to 64 characters. The API uses an exact match. Provide either `batch_id` or a complete time range | | `start_time` | integer | Conditionally | Inclusive creation time range start as a Unix timestamp in milliseconds. Must be provided with `end_time` | | `end_time` | integer | Conditionally | Inclusive creation time range end as a Unix timestamp in milliseconds. Must be provided with `start_time`; a single query cannot span more than 31 days | | `page` | integer | No | Page number starting from 1. Default: 1 | | `page_size` | integer | No | Number of records per page. Default: 20; maximum: 100 | #### Example request ```json theme={null} { "batch_id": "G545273793309741056", "start_time": 1791916618083, "end_time": 1791939618083, "page": 1, "page_size": 20 } ``` #### Response fields (`data`) | Field | Type | Description | | - | - | - | | `total` | integer | Total number of matching records | | `has_more` | boolean | Whether another page is available. When `true`, query `page+1` to continue | | `list` | array | Gift cards on the current page | | `list[].batch_id` | string | Gift card batch ID | | `list[].card_num` | string | Gift card number | | `list[].key` | string | Redemption code | | `list[].title` | string | Gift card title | | `list[].creator_name` | string | Gift card creator name | | `list[].amount` | string | Gift card amount | | `list[].status` | string | Status code. This endpoint returns only string values `0`–`8`; see the table below | | `list[].currency` | string | Gift card currency | | `list[].card_temp_id` | string | Gift card cover ID | | `list[].create_time` | integer | Creation time as a Unix timestamp in milliseconds | | `list[].exchange_uid` | integer | Redeemer ID | | `list[].exchange_time` | integer or null | Redemption time as a Unix timestamp in milliseconds; null if the card has not been redeemed | #### Example response ```json theme={null} { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "total": 1, "has_more": false, "list": [ { "batch_id": "G545273793309741056", "card_num": "5607423016280059", "key": "EXAMPLE-REDEEM-CODE", "title": "Festival Gift Card", "creator_name": "GateUser-8118f6f8", "amount": "0.99", "status": "3", "currency": "USDT", "card_temp_id": "346749173549240320", "create_time": 1791920000000, "exchange_uid": 39992131, "exchange_time": 1791923600000 } ] } } ``` ## Gift card status codes The create and single-card query endpoints return `status` as an **integer**. The batch query endpoint returns `list[].status` as the **string form** of public status codes `0`–`8`. It does not expose internal extension statuses `9`–`11`; those values are returned as `0`: | Code | Meaning | | - | - | | `0` | Unknown | | `1` | Pending payment | | `2` | Not redeemed | | `3` | Redeemed (cashed out) | | `4` | Frozen | | `5` | Payment failed | | `6` | Manual review | | `7` | Review rejected | | `8` | Review payment failed | | `9` | Soft-deleted | | `10` | Gifting in progress | | `11` | Voided | ## Callback Behavior Gift cards do not provide asynchronous callbacks. Retrieve a single card’s status and details with `POST /v1/pay/gift/query`, or use `POST /v1/pay/gift/batch/query` to page through cards by batch or creation time. Use `GET /v1/pay/balance` when you need the merchant account’s multi-currency balances, not a per-card balance. For information on callback handling for other products, see [Notification & Callbacks](/global/essentials/version/100/en/common/notification). ## Error Handling Common platform error codes and how to resolve them are listed below. When querying a gift card, an incorrect key or card number may return `5003000`. | Error Code | Description | Resolution | | - | - | - | | `400007` | Unsupported media type | Check which media types the API accepts | | `400004` | `api_key` not found in the request | In the request header, pass the `api_key` from registration using `X-GatePay-Certificate-ClientId` | | `400020` | Missing Nonce random string for signing | In the request header, pass the random string used to build the signature using `X-GatePay-Nonce` | | `400002` | Invalid signature | Verify the signing algorithm | | `400001` | Invalid request parameters or format | Check required parameters, field types, and values; for example, `title` must be a string | | `400621` | Order amount is incorrect | Check the order amount fields | | `400003` | Timestamp is incorrect | Check whether X-GatePay-Timestamp is earlier than the current time or more than 10 seconds ahead of the request time | | `400201` | A payment order for this merchant’s `merchantTradeNo` already exists | Check for duplicate creation | | `400620` | Duplicate refund order | Check for duplicate requests | | `400604` | The address payment order to refund is not in a terminal state (expired or completed) | Wait until the order reaches a final state before refunding | | `400608` | Refund amount invalid: ≤ 0 or exceeds the payment order amount | Check the refund amount | | `400607` | Refund attempts for one payment order exceed the limit | Only one refund is allowed per payment order | | `500008` | Merchant not found | Confirm `X-GatePay-Certificate-ClientId` carries the `api_key` issued at merchant registration | | `500200` | No Gate address-payment address is available | No payout address available when creating the order | | `5003000` | Gift card not found | Check the gift card key or card number | For more error codes and best practices, see [Error Codes & Best Practices](/global/essentials/version/100/en/common/error). ## Integration Guide ### Minimum runnable path ```text theme={null} List templates -> Create gift card -> Store card_num and card_key securely -> Distribute to the user -> Query card details (POST /v1/pay/gift/query); use GET /v1/pay/balance for merchant account balances if needed ``` For a first integration, validate the lifecycle of a single gift card first, then expand to batch issuance, campaign fulfillment, or membership-related use cases. ### Basic Flow 1. **Retrieve available templates** using `GET /v1/pay/gift/temp/list` 2. **Create a gift card** using `POST /v1/pay/gift/create` with your chosen template 3. **Store the card details** (`card_num` and `card_key` from the create response) securely 4. **Distribute the gift card** to your customer 5. **Query one card’s details** with `POST /v1/pay/gift/query` (body: `card_number` and/or `key`), or **page through gift cards** with `POST /v1/pay/gift/batch/query`. Use `GET /v1/pay/balance` only for merchant account currency balances ### Best Practices * Store both `card_num` and `card_key` for lookups; the query API accepts `card_number` or `key` in the JSON body (if both are sent, `key` wins) * For batch queries, provide `start_time` and `end_time` together. When `has_more` is `true`, increment `page` to continue * Use [Gift card status codes](#gift-card-status-codes) when branching, and handle the integer or string field type documented for each endpoint * Use `card_temp_id` from the template list as `templateId` when creating a card * `GET /v1/pay/balance` reflects merchant account funds by currency, not an individual gift card’s remaining value ## Related Documentation * [Authentication & Security](/global/essentials/version/100/en/common/authentication) * [Notification & Callbacks](/global/essentials/version/100/en/common/notification) * [Error Codes & Best Practices](/global/essentials/version/100/en/common/error) * [Account Queries and Reconciliation](/global/essentials/version/100/en/common/balance) * [Payments Overview](/global/essentials/version/100/en/inflow/payment/payment) # Payment Source: https://docs.gate.com/global/essentials/version/100/en/inflow/payment/payment This guide introduces GatePay's core collection products, including hosted checkout payments, address payments, static-address payments, and client-side payment launch flows. ## Overview GatePay provides multiple payment collection methods to accommodate different merchant and user scenarios: * **Hosted Checkout Payments**: GatePay-managed payment UI supporting QR-code and on-chain dynamic address payments * **Address Payments**: Direct payment to dynamically generated or static collection addresses * **Payment Launch**: Mobile and client-side integration for in-app payment flows *** ## Hosted Checkout Payments ### Product Overview Hosted checkout payment is a full-featured, GatePay-hosted collection capability. Merchants do not need to build their own payment user interface. GatePay handles both: * QR-code payments * On-chain dynamic address payments (Web3) ### Payment Flow The hosted checkout payment flow consists of three main steps: 1. **Pre-order Creation**: The merchant creates a pre-order and receives redirect information from the API. 2. **User Redirection**: The merchant redirects the user to the GatePay hosted checkout page using the provided `location` URL. 3. **Asynchronous Notification**: After the user completes payment, GatePay asynchronously notifies the merchant backend of the order status via callback. **Important**: The merchant must not construct the checkout URL manually. Always use the `location` value returned by the API. ### Query Supported Chains **Request**: ``` GET /v1/pay/address/chains ``` Query the list of supported blockchain networks for Web3 address payments. This endpoint helps you determine which chains are available for your payment currency. ### Create Hosted Checkout Order **Request**: ``` POST /v1/pay/checkout/order ``` Creates a new hosted checkout order. Upon success, the API returns a `location` field that you must use to redirect the user. This URL is the only valid entry point to the GatePay hosted checkout page. #### Request Parameters The exact request body depends on the collection mode and the capabilities enabled for your account. In practice, checkout requests often combine several categories of information: * order identity, amount, and currency * user or terminal context * goods or display information * redirect or notification settings when supported by the specific API * chain and asset-related fields for crypto payment scenarios If this is your first integration, the safest approach is to implement against the corresponding API Reference page and OpenAPI schema directly instead of relying on a shortened parameter summary from the guide. #### Response Fields | Field | Type | Description | | - | - | - | | `prepayId` | string | GatePay pre-order ID for tracking and queries | | `location` | string | Hosted checkout redirect URL. Redirect the user to this URL. | | `qrContent` | string | QR code content for QR-based payment (if applicable) | #### Minimum Runnable Example If your goal is to get the first payment flow working quickly, the example below is more useful than treating the guide as a complete field reference. **Create order** ```bash theme={null} curl -X POST "https://openplatform.gateapi.io/v1/pay/checkout/order" \ -H "Content-Type: application/json" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1710000000000" \ -H "X-GatePay-Nonce: checkout001" \ -H "X-GatePay-Signature: generated_signature" \ -d '{ "merchantTradeNo": "M202604150001", "currency": "USDT", "orderAmount": "10.00", "goods": { "goodsName": "Demo Order", "goodsDetail": "Checkout quickstart" }, "callbackUrl": "https://merchant.example.com/webhook/gatepay", "returnUrl": "https://merchant.example.com/result" }' ``` **Typical success-response focus** * persist `prepayId` * read `location` * redirect the user with `location` **Recommended next steps** 1. wait for the `PAY` callback 2. call `GET /v2/pay/order/query` for final confirmation 3. persist both `merchantTradeNo` and `prepayId` for reconciliation ### Query Order Result **Request**: ``` GET /v2/pay/order/query ``` Query the current status and details of an order. This endpoint is essential for payment confirmation and reconciliation. It is best to treat this endpoint as the final confirmation source for payment results, not only as an exception-handling tool. Even after a successful callback has been received, merchants can still use this query for reconciliation or high-value order confirmation. #### Query Entry by Payment Method * Hosted checkout payment: `GET /v2/pay/order/query` * Address payment: `GET /v1/pay/address/query` * QR / web-launch payment: use the actual query endpoint exposed by the corresponding API Reference page for that product flow Do not mix query endpoints across different product lines. Even where field names look similar, status semantics, amount interpretation, and supplemental fields may differ. #### Payment Amount Handling The interpretation of payment amounts differs based on order type: * **Gate Payments** (non-address): The final paid amount is represented by `orderAmount`. * **Address Payments**: Both `waitAmountOnChain` and `doneAmountOnChain` must be considered: * `waitAmountOnChain`: On-chain amount already detected but not yet finally confirmed * `doneAmountOnChain`: On-chain amount already confirmed and credited to the merchant account ### Signed Requests and Callbacks For security details on request signing and callback verification, see [Authentication and Security](/global/essentials/version/100/en/common/authentication). *** ## Address Payments Address payments enable direct collection to blockchain addresses. The system dynamically generates payment addresses based on order parameters or uses pre-configured static addresses. ### Typical Integration Flow 1. **Chain Query**: Query supported chains for your order currency. 2. **Order Creation**: Create Order: The system will generate and return a unique receiving address. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). 3. **User Payment**: User transfers funds to the collection address. 4. **Payment Detection**: GatePay detects the on-chain transaction and notifies your backend via callback. 5. **Result Confirmation**: Confirm payment via callbacks or use the query API as a fallback. ### Order Statuses Common `PAY_ADDRESS` order statuses: | Status | Description | | - | - | | `PAY_SUCCESS` | Payment succeeded and funds are credited | | `PAY_ERROR` | Payment failed; funds were not credited | | `PAY_CLOSE` | Order was closed by the merchant or system | | `PAY_EXPIRED_IN_PROCESS` | Order validity period expired, but some on-chain transactions remain unconfirmed. Funds may still be credited after confirmation. | ### Payment Mode Selection: Non-Convert vs. Convert **Non-Convert Mode**: Funds are credited in the original payment currency. **Convert Mode**: Funds are converted to a different currency before crediting. For convert mode orders, you may need to query supported conversion currencies. #### Query Supported Conversion Currencies (Convert Mode Only) **Request**: ``` GET /v1/pay/address/supportedconvertcurrencies ``` Lists currencies that support automatic conversion for address payments. #### Create Address Payment Order **Request**: ``` POST /v1/pay/address/create ``` The system will generate and return a unique receiving address. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). When switching between non-convert and convert modes, make sure your team aligns on how payment currency, settlement currency, and callback fields should be interpreted. This avoids mixing business meanings across two different settlement models. #### Query Address Payment Order **Request**: ``` GET /v1/pay/address/query ``` Query the current status of an address payment order, including on-chain detection results and confirmation status. *** ## Static Address Payments Static Address Payment supports merchants in configuring fixed receiving addresses for long-term or recurring payment scenarios. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). Applicable scenarios include: * Subscription or recurring billing * Tip jars or fundraising pages * Merchant settlement accounts * Commission distribution ### How It Works 1. **Configure Static Address**: Use the save API to configure a fixed receiving address for a specified channel and blockchain. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). 2. **Reuse Address**: Reuse the same address and Memo (if applicable) across multiple orders without generating a new address each time. 3. **Automatic Detection**: GatePay detects payments to the static address and sends notifications. If a configuration already exists for the same `channelId` and `chain`, the API updates it. #### Save or Update Static Address Configuration **Request**: ``` POST /v1/pay/fixedaddress/save ``` Saves or updates a static address configuration for a specified `channelId` and blockchain network (`chain`). *** ## Payment Launch Payment launch enables in-app payment experiences for mobile applications or client-side web applications. This flow allows users to initiate payments directly from your application without leaving the app. ### Integration Steps 1. **Server-Side Pre-order**: Create a pre-order on your backend using the checkout order endpoint. 2. **Client Launch**: Pass the `prepayId` to your client application. 3. **Client Query**: The client can optionally query the order status for UI updates. 4. **Parameter Validation**: Validate payment parameters before launching the payment flow. 5. **Final Confirmation**: After the user returns, confirm payment status via server-side query. #### Client SDK Parameter Validation **Request**: ``` POST /v1/pay/open/sdk ``` Validates payment parameters and prepares the SDK for payment launch. Use this endpoint to validate `prepayId` and other parameters before initiating the client payment flow. #### Server-Side Pre-order Response Fields When you create a pre-order for payment launch, the response includes: | Field | Type | Description | | - | - | - | | `prepayId` | string | Pre-order ID to pass to the client SDK | | `location` | string | Redirect URL (used for web-based payment launch) | | `qrContent` | string | QR code content (optional, for QR-based flows) | #### Client Return and Payment Confirmation **Critical**: After the client application returns to your merchant page, the redirect result or client status must **NOT** be treated as the final payment result. Always confirm payment status through a server-side query to `GET /v2/pay/order/query`. This ensures: * Accurate payment state in your system * Proper handling of pending or delayed payments * Fraud detection and reconciliation *** ## Payment Validity and Expiration ### Default Validity Period By default, an order remains valid for **1 hour** from creation time. This is configurable via the `orderExpireTime` parameter. ### Delayed Payment Handling If a blockchain transaction is submitted after the order's expiration time, the payment is classified as a delayed payment. GatePay supports two handling modes: * **Non-Convert Delayed Payment**: Funds are still credited to the merchant account after on-chain confirmation, even though the order is expired. * **Convert Delayed Payment**: User funds do not enter the merchant payment account. The order is treated as failed. *** ## Refunds GatePay provides two refund APIs for backward compatibility: ### Standard Refund (Recommended) **Request**: ``` POST /v2/pay/order/refund ``` Standard refund endpoint for new integrations. Use this for all new implementations. ### Compatibility Refund (Legacy) **Request**: ``` POST /v1/pay/order/refund ``` Legacy refund endpoint. Maintained for existing integrations only. New integrations must use the v2 endpoint. Be careful to distinguish between: * API-initiated refunds: integrate according to the endpoint and callback model described in this documentation * Merchant-console manual refunds: progress visibility is based on the merchant console and should not be assumed to follow the same API callback cadence *** ## Callbacks and Asynchronous Notifications All payment methods support asynchronous callbacks to notify your backend of order status changes. For complete callback details, payload schemas, signing, and verification, see [Notification](/global/essentials/version/100/en/common/notification). GatePay guarantees: * Callbacks are sent according to the callback configuration or callback parameter defined for the specific order flow * Callbacks include signed payloads for security verification * Multiple callback attempts if the initial delivery fails For payment integrations, a reliable operating pattern is to use callbacks to advance the business workflow and use order queries as the final fallback and reconciliation source. If you prefer to start from a complete end-to-end flow instead of reading product sections one by one, see [Quickstart](/global/essentials/version/100/en/common/quickstart). *** ## Best Practices 1. **Always Verify Callbacks**: Use the signature provided with each callback for verification. See [Authentication and Security](/global/essentials/version/100/en/common/authentication). 2. **Use Query as Fallback**: If callback delivery is delayed or missed, use the query endpoints for reconciliation. 3. **Handle Delayed Payments**: Implement logic to handle payments that arrive after order expiration. 4. **Monitor Amount Fields**: For address payments, always check both `waitAmountOnChain` and `doneAmountOnChain` to get the complete payment picture. 5. **Store prepayId**: Keep the `prepayId` returned from order creation for tracking and support purposes. 6. **Implement Idempotency**: Use unique `merchantTradeNo` values to prevent duplicate orders. *** ## Related Documentation * [Notification](/global/essentials/version/100/en/common/notification) * [Authentication and Security](/global/essentials/version/100/en/common/authentication) * [Overview](/global/essentials/version/100/en/common/overview) * [Quickstart](/global/essentials/version/100/en/common/quickstart) # Subscription Source: https://docs.gate.com/global/essentials/version/100/en/inflow/payment/subscription Covers subscription payment product setup, plan management, authorization, deduction modes, and querying recurring or on-demand debit status. ## Overview Subscription payment fits memberships, SaaS, recurring services, and any scenario that needs ongoing authorization and debits. Products are split into two capability classes, distinguished by `priceType` on the product price: | `priceType` | Capability | How debits work | | - | - | - | | `FIX_AMOUNT` | Fixed amount debited on the plan’s billing cycle | After the user authorizes, the platform runs recurring debits according to the merchant’s subscription plan | | `ACCOUNT_AUTH` | Account authorization; the merchant decides when to debit | After the user authorizes, the merchant initiates debits when the business requires | Compared with one-time payments, subscriptions emphasize long-term lifecycle management. Beyond placing orders and authorization, merchants should monitor plan or authorization scope, debit outcomes, retries, and termination rules. ## Standard integration flow Both product types share the same main path: create product → create plan → create subscription order → guide the user to authorize. They diverge **after** authorization succeeds: ```text theme={null} theme={null} Create product -> Create plan -> Create subscription order -> Guide user authorization -> [Debit phase branches by priceType] -> Query and notification tracking ``` ### Debit phase branches * **FIX_AMOUNT**: After authorization → recurring debits (automatic per plan) → query and notification tracking * **ACCOUNT_AUTH**: After authorization → merchant-initiated debits on demand → query and notification tracking ## Minimum runnable path For a first integration, run the smallest path end to end, then add trials, first-period discounts, and completion rules. ```text theme={null} theme={null} Create product -> Create plan -> Create subscription order -> Open subscriptionLink to authorize -> Receive debit notifications -> Query order and debit details to confirm ``` * **FIX_AMOUNT**: After this path works, focus on automatic cycle debits and failure retries. * **ACCOUNT_AUTH**: After authorization, trigger debits from your backend and still confirm via notifications + queries. ### Step 1: Create products Create subscription products and pricing first to define what is sold, billing currency, and presentation. When creating a price, set `priceType` so you know whether debits are cyclic or merchant-initiated after auth. Core APIs: * `POST /merchant/open/v1/pay/merchant/product/create` * `GET /merchant/open/v1/pay/merchant/product/pageQuery` * `GET /merchant/open/v1/pay/merchant/product/queryOne` ### Step 2: Create subscription plans Plans define rules such as billing cycle, trial, end conditions, and promotions. Associate each plan with the product or price created earlier. Core APIs: * `POST /open/v1/plan/save` * `GET /open/v1/plan/list` * `GET /open/v1/plan/detail` ### Step 3: Create subscription orders When the user confirms purchase, your backend creates a subscription order. The response includes `subscriptionLink` for the authorization page. Core APIs: * `POST /open/v1/order/create` * `GET /open/v1/order/list` * `GET /open/v1/order/detail` ### Step 4: Guide the user through authorization Redirect the user to `subscriptionLink` to complete authorization. * **FIX_AMOUNT**: After authorization, the subscription enters the planned recurring debit phase. * **ACCOUNT_AUTH**: After authorization, you hold account debit authorization; call `POST /open/v1/order/deduct` from your server when you need to debit. ### Step 5: Track order and debit status Prefer **notifications** for subscription order status and each debit outcome; use **query APIs** as a fallback. Core APIs: * `GET /open/v1/deduction/order/list` * `GET /open/v1/deduction/order/detail` * `POST /open/v1/order/deduct` (merchant-initiated debit for `ACCOUNT_AUTH`) Webhooks (see API Reference): * `subscriptionOrderWebhook`: subscription order status updates * `subscriptionOrderPaymentWebhook`: payment / deduction notifications ## Integration notes * Store separate business IDs for products, plans, and orders to simplify reconciliation and support. * After order creation, send users to authorization quickly to reduce drop-off. * Treat “subscription order status” and “debit status” as two related but separate tracks; for `ACCOUNT_AUTH`, also distinguish **authorized amount** vs **total debited**. * **FIX_AMOUNT**: recurring debits are ongoing—do not infer long-term health from a single API response. * **ACCOUNT_AUTH**: implement authorization validity, idempotent debits, and retry policy on the server to avoid duplicate or missing debits. * If you have a membership or entitlement system, map subscription states explicitly to internal entitlements instead of equating a single payment result with access. ## FAQ ### Which currencies and payment methods are supported? Major Web3 wallets are supported, or users can authorize USDT/USDC in the Gate App for subscription. If you have enabled Stripe, linked accounts can be used for fiat subscription payments. ### How long is a subscription order valid? There is no single fixed “validity” window. The order ends based on configured termination such as `totalPayCount` or `endTime`. If neither is set, it is usually treated as an ongoing subscription. ### How do I configure a trial period? Set `trialDays` on the subscription plan. No formal debit runs during the trial; after the trial, debits follow product and plan rules. ### How do I configure a first-period discount? When creating product pricing for subscription, set `promoConfigType`: * `FIX_AMOUNT`: set `promoAmount` as the discounted amount for the first period * `RATE`: set `promoRate` as the discount ratio, e.g. `0.1` for a 10% price ### How can a merchant manually end a subscription? Call `POST /open/v1/order/complete` with `operationType=FINISH`. No further debits are executed after completion. ### Who initiates debits in ACCOUNT_AUTH mode? The merchant triggers debits from the backend when needed by calling `POST /open/v1/order/deduct` with amount and currency, then reconcile with notifications and deduction query APIs. ## Order status | Status | Description | | - | - | | `CREATED` | Order created; waiting for user authorization | | `AUTHORIZED` | Authorized; waiting for the first debit or for the merchant to initiate a debit | | `CONFIRMING` | Confirming; awaiting the first subscription confirmation deduction result | | `TRIAL` | In trial; formal debit has not started | | `RUNNING` | Running normally; waiting for the platform or the merchant to initiate the next debit | | `UNPAID` | Current debit failed but close conditions are not met yet | | `COMPLETED` | End condition reached or merchant completed manually | | `CANCELLED` | Cancelled by the merchant | | `CLOSED` | Closed due to an exception, e.g. too many failed debits | | `BLOCKED` | A debit was made but funds are under risk control | ## Related guides * [Payment](/global/essentials/version/100/en/inflow/payment/payment) * [Notification](/global/essentials/version/100/en/common/notification) * [Authentication](/global/essentials/version/100/en/common/authentication) * [Error](/global/essentials/version/100/en/common/error) * [API Reference](/global/api-reference/version/100/en/introduction) # x402 Source: https://docs.gate.com/global/essentials/version/100/en/inflow/payment/x402 GatePay integrates the x402 open payment protocol so clients can complete on-chain payments automatically through standard HTTP flows. ## Overview x402 is an open payment standard built around the HTTP `402 Payment Required` status code. When a client requests a paid resource, the server returns a 402 response with payment requirements. The client signs and completes the on-chain payment automatically, keeping the flow transparent to the end user. ## Why x402? * Native micropayments for usage-based APIs * Programmatic payments without traditional account registration * Low-friction settlement through on-chain signatures * HTTP-native integration that works with standard web services ## Core roles | Role | Description | | - | - | | Client (Buyer) | Client or developer that requests a paid resource and signs the payment | | Server (Seller) | Merchant server that declares payment requirements and serves the resource after validation | | Facilitator | GatePay service that verifies payment payloads and finalizes settlement | ## Merchant integration Merchants can integrate through the SDK and client repositories published under the official Gate GitHub organization, while declaring x402 payment requirements at the route layer. The currently public resources include Go, Java, Python, Node.js / TypeScript, and PHP repositories. Use the organization page as the latest source of truth. > [card] [Gate GitHub Organization](https://github.com/gate) ## Client integration For MCP-compatible clients, install and configure the x402 MCP package with the following command. Follow the MCP configuration format required by your client. ```bash theme={null} npx -y @gatepay/x402-mcp ``` > [card] [Local MCP implementation](https://github.com/gate/gatepay-local-mcp) ## Payment flow 1. The client calls the merchant API. 2. The merchant returns `402 Payment Required` with payment requirements in headers. 3. The client signs a payment payload based on the selected chain and token. 4. The client retries the request with the `PAYMENT-SIGNATURE` header. 5. The merchant sends the payload to the GatePay Facilitator for validation. 6. After validation, the merchant serves the resource and the Facilitator submits settlement on-chain. 7. The merchant returns `200 OK` and a `PAYMENT-RESPONSE` header. ## Minimum integration path If you are integrating x402 for the first time, begin with one protected resource and validate the following path: ```text theme={null} Declare one paid HTTP route -> Return 402 payment requirements -> Let the client sign and retry -> Validate through GatePay -> Return the resource ``` Once the single-route flow is stable, you can expand to multiple resources, tiered pricing, and more advanced AI agent payment scenarios with less coordination overhead. ## GatePay Facilitator GatePay acts as the x402 Facilitator and provides: * Payment verification * On-chain settlement submission and confirmation tracking * Sponsored gas for supported payment flows ## Supported networks and token | Network | Token | | - | - | | Ethereum | USDC | | Base | USDC | | Arbitrum One | USDC | | Polygon | USDC | ## Related guides * [Payment](/global/essentials/version/100/en/inflow/payment/payment) * [Authentication](/global/essentials/version/100/en/common/authentication) * [Notification](/global/essentials/version/100/en/common/notification) * [API Reference](/global/api-reference/version/100/en/introduction) # Institution Source: https://docs.gate.com/global/essentials/version/100/en/internalflow/institution Explains dedicated institution APIs, institution merchant APIs, header rules, and the recommended integration path. ## Overview The institution documentation includes two capability layers: * Dedicated institution APIs: accounts, fee settings, charge, transfer, and the account-creation callback * Institution Merchant APIs: the full merchant API surface exposed under institution-prefixed paths ## Dedicated Institution APIs ### Accounts * `POST /merchant/open/institution/v1/accounts/create` * `POST /merchant/open/institution/v1/accounts/update` * `GET /merchant/open/institution/v1/accounts/query` * `GET /merchant/open/institution/v1/accounts/list` * `POST /cashier/open/v1/certification/url` * `GET /cashier/open/v1/certification/verify/query` ### Fee Settings * `POST /rate/commission_rule` * `POST /rate/commission_rule/upgrade` * `GET /rate/commission_rule` * `POST /rate/commission_rule/list` These APIs let the institution main merchant configure markup rules for sub-accounts. If a sub-account does not have its own markup rule, pricing falls back to the main merchant base-rate rule without adding any sub-account-level markup. ### Transfer and Charge * `POST /transfer/open/institution/v1/pay/transfer` * `GET /transfer/open/institution/v1/pay/transfer/detail` * `POST /transfer/open/institution/v1/pay/charge` * `GET /transfer/open/institution/v1/pay/charges/detail` In the current version, `transfer` and `charge` are **synchronous APIs**: * Each submit request returns the final execution result directly * Merchants do not need to rely on a submit-then-poll pattern to wait for asynchronous completion * The `detail` endpoints are retained for historical lookup, result backfill, and reconciliation checks by `merchantBatchNo` ### Callback * `POST /webhook/institution/v1/accounts/callback` * `POST /webhook/institution/v1/verify/result` ## Institution Merchant APIs The institution merchant API set covers: * Payment * Balance * OTC * Convert * Payout * Gift Card * Subscription Institution-prefixed path convention: ```text theme={null} /v1/pay/checkout/order /payment/open/institution/v1/pay/checkout/order ``` ## Header Rules ### Endpoints that do not use `X-GatePay-On-Behalf-Of` * `POST /merchant/open/institution/v1/accounts/create` * `GET /merchant/open/institution/v1/accounts/query` * `GET /merchant/open/institution/v1/accounts/list` * `GET /rate/commission_rule` * `POST /rate/commission_rule` * `POST /rate/commission_rule/upgrade` * `POST /rate/commission_rule/list` ### Endpoints that require `X-GatePay-On-Behalf-Of` * Charge and transfer APIs * All institution merchant APIs | Header | Required | Description | | - | - | - | | `X-GatePay-Certificate-ClientId` | Yes | Application ClientId | | `X-GatePay-Timestamp` | Yes | UTC millisecond timestamp | | `X-GatePay-Nonce` | Yes | Random string | | `X-GatePay-Signature` | Yes | Request signature | | `X-GatePay-On-Behalf-Of` | Conditional | Required for institution fund-movement APIs and institution merchant APIs. Institution merchant APIs typically use the target sub-account ID; charge and transfer APIs can use the initiating account ID for the current request (either an institution account ID or a sub-account ID). It is not used by the account APIs or the fee-setting APIs. | | `X-GatePay-MerchantId` | Conditional | Required by the fee-setting APIs to identify the current main-merchant context. | ## Recommended Reading Order 1. Start with [Institution Headers](/global/api-reference/version/100/en/common/institutionalCommonHeaders) 2. Validate account creation and query first 3. Validate fee settings in the order of create > update > detail query > list query 4. Validate `transfer` and `charge`, and wealth management if needed 5. Extend to institution merchant APIs ## Related References * [Institution Headers](/global/api-reference/version/100/en/common/institutionalCommonHeaders) * [Create Sub-account](/global/api-reference/version/100/en/endpoint/institutional/create) * [Update Sub-account](/global/api-reference/version/100/en/endpoint/institutional/update) * [Query Sub-account](/global/api-reference/version/100/en/endpoint/institutional/query) * [List Sub-accounts](/global/api-reference/version/100/en/endpoint/institutional/list) * [Get Certification URL](/global/api-reference/version/100/en/endpoint/institutional/getCertificationUrl) * [Query Verification Status](/global/api-reference/version/100/en/endpoint/institutional/queryVerify) * [Get Fee Rule Configuration Detail](/global/api-reference/version/100/en/endpoint/institutional/fee-settings/query) * [Create Fee Rule](/global/api-reference/version/100/en/endpoint/institutional/fee-settings/create) * [Update Fee Rule](/global/api-reference/version/100/en/endpoint/institutional/fee-settings/upgrade) * [List Fee Rules](/global/api-reference/version/100/en/endpoint/institutional/fee-settings/list) * [Wealth Action](/global/api-reference/version/100/en/endpoint/institutional/wealthAction) * [Wealth Query](/global/api-reference/version/100/en/endpoint/institutional/wealthQuery) * [Initiate Transfer](/global/api-reference/version/100/en/endpoint/institutional/transfer) * [Transfer Detail](/global/api-reference/version/100/en/endpoint/institutional/transferDetail) * [Initiate Charge](/global/api-reference/version/100/en/endpoint/institutional/charge) * [Charge Detail](/global/api-reference/version/100/en/endpoint/institutional/chargeDetail) # Convert Source: https://docs.gate.com/global/essentials/version/100/en/internalflow/swap Currency conversion enables merchants to exchange currencies directly using balances in their payment accounts. This capability is essential for multi-currency operations and balance management. ## Overview The convert service supports the following scenarios: * **Post-collection conversion**: Convert received payments to settlement currency * **Unified settlement currency**: Maintain accounts in a single currency * **Balance rebalancing**: Optimize currency distribution across accounts For request headers, signature rules, and callback verification, refer to [Authentication & Security](/global/essentials/version/100/en/common/authentication). ## Integration Flow The standard convert workflow follows these steps: ``` Query tradable scope → Get quote → Create swap order → Query result ``` Each step is described in detail below. ### Step 1: Query Tradable Currency Scope (Optional) **Endpoint:** `GET /v1/pay/convert/currency` Retrieves the list of currencies available for conversion. This step is optional but recommended for user interface initialization and validation. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `side` | string | No | Filter by `buy` or `sell` direction | #### Response Fields The response includes available currencies with precision and amount constraints: * `minBuyAmount`: Minimum buy amount (field precision rules apply) * `maxBuyAmount`: Maximum buy amount (field precision rules apply) * `minSellAmount`: Minimum sell amount (field precision rules apply) * `maxSellAmount`: Maximum sell amount (field precision rules apply) *** ### Step 2: Query Available Currency Pairs (Optional) **Endpoint:** `GET /v1/pay/convert/pair` Retrieves supported trading pairs and exchange rate information. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `currency` | string | No | Filter pairs by base currency | | `side` | string | No | Filter by `buy` or `sell` direction | *** ### Step 3: Get Quote **Endpoint:** `POST /v1/pay/convert/preview` Generates a quote for currency conversion. The quote includes an expiration timestamp; expired quotes cannot be used for order creation. #### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `buyCurrency` | string | Yes | Target currency to buy | | `sellCurrency` | string | Yes | Source currency to sell | | `buyAmount` | string | Conditional | Amount to buy (mutually exclusive with `sellAmount`) | | `sellAmount` | string | Conditional | Amount to sell (mutually exclusive with `buyAmount`) | **Note:** Provide either `buyAmount` or `sellAmount`, but not both. #### Response Fields | Field | Type | Description | | - | - | - | | `quoteId` | string | Unique quote identifier; required for order creation | | `exchangeRate` | string | Current exchange rate | | `buyAmount` | string | Amount in target currency | | `sellAmount` | string | Amount in source currency | | `expirationTime` | timestamp | Quote expiration timestamp | *** ### Step 4: Create Convert Order **Endpoint:** `POST /v1/pay/convert` Creates a currency conversion order using a valid quote. This endpoint is idempotent: submitting the same `clientReqId` multiple times will return the same business result. #### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `quoteId` | string | Yes | Quote ID from Step 3 | | `buyCurrency` | string | Yes | Target currency | | `sellCurrency` | string | Yes | Source currency | | `buyAmount` | string | Yes | Amount to buy | | `sellAmount` | string | Yes | Amount to sell | | `clientReqId` | string | Yes | Merchant-generated unique request ID for idempotency | #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | Platform order number for queries | | `clientReqId` | string | Echoed from request | | `status` | string | Initial order status (typically `processing`) | | `buyAmount` | string | Final buy amount | | `sellAmount` | string | Final sell amount | #### Example Request ```json theme={null} { "quoteId": "QUOTE_abc123", "buyCurrency": "BTC", "sellCurrency": "USDT", "buyAmount": "0.5", "sellAmount": "21500", "clientReqId": "SWAP_20240101_001" } ``` *** ### Step 5: Query Convert Order **Endpoint:** `GET /v1/pay/convert/order` Queries the status and details of a swap order. Supports multiple query keys for flexibility. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `orderId` | string | Conditional | Platform order number | | `clientReqId` | string | Conditional | Merchant-generated request ID | **Note:** Provide either `orderId` or `clientReqId` (not both required, but at least one). #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | Platform order number | | `clientReqId` | string | Merchant request ID | | `status` | string | Order status (see enumeration below) | | `buyCurrency` | string | Target currency | | `sellCurrency` | string | Source currency | | `buyAmount` | string | Final buy amount | | `sellAmount` | string | Final sell amount | | `completionTime` | timestamp | Order completion timestamp | *** ## Convert Order Status Enumeration | Status | Description | | - | - | | `processing` | Order is being processed; check back later | | `success` | Conversion completed successfully; funds are now in the account | | `failure` | Conversion failed; funds returned to original account | ## Retry and Error Handling ### Handling Uncertain Responses If a network timeout or uncertain response occurs: 1. **Query first**: Use `GET /v1/pay/convert/order` with `clientReqId` or `orderId` to determine final status 2. **Only retry if necessary**: Only reuse the same `clientReqId` for order creation if the query result remains uncertain 3. **Preserve idempotency**: Keep `clientReqId` unchanged to ensure the same business result ### Common Failure Scenarios | Failure Reason | Description | Resolution | | - | - | - | | Insufficient balance | Account does not have enough funds in sell currency | Fund the account or reduce sell amount | | Unsupported trading pair | Currency pair is not available | Use a different currency pair | | Expired quote | Quote lifetime has elapsed | Generate a new quote using `POST /v1/pay/convert/preview` | | Invalid quantity precision | Amount does not match currency precision rules | Adjust amount to match precision requirements | | Amount limit exceeded | Amount exceeds currency limits | Review limits via `GET /v1/pay/convert/currency` | ## Callback Behavior The convert capability does not provide asynchronous callbacks. Final order confirmation must be obtained through the query API (`GET /v1/pay/convert/order`). For information on callbacks for other products, see [Notification & Callbacks](/global/essentials/version/100/en/common/notification). ## Error Handling For comprehensive error codes and resolution steps, refer to [Error Codes & Best Practices](/global/essentials/version/100/en/common/error). ## Integration Checklist * [ ] Retrieve available currency pairs from `GET /v1/pay/convert/pair` * [ ] Implement quote retrieval with expiration handling * [ ] Generate unique `clientReqId` for each swap request * [ ] Create swap orders with valid quotes * [ ] Implement query fallback for order confirmation * [ ] Handle all failure scenarios gracefully * [ ] Store order IDs for reconciliation * [ ] Monitor conversion rates and limits ## Related Documentation * [Authentication & Security](/global/essentials/version/100/en/common/authentication) * [Account Queries and Reconciliation](/global/essentials/version/100/en/common/balance) * [Error Codes & Best Practices](/global/essentials/version/100/en/common/error) * [General Overview](/global/essentials/version/100/en/common/overview) # OTC Source: https://docs.gate.com/global/essentials/version/100/en/otc Unified GatePay OTC guide covering both on-ramp and off-ramp flows. ## Overview GatePay OTC provides two closely related settlement flows under one business domain: * **On-ramp**: use fiat to buy crypto and credit assets to the merchant account * **Off-ramp**: sell crypto and settle fiat to an approved bank account Both flows share the same integration model: * signed server-side API calls * quote retrieval before order creation * bank account governance * status tracking through active queries and callback notifications From an integration perspective, OTC is closer to a settlement product than to a retail checkout product. Merchants typically manage order creation, bank account selection, callback consumption, and reconciliation from the server side. As a result, a successful integration depends not only on calling the right API, but also on understanding the business flow around quote timing, remittance, settlement tracking, and callback processing. ## Shared Integration Requirements Before using OTC APIs, make sure that: 1. The merchant account has completed the required KYC or compliance review. 2. API credentials and signing logic are already available in the merchant backend. 3. At least one bank account has been created and approved for OTC settlement. 4. The merchant operates in a supported country or region. See: * [Authentication](/global/essentials/version/100/en/common/authentication) * [Merchant Access](/global/essentials/version/100/en/common/accessguide) In addition to technical readiness, merchants should also prepare their business process before going live: * define how bank account onboarding is managed * define how quote expiry and order retry are handled * define how callback events are persisted and replayed * define how OTC settlements are reconciled ## Shared Quote API OTC on-ramp and off-ramp both depend on quote retrieval. Use the following page to understand quote meaning, validity, and usage: * [OTC Quote](/global/api-reference/version/100/en/endpoint/otc/quote) Use `type` to distinguish the business direction: * `BUY`: OTC on-ramp * `SELL`: OTC off-ramp Operationally, the quote API should be treated as a short-lived pricing input rather than as a persistent contract. The safest pattern is: 1. request a quote immediately before the user or operator is ready to proceed 2. persist the quote token and validity period 3. create the order within the validity window 4. discard and refresh the quote if timing or amount changes ## OTC / On-ramp ### Business Goal OTC on-ramp allows a merchant to remit fiat by bank transfer and receive cryptocurrency in the GatePay merchant account. Typical use cases include treasury top-up, institutional inventory purchase, and merchant-side fiat funding before using assets for further payment or settlement activities. ### Typical Flow > [tab] Regular Merchant > > ```text theme={null} > Get Quote -> Create Deposit Order -> Receive Gate Collection Bank Info -> Complete Offline Remittance -> Confirm Payment -> Track Settlement -> Assets Credited > ``` > [tab] Institutional Sub-account > > ```text theme={null} > Create Institutional Sub-account -> Complete Institutional Sub-account KYB Certification -> Get Quote -> Create Deposit Order -> Receive Gate Collection Bank Info -> Complete Offline Remittance -> Confirm Payment -> Track Settlement -> Assets Credited > ``` ### Core APIs * [OTC Quote](/global/api-reference/version/100/en/endpoint/otc/quote) * [Create Deposit Order](/global/api-reference/version/100/en/endpoint/otc/deposit-create) * [Confirm Deposit Payment](/global/api-reference/version/100/en/endpoint/otc/deposit-confirm) * [Cancel Deposit Order](/global/api-reference/version/100/en/endpoint/otc/deposit-cancel) * [Deposit Detail](/global/api-reference/version/100/en/endpoint/otc/deposit-detail) * [Deposit List](/global/api-reference/version/100/en/endpoint/otc/deposit-list) * [OTC Callback Webhook](/global/api-reference/version/100/en/endpoint/otc/callback) ### Minimum Integration Path For a first OTC on-ramp integration, it is best to validate quote retrieval, order creation, payment confirmation, and settlement tracking through the smallest possible flow: 1. request a `BUY` quote 2. create the on-ramp order 3. complete the offline bank remittance with the returned bank details 4. call the payment-confirmation endpoint after remittance is completed 5. track the final settlement result through callbacks and queries ### Integration Notes * The quote must be used within its validity period. * The deposit order must carry a unique `clientOrderId`. * The merchant must transfer funds according to the returned Gate collection bank information. * The remittance reference must be preserved exactly. * Payment confirmation should be sent only after remittance is actually completed. * For institutional sub-accounts: To implement OTC deposits for institutional sub-accounts, institutional sub-account KYB certification must be completed first. For details, see: [Get Certification URL](/global/api-reference/version/100/en/endpoint/institutional/getCertificationUrl). For on-ramp, merchants should understand "confirm payment" as a confirmation that the real bank remittance has already been made, rather than as a simple front-end acknowledgement action. For on-ramp, the most common issue is usually not the API itself, but a mismatch between the payment instruction and the actual bank remittance. Merchants should therefore preserve returned bank details exactly and keep enough order context for later reconciliation. ### Common Callback States * `RECHARGE_SUCCESS` * `RECHARGE_FAIL` In many integrations, callback events may arrive before all related downstream records are fully updated. It is therefore recommended to separate: * callback ingestion * business status confirmation * accounting or ledger posting ## OTC / Off-ramp ### Business Goal OTC off-ramp allows a merchant to sell crypto and settle fiat to an approved bank account. Typical use cases include treasury withdrawal, merchant-side fiat liquidation, and operational settlement to external banking rails. ### Typical Flow ```text theme={null} Get Quote -> Create Withdrawal Order -> Wait for Processing -> Bank Dispatch -> Track Result -> Final Settlement Confirmation ``` ### Minimum Integration Path For a first OTC off-ramp integration, validate one `SELL` flow from end to end: 1. request a `SELL` quote 2. choose an approved bank account 3. create the off-ramp order 4. process callbacks and query as fallback 5. reconcile the platform result against the bank payout outcome ### Core APIs * [OTC Quote](/global/api-reference/version/100/en/endpoint/otc/quote) * [Create Withdrawal Order](/global/api-reference/version/100/en/endpoint/otc/withdraw-create) * [Withdrawal Detail](/global/api-reference/version/100/en/endpoint/otc/withdraw-detail) * [Withdrawal List](/global/api-reference/version/100/en/endpoint/otc/withdraw-list) * [OTC Callback Webhook](/global/api-reference/version/100/en/endpoint/otc/callback) ### Integration Notes * Use a fresh quote token before creating the withdrawal order. * Keep `clientOrderId` globally unique. * Reconcile against both expected fiat amount and final settled fiat amount when provided. * Use callback plus detail query together as the reliable source of truth. For off-ramp, settlement visibility is especially important because the business event spans both crypto disposal and bank-side payout. Merchants should avoid treating the workflow as complete too early. In most cases, the safest confirmation point is the final successful order state together with the returned payout metadata. ### Common Callback States * `WITHDRAW_DISPATCHED` * `WITHDRAW_SUCCESS` * `WITHDRAW_FAIL` When using `WITHDRAW_DISPATCHED`, it is helpful to treat it as a dispatch milestone rather than as the final settlement result. This makes it easier to distinguish “bank payout initiated” from “business fully completed”. ## Bank Account Management ### Operation flow 1. Submit the bank account holder name, account number, bank name, SWIFT code, and other account details required for registration. 2. Submit supporting documents such as the company operating certificate, shareholder proof, and shareholding structure chart (include whatever materials your onboarding case requires). 3. Allow about **two days** for manual review. During this period, poll the [Bank Account List](/global/api-reference/version/100/en/endpoint/otc/bank-list) API on a schedule; once verification succeeds, the account can be used for settlement. * [Bank Countries](/global/api-reference/version/100/en/endpoint/otc/bank-countries) * [Create Bank Account](/global/api-reference/version/100/en/endpoint/otc/bank-create) * [Submit Bank Account Material Supplement](/global/api-reference/version/100/en/endpoint/otc/bank-material-supplement) * [Bank Account List](/global/api-reference/version/100/en/endpoint/otc/bank-list) * [Delete Bank Account](/global/api-reference/version/100/en/endpoint/otc/bank-delete) Bank account governance should usually follow a stricter process than normal application configuration, because an incorrect bank account can lead to delays, review escalation, or settlement risk. ## Callbacks and Reconciliation OTC integrations should not rely on a single confirmation mechanism. Recommended pattern: 1. Create and persist the quote and order on the backend. 2. Store `clientOrderId`, `orderId`, and settlement metadata. 3. Process callback notifications first. 4. Use detail queries as the fallback source of truth. 5. Reconcile bank settlement records with OTC order results. For larger implementations, it is also useful to maintain separate business checkpoints such as: * quote acquired * order created * callback received * detail verified * finance reconciled This approach makes it easier to understand settlement progress without overloading the API-level order state with additional business meaning. See: * [Notification](/global/essentials/version/100/en/common/notification) * [OTC Callback Webhook](/global/api-reference/version/100/en/endpoint/otc/callback) ## Recommended Reading Order If this is your first OTC integration, the most practical reading order is: 1. Read this OTC guide for the business model. 2. Read [Merchant Access](/global/essentials/version/100/en/common/accessguide) and [Authentication](/global/essentials/version/100/en/common/authentication). 3. Read the shared [OTC Quote](/global/api-reference/version/100/en/endpoint/otc/quote) page. 4. Read the order creation and query pages for the specific flow you are implementing. 5. Finish with callback and reconciliation pages before launch. # Payout Source: https://docs.gate.com/global/essentials/version/100/en/outflow/payout This guide introduces GatePay's payout (withdrawal) capabilities for batch fund distribution, commission payouts, merchant settlements, and other bulk transfer scenarios. ## Overview GatePay payout capabilities enable merchants to distribute funds to multiple recipients in a single batch operation. Common use cases include: * Commission distribution to affiliates or partners * Merchant settlement and revenue sharing * Batch fund transfers to user wallets * Royalty payments * Refunds and chargebacks In this guide, the terms "payout", "withdrawal", and "merchant-side fund transfer" all refer to the same outbound transfer capability. To keep the reading experience consistent, this page uses "payout" as the primary label. *** ## Prerequisites Before integrating payout capabilities, you must complete the following setup steps: 1. **Application Creation**: Create a GatePay application in the merchant dashboard 2. **Retrieve ClientId**: Obtain your `ClientId` for API authentication 3. **Signing Key Configuration**: Configure your signing key for request authentication 4. **Callback URL Configuration**: Set up your callback endpoint for asynchronous notifications For detailed setup instructions, see [Overview](/global/essentials/version/100/en/common/overview) and [Authentication and Security](/global/essentials/version/100/en/common/authentication). *** ## Payout Integration Steps ### Step 1: Query Fees and Limits Before creating any payout batch, query the current fee structure and amount limits. These values may change dynamically and should not be cached. **Request**: ``` POST /v1/pay/withdraw/query ``` This endpoint retrieves: * Current withdrawal fees * Minimum and maximum payout amounts * Per-transaction limits * Daily payout limits Operationally, this step should be treated as more than a fee check. It is also the safest pre-flight validation before order creation, because it confirms the current payout path is available for the intended amount and conditions. ### Step 2: Create a Batch Payout Create a batch containing one or more sub-orders (recipient withdrawal requests). Each batch is identified by a unique `batch_id`. #### Minimum Integration Path Operationally, the minimum payout path is usually: 1. call `POST /v1/pay/withdraw/query` to retrieve current fees and limits 2. call `POST /v1/pay/withdraw` to create the batch 3. process the payout callback notifications 4. use query endpoints as fallback confirmation when needed For first-time merchants, it is best to validate the full lifecycle with a single sub-order before expanding to large batches. ### Step 3: Receive Callbacks and Track Status GatePay sends asynchronous callbacks to your configured callback URL. These callbacks report both batch-level status and individual sub-order status. **Callback Order**: 1. Initial callback when batch is created (`INIT` status) 2. Processing callback when batch enters processing (`PROCESSING` status) 3. Final callback with completion status (`SUCCESS`, `PARTIAL`, or `FAIL`) ### Step 4: Reconciliation and Fallback Queries Use the query API as a fallback mechanism for: * Verifying callback delivery * Reconciling accounts * Investigating failed transactions * Confirming final status If your business has strict confirmation requirements, it is helpful to treat "callback received" and "query confirmed" as two separate checkpoints rather than relying on only one of them. *** ## Callbacks First, Query as Fallback GatePay's payout system prioritizes **asynchronous callbacks** for reliability and performance: | Stage | Primary Method | Fallback | | - | - | - | | **Batch Status** | Receive callbacks to `callbackUrl` | Use `POST /v1/pay/withdraw/query` to query batch status | | **Sub-order Status** | Callbacks include sub-order details | Query individual sub-order details via query API | | **Reconciliation** | Receive detailed callback payloads with all amounts and fees | Query endpoint for audit trails and confirmation | **Best Practice**: Implement callback handling as your primary status update mechanism. Use the query API only for fallback verification or periodic reconciliation. For detailed callback information, signing, and verification procedures, see [Notification](/global/essentials/version/100/en/common/notification). If you want to understand the callback status combinations first, continue with [Notification](/global/essentials/version/100/en/common/notification). *** ## Idempotency and Reconciliation GatePay uses two key identifiers for idempotency and reconciliation: | Field | Scope | Purpose | Usage | | - | - | - | - | | `merchant_withdraw_id` | Per sub-order | Merchant-assigned unique identifier for each withdrawal recipient | Idempotency; prevent duplicate payouts to the same recipient | | `suborder_id` | Per sub-order | GatePay-assigned unique identifier | Platform-side tracking, callbacks, and query operations | **Idempotency Guarantee**: If you resubmit a batch with the same `merchant_withdraw_id` values, GatePay will detect duplicates and prevent double-payments. From the merchant system perspective, `merchant_withdraw_id` is best treated as a business reconciliation key rather than only as a technical idempotency field. That makes support handling, manual investigation, and ledger matching easier later. *** ## Batch and Sub-Order Statuses ### Batch Status Lifecycle A batch progresses through the following states: | Status | Description | | - | - | | `INIT` | Batch created; initial validation in progress | | `PROCESSING` | Batch being processed; funds are being transferred on-chain | | `PARTIAL` | Some sub-orders succeeded; others failed | | `FAIL` | Entire batch failed; no funds were distributed | | `SUCCESS` | Entire batch succeeded; all sub-orders completed | ### Sub-Order Status Each withdrawal within a batch has its own status: | Status | Description | | - | - | | `DONE` | Sub-order completed successfully; funds transferred and confirmed | | `FAIL` | Sub-order failed; funds were not transferred or were reversed | *** ## Callback Payload Structure ### Main Batch Callback Payload When a batch status changes, GatePay sends a callback with the following main-order fields: | Field | Required | Description | | - | - | - | | `batch_id` | Yes | Unique batch identifier assigned by GatePay | | `merchant_id` | Yes | Your merchant ID from GatePay | | `status` | Yes | Current batch status: `INIT`, `PROCESSING`, `PARTIAL`, `FAIL`, or `SUCCESS` | | `client_id` | Yes | The `client_id` used to create this batch | | `pay_back_status` | Yes | Rollback/refund status for the batch | | `channel_id` | Yes | Channel identifier used for this payout batch | ### Sub-Order Array Callback Payload Each callback includes a `suborders` array with detailed information about individual withdrawals: | Field | Required | Description | | - | - | - | | `suborder_id` | Yes | GatePay-assigned sub-order identifier | | `chain` | Yes | Blockchain network (e.g., Ethereum, Polygon) | | `address` | Yes | Recipient wallet address | | `currency` | Yes | Payout currency (e.g., USDT, ETH) | | `amount` | Yes | Requested payout amount in currency units | | `fee` | Yes | Actual fee deducted for this sub-order | | `txHash` | Yes | Blockchain transaction hash (confirms on-chain transfer) | | `status` | Yes | Sub-order status: `DONE` or `FAIL` | | `merchant_withdraw_id` | Yes | Your merchant-assigned identifier for reconciliation | | `fee_type` | Yes | Fee deduction type: `0` (internal) or `1` (external) | | `finish_time` | Yes | Completion timestamp (Unix epoch in seconds) | | `sub_amount` | Yes | Total amount for this sub-order (including fee if applicable) | | `done_amount` | Yes | Amount actually credited to the recipient's address | ### Fee Type Clarification * **Fee Type 0 (Internal Deduction)**: Fee is deducted from the merchant's account; the full `amount` is sent to the recipient. * **Fee Type 1 (External Deduction)**: Fee is deducted from the withdrawal amount; the recipient receives `amount - fee`. *** ## Error Handling ### Common Error Codes When creating or processing payouts, you may encounter the following error codes: | Error Code | Description | Applicable API | Recommended Handling | | - | - | - | - | | `550233` | Insufficient balance in merchant account | Batch payout creation | Check available balance via account balance query; top up account | | `550234` | Memo/description field exceeds maximum length | Batch payout creation | Check memo length limits and truncate if necessary | | `550235` | Amount precision exceeds allowed decimal places | Batch payout creation | Verify amount precision matches currency requirements (e.g., USDT typically allows 6 decimals) | | `550238` | Batch contains too many sub-orders | Batch payout creation | Split into multiple batches with fewer sub-orders | | `550239` | `amount` field is missing or empty | Batch payout creation | Verify `amount` is provided for each sub-order | | `550240` | `currency` field is missing or empty | Batch payout creation | Verify `currency` is provided for each sub-order | | `550241` | `address` field is missing or empty | Batch payout creation | Verify recipient address is provided for each sub-order | | `550242` | `chain` field is missing or empty | Batch payout creation | Verify blockchain network is provided for each sub-order | | `550245` | `batch_id` already exists (duplicate batch) | Batch payout creation | Use a unique `batch_id` or leverage idempotency for retries | | `550249` | Invalid `batch_id` or `merchant_withdraw_id` format | Batch payout creation | Ensure IDs are valid strings without special characters | ### Error Response Handling When an error occurs, GatePay returns an error response with: * **Error Code**: Numeric identifier for the error * **Error Message**: Human-readable description * **Details**: Additional context (if available) Implement retry logic with exponential backoff for transient errors (network issues, timeouts). For permanent errors (insufficient balance, invalid parameters), address the underlying issue before retrying. *** ## Reconciliation and Auditing ### Account Balance Reconciliation Regularly reconcile your GatePay merchant account balance against your internal records: 1. **Query Fees Before Each Payout**: Get current fee rates 2. **Track Batch Status**: Monitor batch and sub-order status via callbacks 3. **Audit Amounts**: Verify `amount`, `fee`, and `done_amount` match your expectations 4. **Reconcile Daily**: Use query APIs to reconcile at end of day For detailed reconciliation procedures, see [Balance](/global/essentials/version/100/en/common/balance). ### Investigating Failed Payouts If a sub-order fails: 1. **Check Sub-Order Status**: Query the batch to get `status` for each sub-order 2. **Review Error Details**: Look for error reason in callback or query response 3. **Verify Recipient Address**: Ensure wallet address is valid for the specified chain 4. **Check Recipient Chain**: Confirm the recipient's wallet supports the specified blockchain 5. **Retry If Transient**: For temporary failures, resubmit with a new `batch_id` and same `merchant_withdraw_id` *** ## Query Payout Results **Request**: ``` POST /v1/pay/withdraw/query ``` Query detailed results for a specific payout batch. This endpoint returns: * Batch status and metadata * Sub-order array with individual results * Fee information * Transaction hashes for on-chain verification Use this endpoint for: * Fallback verification if callbacks are delayed * Periodic reconciliation * Detailed audit trails * Support and investigation *** ## Request Signing and Validation All payout requests must use the standard GatePay signing mechanism. For request signing, signature generation, and callback verification details, see [Authentication and Security](/global/essentials/version/100/en/common/authentication). Key signing requirements: * Compute HMAC-SHA512 with the Payment API Secret using the `timestamp\nnonce\nbody\n` signing string * Include the computed signature in the `X-GatePay-Signature` header * Verify callbacks with the same Payment API Secret and signing rules *** ## Best Practices 1. **Query Fees Dynamically**: Always query current fees before creating a batch; do not cache fee values. 2. **Use Unique Identifiers**: Assign unique `merchant_withdraw_id` and `batch_id` values to prevent duplicates and enable idempotency. 3. **Implement Callback Handling**: Set up robust callback processing for real-time status updates. 4. **Monitor Batch Status**: Track batches through their lifecycle; alert on `PARTIAL` or `FAIL` status. 5. **Verify Transactions On-Chain**: For critical payouts, verify `txHash` on the blockchain explorer. 6. **Reconcile Daily**: Reconcile your internal account balance against GatePay records daily. 7. **Handle Errors Gracefully**: Implement proper error handling with exponential backoff for retries. 8. **Secure Your Signing Key**: Protect your signing key; never expose it in logs or to unauthorized parties. 9. **Validate Recipient Addresses**: Perform basic validation (checksum, format) on recipient addresses before submission. 10. **Plan for Rate Limits**: Be aware of API rate limits; implement request queuing for large batch operations. *** ## Related Documentation * [Overview](/global/essentials/version/100/en/common/overview) * [Authentication and Security](/global/essentials/version/100/en/common/authentication) * [Notification](/global/essentials/version/100/en/common/notification) * [Balance](/global/essentials/version/100/en/common/balance) * [Notification](/global/essentials/version/100/en/common/notification) # Notifications Overview Source: https://docs.gate.com/global/api-reference/version/100/en/common/asyncNotification Explains GatePay asynchronous notifications, including payload structure, status enums, retry rules, and signature verification. ## Reading path We recommend this order when integrating notifications: 1. **This page (overview)** — shared envelope, retries, signature verification, and `bizType` reference 2. **Business notification pages** — field tables and examples (Payment / OTC / Payout / Subscription / Institution groups in this menu) 3. **[Guide: Notification](/global/essentials/version/100/en/common/notification)** — event catalog, terminal-state handling, and product-to-`bizType` mapping 4. **[Best practices](/global/api-reference/version/100/en/common/bestPractices)** — payment query fallback, 10s refund rule, and security guidance ## Overview When order status changes (payment success, timeout, cancellation, closure, exception, and similar events), GatePay sends an asynchronous POST notification to the **callback URL** configured at merchant registration. * **Delivery**: GatePay delivers JSON notifications to your callback URL via POST. * **Retry**: If delivery fails due to network or other issues, GatePay retries after **15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)**. If retries still fail, use the relevant query APIs to obtain the latest status. * **Idempotency**: The same business event may be delivered more than once. Implement idempotent processing using business-unique identifiers such as `bizId` and `merchantTradeNo`. ## Processing requirements 1. **Verify signature**: Validate the signature before processing business logic. Request headers include `X-GatePay-Timestamp`, `X-GatePay-Nonce`, and `X-GatePay-Signature`. See [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). 2. **Parse `data`**: For standard-envelope callbacks, `data` is a **JSON string** — call `JSON.parse` before reading fields. **Exception:** **Payout (`WITHDRAW`)** has no `data` field and uses the dedicated `main_order` + `suborders` shape (see [Payout status notification](/global/api-reference/version/100/en/endpoint/withdraw/callback)). Top-level `client_id` / `clientId` may be absent or mixed; follow the actual callback. 3. **Acknowledge**: Return HTTP 200 with JSON `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. Returning `FAIL` or timing out triggers retries. ## Message structure | Field | Description | | - | - | | bizType | Business type | | bizId | Business ID | | bizStatus | Business status | | client_id / clientId | Application ClientId (field name varies; may be absent) | | data | Business payload as a JSON string; absent for `WITHDRAW` (see each business notification page) | ### Message JSON example ```json theme={null} { "bizType": "PAY", "bizId": "order_123456", "bizStatus": "PAY_SUCCESS", "client_id": "your_client_id", "data": "{...}" } ``` ## bizType | bizType | Description | | - | - | | `PAY` | Gate Pay order status | | `PAY_FIAT` | Fiat payment order status | | `PAY_ADDRESS` | Address payment order status | | `TRANSFER_ADDRESS` | Address payment fund credit | | `CHAIN_ADDRESS` | Address payment on-chain transaction lifecycle | | `PAY_FIXED_ADDRESS` | Static address collection | | `FIXED_ADDRESS_RISK` | Static address risk | | `PAY_REFUND` | Refund status | | `PAY_BATCH` | Batch transfer / reward | | `PAY_GIFT_BATCH` | Gift card batch payment | | `PAY_UNRESOLVED` | Unresolved payment | | `INSTITUTION` | Institution sub-account result | | `OTC` | OTC on-ramp / off-ramp | | `WITHDRAW` | Payout / withdrawal batch | | `SUBSCRIPTION_ORDER_STATUS` | Subscription order status | | `SUBSCRIPTION_PAYMENT` / `ACCOUNT_AUTH_DEDUCTION` | Subscription / authorized deduction | ## Terminal states at a glance See the full [event catalog in the Guide](/global/essentials/version/100/en/common/notification#event-catalog). | bizType | bizStatus (examples) | Terminal | Suggested action | | - | - | - | - | | `PAY` / `PAY_FIAT` | `PAY_SUCCESS` | Yes | Mark paid and fulfill | | `PAY` / `PAY_FIAT` | `PAY_ERROR` / `PAY_CLOSE` | Yes | Mark failed/closed; stop polling | | `PAY_REFUND` | `REFUND_PROCESS` | No | Mark processing; wait or query | | `PAY_REFUND` | `REFUND_SUCCESS` / `REFUND_REJECTED` | Yes | Reconcile / manual review | | `PAY_ADDRESS` | `PAY_EXPIRED_IN_PROCESS` | No | Do not finalize until chain confirms | | `CHAIN_ADDRESS` | `PAY_PASSED` / `PAY_CONFIRMING` / `PAY_DONE` | No | Record the status during on-chain transaction and verification | | `WITHDRAW` | `WITHDRAW_SUCCESS` / `WITHDRAW_PARTIAL` / `WITHDRAW_FAIL` | Yes | Reconcile batch and sub-orders | | `INSTITUTION` | `INSTITUTION_ACCOUNT_FAIL` | Yes | Record failure; manual follow-up | ## bizStatus enum (payment / address) | bizStatus | Description | | - | - | | PAY_SUCCESS | Payment successful | | PAY_ERROR | Payment failed | | PAY_CLOSE | Payment closed | | REFUND_SUCCESS | Refund successful | | REFUND_PROCESS | Refund in process | | REFUND_REJECTED | Refund rejected | | PAY_EXPIRED_IN_PROCESS | Target amount reached during validity but on-chain records still unconfirmed | | TRANSFERRED_ADDRESS_IN_TERM | Address credited within term | | TRANSFERRED_ADDRESS_DELAY | Delayed address credit | | CONVERT_ADDRESS_PAY_DELAY | Convert address payment delayed | | PAY_PASSED | On-chain transaction compliance verification passed (`CHAIN_ADDRESS`) | | PAY_CONFIRMING | On-chain transaction sync started (`CHAIN_ADDRESS`) | | PAY_DONE | On-chain transaction confirmed (`CHAIN_ADDRESS`) | | PAID | Batch order paid | | RISK_ADDRESS | Fixed address risk | Subscription, OTC, institution, and unresolved-payment statuses are documented on their respective pages. # Address Payment Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/addresspayment/callback global/api-reference/version/100/en/openapi/address-payment-callback-openapi.json webhook addressPaymentWebhook In address payment scenarios, GatePay delivers `PAY_ADDRESS` (order status change), `TRANSFER_ADDRESS` (order fund transfer), and `CHAIN_ADDRESS` (on-chain transaction and verification status) notifications to the merchant callback URL. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview. ## Overview This page documents `webhook addressPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the merchant callback URL when address payment order status or fund transfer status changes (`bizType` is `PAY_ADDRESS`, `TRANSFER_ADDRESS`, or `CHAIN_ADDRESS`). ## Notes * Use `merchantTradeNo` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * Order status changes from created to payment completed * Order status changes from created to expired * User pays a sufficient amount within the validity period, but on-chain confirmation is incomplete at expiration, so the order enters `PROCESS` * Before an order finishes (expired or completed), each successful payment credits the merchant balance account; when cumulative payments reach the order amount within the validity period, the order is marked completed * After order completion, new payments to the order address are confirmed and credited to the merchant balance account * After order completion, new payments to a convert payment order address are detected * In dynamic address payment scenarios, on-chain deposit lifecycle events such as transaction sync, compliance verification, and confirmation (`CHAIN_ADDRESS`) ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Notification category; see table below | | `bizId` | string | Order ID | | `bizStatus` | string | Business status; see tables below | | `client_id` | string | Merchant `client_id` that created the order (common in `TRANSFER_ADDRESS` and similar scenarios) | | `data` | string | Business payload as a JSON string; structure varies by `bizType` | ## bizType Enumeration | Value | Description | | - | - | | `PAY_ADDRESS` | Order status change notification | | `TRANSFER_ADDRESS` | Order fund transfer notification | | `CHAIN_ADDRESS` | On-chain transaction and verification status notification (sync, compliance passed, confirmed) | ## bizStatus Values (`bizType=PAY_ADDRESS`) | Value | Description | | - | - | | `PAY_SUCCESS` | Payment succeeded | | `PAY_ERROR` | Payment error | | `PAY_CLOSE` | Order expired and closed | | `PAY_EXPIRED_IN_PROCESS` | User paid ≥ order amount within the validity period, but unconfirmed on-chain payments remain; order enters `PROCESS` | Convert address payment orders may also use statuses such as `PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION` (as returned in the callback). ## bizStatus Values (`bizType=TRANSFER_ADDRESS`) | Value | Description | | - | - | | `TRANSFERRED_ADDRESS_IN_TERM` | Non-convert: successful payment credited to merchant balance account within the validity period | | `TRANSFERRED_ADDRESS_DELAY` | Non-convert: delayed payment credited after the validity period | | `CONVERT_ADDRESS_PAY_DELAY` | Convert: delayed arrival notified but not credited to merchant balance account | ## bizStatus Values (`bizType=CHAIN_ADDRESS`) | Value | Description | | - | - | | `PAY_PASSED` | On-chain transaction compliance verification passed | | `PAY_CONFIRMING` | On-chain transaction sync started | | `PAY_DONE` | On-chain transaction confirmed | > These statuses only record the on-chain transaction and verification process and cannot be treated as order terminal states. ## data Fields (`bizType=PAY_ADDRESS`, non-convert) | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `originalMerchantTradeNo` | string | Associated original merchant order number (populated for supplementary-order, convert, and similar scenarios) | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | string | Order amount | | `underpaidAmount` | string | Remaining unpaid amount after payment completes | | `payerId` | int64 | Payer UID | | `createTime` | int64 | Order creation time (milliseconds) | | `transactionId` | string | Transaction ID | | `waitAmountOnChain` | string | Amount awaiting on-chain confirmation within the validity period | | `doneAmountOnChain` | string | Amount confirmed on-chain within the validity period | | `channelId` | string | Channel identifier | | `chain` | string | Blockchain network | | `address` | string | Collection address | | `fromAddress` | string | Payer address | | `clientId` | string | Merchant `client_id` embedded in `data` (may appear together with top-level `client_id`) | | `originalOrderId` | string | Associated original Gate Pay order number (populated for supplementary-order, convert, and similar scenarios) | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## data Fields (`bizType=PAY_ADDRESS`, convert) In addition to fields above, convert orders may include: | Field | Type | Description | | - | - | - | | `totalFee` | string | Order amount | | `payCurrency` | string | Payment currency | | `payAmount` | string | Required payment amount | | `rate` | string | Exchange rate | | `transferAmount` | string | User's actual payment amount; often empty in status-change notifications | | `overPay` | string | Amount paid above the order requirement; non-zero only on payment success | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## data Fields (`bizType=TRANSFER_ADDRESS`) | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `originalMerchantTradeNo` | string | Associated original merchant order number (populated for supplementary-order, convert, and similar scenarios) | | `originalOrderId` | string | Associated original Gate Pay order number (populated for supplementary-order, convert, and similar scenarios) | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | string | Order amount | | `payerId` | int64 | Payer UID | | `createTime` | int64 | Order creation time (milliseconds) | | `transactionId` | string | Transaction ID | | `transferAmount` | string | User's actual payment amount | | `channelId` | string | Channel identifier | | `chain` | string | Blockchain network | | `address` | string | Collection address | | `txHash` / `tx_hash` | string | On-chain transaction hash (parse compatibly) | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## data Fields (`bizType=CHAIN_ADDRESS`) | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `clientId` | string | Merchant `client_id` | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | number | Order amount | | `payerId` | int64 | Payer UID | | `createTime` | int64 | Order creation time (milliseconds) | | `transferAmount` | number | On-chain received amount | | `txHash` | string | On-chain transaction hash | | `channelId` | string | Channel identifier | | `chain` | string | Blockchain network | | `address` | string | Collection address | | `fromAddress` | string | Payer address | | `passedTime` | int64 | On-chain transaction compliance verification passed time (milliseconds); returned when `bizStatus=PAY_PASSED` | | `confirmingTime` | int64 | On-chain transaction sync start time (milliseconds); returned when `bizStatus=PAY_CONFIRMING` | | `doneTime` | int64 | On-chain transaction confirmed time (milliseconds); returned when `bizStatus=PAY_DONE` | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## Callback Examples ### Order status change (`bizType=PAY_ADDRESS`, payment success) ```json theme={null} { "bizType": "PAY_ADDRESS", "bizId": "79553671353466882", "bizStatus": "PAY_SUCCESS", "client_id": "cuqrgOWUjWusqagz", "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"\",\"waitAmountOnChain\":\"0\"}" } ``` ### Order status change (`bizType=PAY_ADDRESS`, convert) ```json theme={null} { "bizType": "PAY_ADDRESS", "bizId": "46301072319320064", "bizStatus": "PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION", "client_id": "ygMRT5SdrGpiISVV", "data": "{\"accountId\":10002,\"merchantTradeNo\":\"938402023010600017\",\"originalMerchantTradeNo\":\"\",\"productType\":\"\",\"productName\":\"USDT_PAY_WMHH_TEST\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"USDT_PAY_WMHH_TEST\",\"terminalType\":\"MINIAPP\",\"currency\":\"USDT\",\"totalFee\":\"2.1\",\"orderAmount\":\"2.1\",\"payCurrency\":\"WMHH\",\"payAmount\":\"0.2142\",\"rate\":\"0.1\",\"payerId\":10002,\"createTime\":1673000635873,\"transactionId\":\"\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.2142\",\"transferAmount\":\"\",\"overPay\":\"0\"}" } ``` ### Fund transfer (`bizType=TRANSFER_ADDRESS`) ```json theme={null} { "bizType": "TRANSFER_ADDRESS", "bizId": "79553671353466882", "bizStatus": "TRANSFERRED_ADDRESS_IN_TERM", "client_id": "cuqrgOWUjWusqagz", "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"79553755105198106\",\"transferAmount\":\"98.2\",\"tx_hash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\"}" } ``` ### On-chain transaction and verification status (`bizType=CHAIN_ADDRESS`) ```json theme={null} { "bizType": "CHAIN_ADDRESS", "bizId": "79553671353466882", "bizStatus": "PAY_PASSED", "client_id": "cuqrgOWUjWusqagz", "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":98.2,\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transferAmount\":98.2,\"txHash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\",\"passedTime\":1780037570000}" } ``` # Fiat Payment Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/fiatPaymentNotify global/api-reference/version/100/en/openapi/fiat-payment-callback-openapi.json webhook fiatPaymentWebhook When a fiat payment order status changes, GatePay sends a webhook with `bizType` `PAY_FIAT`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview; you may also call the order query API for the latest status. ## Overview This page documents `webhook fiatPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the merchant callback URL when fiat payment order status changes (`bizType` is `PAY_FIAT`). ## Notes * Use `merchantTradeNo` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * When a fiat payment order status changes (payment success, timeout, cancellation, or closure), GatePay sends a notification to the **callback URL** configured at merchant registration * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). **Scope**: Orders placed and paid in fiat currency (`bizType` is `PAY_FIAT`). When fiat is selected at checkout, GatePay converts to crypto at the live rate for collection. ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY_FIAT` | | `bizId` | string | Prepaid order ID | | `bizStatus` | string | Order status; see table below | | `client_id` | string | Merchant `client_id` that created the order (may be omitted in some callbacks; use actual payload) | | `data` | string | Order payload as a JSON string | ### Example Message ```json theme={null} { "bizType": "PAY_FIAT", "bizId": "84818925449510912", "bizStatus": "PAY_SUCCESS", "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"waitAmountOnChain\":\"0\"}" } ``` ## bizStatus Enumeration | Value | Description | | - | - | | `PAY_SUCCESS` | Payment succeeded | | `PAY_ERROR` | Payment error | | `PAY_CLOSE` | Order closed by merchant or timed out | ## data Field Reference | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | string | Order amount | | `fiatCurrency` | string | Fiat currency | | `fiatAmount` | `number` | Fiat amount | | `payerId` | int64 | Payer UID; `0` when paid without a Gate account | | `createTime` | int64 | Order creation time (milliseconds) | | `transactionID` | string | Platform transaction ID (some legacy callbacks may use `transactionId`; parse compatibly) | | `channelId` | string | Customer name / channel identifier | | `doneAmountOnChain` | string | On-chain confirmed amount | | `waitAmountOnChain` | string | On-chain amount awaiting confirmation | | `payAccount` | string | Payment method used for the fiat payment; see enumeration below | ### payAccount Enumeration | Value | Payment Method | | - | - | | `card` | Card | | `google_pay` | Google Pay | | `apple_pay` | Apple Pay | | `link` | Link | | `PIX` | PIX | | `SPEI` | SPEI | | `Bank Transfer` | Bank Transfer | ## Callback Example ### Fiat payment succeeded (`bizStatus=PAY_SUCCESS`) ```json theme={null} { "bizType": "PAY_FIAT", "bizId": "84818925449510912", "bizStatus": "PAY_SUCCESS", "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"waitAmountOnChain\":\"0\"}" } ``` ### Order closed (`bizStatus=PAY_CLOSE`) ```json theme={null} { "bizType": "PAY_FIAT", "bizId": "84818925449510912", "bizStatus": "PAY_CLOSE", "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` ### Payment error (`bizStatus=PAY_ERROR`) ```json theme={null} { "bizType": "PAY_FIAT", "bizId": "84818925449510912", "bizStatus": "PAY_ERROR", "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` # Gate Payment Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/gatePaymentNotify global/api-reference/version/100/en/openapi/gate-payment-callback-openapi.json webhook gatePaymentWebhook Applies to orders placed through hosted checkout, client launch, and similar flows where the user pays with a Gate payment account. `bizType` is always `PAY`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview. You may also call `/v1/pay/order/query` to reconcile order status. ## Overview This page documents `webhook gatePaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the merchant callback URL when Gate payment order status changes (`bizType` is `PAY`). ## Notes * Use `merchantTradeNo` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * When the order status changes (payment success, payment timeout, cancellation, closure, and similar events), GatePay sends a notification to the **callback URL** configured at merchant registration * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). **Scope**: Orders placed through hosted checkout, web or in-app launch, and similar flows where the user pays with a **Gate payment account** (`bizType` is `PAY`). See [Payments](/global/essentials/version/100/en/inflow/payment/payment) for integration guidance. ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY` | | `bizId` | string | Prepaid order ID | | `bizStatus` | string | Order status; see table below | | `client_id` | string | Merchant `client_id` that created the order (may be omitted in some callbacks; use actual payload) | | `data` | string | Order payload as a JSON string | ### Example Message ```json theme={null} { "bizType": "PAY", "bizId": "79553572569350157", "bizStatus": "PAY_SUCCESS", "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` ## bizStatus Enumeration | Value | Description | | - | - | | `PAY_SUCCESS` | Payment succeeded | | `PAY_ERROR` | Payment error | | `PAY_CLOSE` | Order closed by merchant or timed out | ## data Field Reference | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | string | Order amount (payment amount when Gate Pay succeeds) | | `totalFee` | string | Order amount (may appear together with `orderAmount`) | | `expectCurrency` | string | Merchant expected settlement currency | | `actualCurrency` | string | Actual settlement currency | | `actualAmount` | string | Amount in `actualCurrency` | | `payerId` | int64 | Payer UID | | `createTime` | int64 | Order creation time (milliseconds) | | `transactionId` | string | Platform transaction ID (may be omitted in some callbacks) | | `channelId` | string | Customer name / channel identifier | | `doneAmountOnChain` | string | On-chain confirmed amount | | `waitAmountOnChain` | string | On-chain amount awaiting confirmation | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## Callback Example ### Payment success (`bizStatus=PAY_SUCCESS`) ```json theme={null} { "bizType": "PAY", "bizId": "79553572569350157", "bizStatus": "PAY_SUCCESS", "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` ### Order closed (`bizStatus=PAY_CLOSE`) ```json theme={null} { "bizType": "PAY", "bizId": "79553572569350157", "bizStatus": "PAY_CLOSE", "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":0,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` ### Payment error (`bizStatus=PAY_ERROR`) ```json theme={null} { "bizType": "PAY", "bizId": "79553572569350157", "bizStatus": "PAY_ERROR", "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}" } ``` # Gift Card Payment Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/giftCardPaymentNotify global/api-reference/version/100/en/openapi/gift-card-payment-callback-openapi.json webhook giftCardPaymentWebhook When a batch gift-card payment order status changes, GatePay sends a webhook with `bizType` `PAY_GIFT_BATCH`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview. ## Overview This page documents `webhook giftCardPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the merchant callback URL when batch gift-card payment order status changes (`bizType` is `PAY_GIFT_BATCH`). ## Notes * Use `externalId` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * When a batch gift-card payment order status changes, GatePay sends a notification to the **callback URL** configured at merchant registration * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). **Scope**: Batch gift-card payment orders (`bizType` is `PAY_GIFT_BATCH`). For gift-card integration, see [Gift Card](/global/essentials/version/100/en/inflow/payment/giftcard). ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY_GIFT_BATCH` | | `bizId` | string | Batch gift-card order ID (may be an empty string; use actual payload) | | `bizStatus` | string | Batch gift-card order status; see table below | | `client_id` | string | Merchant `client_id` that created the order | | `data` | string | Business payload as a JSON string | ### Example Message ```json theme={null} { "bizType": "PAY_GIFT_BATCH", "bizId": "", "bizStatus": "PAID", "data": "{\"batchItemList\":[],\"externalId\":\"\"}" } ``` ## bizStatus Enumeration | Value | Description | | - | - | | `PAID` | Batch gift-card payment/issuance completed | ## data Field Reference | Field | Type | Description | | - | - | - | | `externalId` | string | Merchant external order ID | | `batchItemList` | array | Batch gift-card line items | ### batchItemList Item Fields | Field | Type | Description | | - | - | - | | `amount` | string | Line item amount | | `channel_id` | string | Customer name / channel identifier | | `create_time` | int64 | Creation time (milliseconds) | | `currency` | string | Currency | | `receiver_id` | int64 | Receiver UID | | `status` | string | Line item status, for example `PAID` | ## Callback Example ### Batch gift-card payment completed (`bizStatus=PAID`) ```json theme={null} { "bizType": "PAY_GIFT_BATCH", "bizId": "", "bizStatus": "PAID", "data": "{\"batchItemList\":[],\"externalId\":\"\"}" } ``` ### Batch gift-card payment completed (with batchItemList) ```json theme={null} { "bizType": "PAY_GIFT_BATCH", "bizId": "79553020665790541", "bizStatus": "PAID", "data": "{\"batchItemList\":[{\"amount\":\"10.00\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"status\":\"PAID\"}],\"externalId\":\"gift-order-20260329\"}" } ``` # Query Payment Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/query global/api-reference/version/100/en/openapi/call-payment-openapi.json POST /v1/pay/order/query In order to synchronize order information with merchants, GatePay provides a query interface enabling the merchants to query prepaid orders and refund orders. ## Overview This page documents the `POST /v1/pay/order/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Order status query interface ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Refund Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/refundNotify global/api-reference/version/100/en/openapi/refund-callback-openapi.json webhook refundWebhook When a refund order status changes, GatePay sends a webhook with `bizType` `PAY_REFUND`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview. ## Overview This page documents `webhook refundWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the merchant callback URL when refund order status changes (`bizType` is `PAY_REFUND`). ## Notes * Use `refundInfo.refundRequestId` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * When a refund order status changes (success, in progress, or rejected), GatePay sends a notification to the **callback URL** configured at merchant registration * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). **Scope**: Refund order status changes (`bizType` is `PAY_REFUND`). For refund reconciliation, prefer the merchant-unique identifier `refundRequestId`. ## Query fallback 1. A successful refund API response only means acceptance, not the final refund outcome. 2. Wait for the `PAY_REFUND` callback first; if no status notification arrives within **10 seconds**, call [Query Refund Details](/global/api-reference/version/100/en/endpoint/checkout/refundDetails) (`GET /v2/pay/refund/details`) using `refundRequestId`. ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY_REFUND` | | `bizId` | string | Refund order ID | | `bizStatus` | string | Refund order status; see table below | | `client_id` / `clientId` | string | Merchant `client_id` (top-level field may be `client_id` or `clientId`) | | `data` | string | Business payload as a JSON string | ### Example Message ```json theme={null} { "bizType": "PAY_REFUND", "bizId": "79553022813274112", "bizStatus": "REFUND_SUCCESS", "clientId": "smsWJbaQektcDhOw", "data": "{\"accountId\":10002,\"merchantTradeNo\":\"native5939082218\",\"productName\":\"goodsName\",\"tradeType\":\"APP\",\"goodsName\":\"goodsName\",\"terminalType\":\"APP\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"createTime\":1780017217454,\"transactionId\":\"79553022813274118\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"},\"channelId\":\"\"}" } ``` ## bizStatus Enumeration | Value | Description | | - | - | | `REFUND_SUCCESS` | Refund succeeded | | `REFUND_PROCESS` | Refund in progress | | `REFUND_REJECTED` | Refund rejected | ## data Field Reference | Field | Type | Description | | - | - | - | | `merchantTradeNo` | string | Merchant trade number | | `productType` | string | `goodsType` at order creation | | `productName` | string | `goodsName` at order creation | | `tradeType` | string | `terminalType` at order creation | | `goodsName` | string | Goods name | | `terminalType` | string | Terminal type | | `currency` | string | Order currency | | `orderAmount` | string | Order amount | | `createTime` | int64 | Order creation time (milliseconds) | | `transactionId` | string | Platform transaction ID | | `channelId` | string | Customer name / channel identifier | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | | `refundInfo` | object | Refund details | ### refundInfo Fields | Field | Type | Description | | - | - | - | | `refundRequestId` | string | Merchant refund ID; merchant-generated and less than 32 bytes | | `prepayId` | string | Original order ID to refund | | `orderAmount` | string | Order amount | | `refundAmount` | string | Refund amount | | `refundPayCurrency` | string | Refund payment currency | | `refundPayAmount` | string | Refund payment amount | ## Callback Example ### Refund succeeded (`bizStatus=REFUND_SUCCESS`) ```json theme={null} { "bizType": "PAY_REFUND", "bizId": "79553022813274112", "bizStatus": "REFUND_SUCCESS", "clientId": "smsWJbaQektcDhOw", "data": "{\"accountId\":10002,\"merchantTradeNo\":\"native5939082218\",\"productName\":\"goodsName\",\"tradeType\":\"APP\",\"goodsName\":\"goodsName\",\"terminalType\":\"APP\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"createTime\":1780017217454,\"transactionId\":\"79553022813274118\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"},\"channelId\":\"\"}" } ``` ### Refund in process (`bizStatus=REFUND_PROCESS`) ```json theme={null} { "bizType": "PAY_REFUND", "bizId": "79553022813274112", "bizStatus": "REFUND_PROCESS", "clientId": "smsWJbaQektcDhOw", "data": "{\"accountId\":10002,\"merchantTradeNo\":\"native5939082218\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"}}" } ``` ### Refund rejected (`bizStatus=REFUND_REJECTED`) ```json theme={null} { "bizType": "PAY_REFUND", "bizId": "79553022813274112", "bizStatus": "REFUND_REJECTED", "clientId": "smsWJbaQektcDhOw", "data": "{\"accountId\":10002,\"merchantTradeNo\":\"native5939082218\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"}}" } ``` # Validate Payment Launch Parameters Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/callpayment/sdk global/api-reference/version/100/en/openapi/call-payment-openapi.json POST /v1/pay/open/sdk Payment Component Validation Interface ## Overview This page documents the `POST /v1/pay/open/sdk` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Payment Component Validation Interface ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Convert Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/convert/convert global/api-reference/version/100/en/openapi/convert-openapi.json POST /v1/pay/convert Initiate convert. ## Overview This page documents the `POST /v1/pay/convert` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Supported Convert Currencies Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/convert/currency global/api-reference/version/100/en/openapi/convert-openapi.json GET /v1/pay/convert/currency Query available convert currencies. ## Overview This page documents the `GET /v1/pay/convert/currency` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Convert Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/convert/order global/api-reference/version/100/en/openapi/convert-openapi.json GET /v1/pay/convert/order Query order. ## Overview This page documents the `GET /v1/pay/convert/order` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Supported Convert Pairs Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/convert/pair global/api-reference/version/100/en/openapi/convert-openapi.json GET /v1/pay/convert/pair Query available currency pairs. ## Overview This page documents the `GET /v1/pay/convert/pair` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Preview Convert Quote Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/convert/preview global/api-reference/version/100/en/openapi/convert-openapi.json POST /v1/pay/convert/preview Preview quote. ## Overview This page documents the `POST /v1/pay/convert/preview` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Supported Chains and Currencies Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/chains global/api-reference/version/100/en/openapi/fixed-address-openapi.json GET /v1/pay/fixedaddress/chains Queries the networks and currencies supported by GatePay for static address collection. ## Overview This page documents the `GET /v1/pay/fixedaddress/chains` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Queries the networks and currencies supported by GatePay for static address collection. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Delete Static Address Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/delete global/api-reference/version/100/en/openapi/fixed-address-openapi.json DELETE /v1/pay/fixedaddress/delete Deletes an already generated and valid static collection address. ## Overview This page documents the `DELETE /v1/pay/fixedaddress/delete` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Deletes an already generated and valid static collection address. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Static Address Detail Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/detail global/api-reference/version/100/en/openapi/fixed-address-openapi.json GET /v1/pay/fixedaddress/detail Views the details of an already generated and valid static collection address. ## Overview This page documents the `GET /v1/pay/fixedaddress/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Views the details of an already generated and valid static collection address. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create EVM Static Address Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/evm-save global/api-reference/version/100/en/openapi/fixed-address-openapi.json POST /merchant/open/v1/pay/fixedaddress/evm/save For the same customer, create a static collection address that can correspond to multiple networks, applicable only to EVM networks. **Note**: Under the same channelId, only one static collection address is allowed per network, and duplicate creation is not permitted. ## Overview This page documents the `POST /merchant/open/v1/pay/fixedaddress/evm/save` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. For the same customer, create a static collection address that can correspond to multiple networks, applicable only to EVM networks. ## Notes * Under the same `channelId`, only one static collection address is allowed per network, and duplicate creation is not permitted. * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Fixed Address Payment Status Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/fixedAddressPaymentNotify global/api-reference/version/100/en/openapi/fixed-address-payment-callback-openapi.json webhook fixedAddressPaymentWebhook When a static collection address receives a qualifying payment, GatePay sends a webhook with `bizType` `PAY_FIXED_ADDRESS`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. For risky address notifications (`FIXED_ADDRESS_RISK`), see the fixed address risk notification documentation. ## Overview This page documents `webhook fixedAddressPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. GatePay sends asynchronous notifications to the address callback URL when funds are credited to a static collection address (`bizType` is `PAY_FIXED_ADDRESS`). ## Notes * Use `transactionId` or `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger Scenarios * When the merchant-bound collection address receives funds, and the collection network and received currency are within the merchant's revenue scope ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Message type; always `PAY_FIXED_ADDRESS` | | `bizId` | string | Order ID | | `bizStatus` | string | Business status; see table below | | `data` | string | Bill details as a JSON string | ### Example Message ```json theme={null} { "bizType": "PAY_FIXED_ADDRESS", "bizId": "79553757252681728", "bizStatus": "PAY_SUCCESS", "data": "{\"accountId\":10002,\"address\":\"THGthEF4kxhk6STPSUsQcYsUk3FiHX6FKR\",\"amount\":\"498.7\",\"chain\":\"TRX\",\"channel_id\":\"1956171254260887553\",\"createTime\":1780037680066,\"currency\":\"USDT\",\"fromAddress\":\"TNXoiAJ3dct8Fjg4M9fkLFh9S2v9TXc32G\",\"orderAmount\":\"498.7\",\"transactionId\":\"79553757252681730\",\"transactionTime\":1780037680066,\"txHash\":\"6711f98a10b9efdcfd35a281fd53554736e100441902ef1d24ee2fb5bb75f15a\"}" } ``` ## bizType Enumeration | Value | Description | | - | - | | `PAY_FIXED_ADDRESS` | Static collection address payment notification | For risky address notifications (`FIXED_ADDRESS_RISK`), see [Fixed Address Risk Notification](/global/api-reference/version/100/en/endpoint/fixedaddress/fixedAddressRiskNotify). ## bizStatus Enumeration | Value | Description | | - | - | | `PAY_SUCCESS` | Payment successful and funds credited | ## data Field Reference Parsed `data` fields: | Field | Type | Description | | - | - | - | | `channel_id` | string | Customer name / channel identifier (snake_case; use actual payload) | | `currency` | string | Bill currency | | `orderAmount` | string | Bill amount | | `createTime` | int64 | Bill creation time (milliseconds) | | `transactionId` | string | Transaction ID | | `transactionTime` | int64 | Bill settlement time (milliseconds) | | `chain` | string | Blockchain network | | `address` | string | Collection address | | `amount` | string | Credited amount | | `fromAddress` | string | Payer address | | `txHash` | string | On-chain transaction hash | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | ## Callback Example ### Payment success (`bizStatus=PAY_SUCCESS`) ```json theme={null} { "bizType": "PAY_FIXED_ADDRESS", "bizId": "79553757252681728", "bizStatus": "PAY_SUCCESS", "data": "{\"accountId\":10002,\"address\":\"THGthEF4kxhk6STPSUsQcYsUk3FiHX6FKR\",\"amount\":\"498.7\",\"chain\":\"TRX\",\"channel_id\":\"1956171254260887553\",\"createTime\":1780037680066,\"currency\":\"USDT\",\"fromAddress\":\"TNXoiAJ3dct8Fjg4M9fkLFh9S2v9TXc32G\",\"orderAmount\":\"498.7\",\"transactionId\":\"79553757252681730\",\"transactionTime\":1780037680066,\"txHash\":\"6711f98a10b9efdcfd35a281fd53554736e100441902ef1d24ee2fb5bb75f15a\"}" } ``` For static collection address APIs, see [static collection address](/global/api-reference/version/100/en/endpoint/fixedaddress/chains). # Fixed Address Risk Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/fixedAddressRiskNotify global/api-reference/version/100/en/openapi/fixedAddressRiskNotify-openapi.json webhook fixedAddressRiskWebhook Sent once when a merchant-bound static collection address is flagged as risky (`is_risk` is `1`). The callback body includes `bizType`, `bizId`, `bizStatus`, and `data`. After receiving the notification, update the local address risk state and avoid continuing to collect funds to that address. ## Overview This page documents `webhook fixedAddressRiskWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. When a merchant-bound static collection address is flagged as risky, GatePay sends an asynchronous notification to the callback URL configured for that address. The payload includes `bizType` (`FIXED_ADDRESS_RISK`), `bizStatus` (`RISK_ADDRESS`), and `data` (JSON string). ## Notes * Use `bizId` or the risk address for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger scenarios * GatePay sends a notification when a merchant-bound static collection address is flagged as risky (`is_risk=1`) * Stop collecting to that address locally after receiving the notification * If delivery fails, GatePay retries according to [Notifications overview](/global/api-reference/version/100/en/common/asyncNotification) ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `FIXED_ADDRESS_RISK` | | `bizId` | string | Business ID | | `bizStatus` | string | Always `RISK_ADDRESS` | | `clientId` | string | Merchant `client_id` | | `data` | string | Risk address details as a JSON string | ### Parsed `data` Fields | Field | Type | Description | | - | - | - | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | | `customer_name` | string | Customer name / channel identifier | | `address` | string | Collection address flagged as risky | ## Callback Example ```json theme={null} { "bizType": "FIXED_ADDRESS_RISK", "bizId": "79547404996050989", "bizStatus": "RISK_ADDRESS", "clientId": "RLSfEKlmvLXYyAVX", "data": "{\"accountId\":10002,\"customer_name\":\"5418020260513\",\"address\":\"TT91qAWcHf2xRcev5U3DiQRQ5v3GKxt89E\"}" } ``` # List Static Addresses Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/list global/api-reference/version/100/en/openapi/fixed-address-openapi.json GET /v1/pay/fixedaddress/list Queries the list of generated and valid static collection addresses. ## Overview This page documents the `GET /v1/pay/fixedaddress/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Queries the list of generated and valid static collection addresses. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Static Address Order List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/order-query global/api-reference/version/100/en/openapi/fixed-address-openapi.json GET /v1/pay/fixedaddress/order/query Queries the static collection order list. ## Overview This page documents the `GET /v1/pay/fixedaddress/order/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Queries the static collection order list. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Static Address Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fixedaddress/save global/api-reference/version/100/en/openapi/fixed-address-openapi.json POST /v1/pay/fixedaddress/save Generates a static collection address based on the specified currency and network. **Note**: If a static collection address already exists for `channelId` + `chain`, the `currencies` and `callbackUrl` in the request will update the existing bound information. ## Overview This page documents the `POST /v1/pay/fixedaddress/save` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. Generates a static collection address based on the specified currency and network. ## Notes * If a static collection address already exists for `channelId` + `chain`, the `currencies` and `callbackUrl` in the request update the existing bound information. * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Unresolved Payment Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/fundrecords/unresolvedPayNotify global/api-reference/version/100/en/openapi/unresolvedPayNotify-openapi.json webhook unresolvedPayWebhook Sent once per unresolved payment event to the merchant. The callback body includes `bizType`, `bizId`, `bizStatus`, and `data`. ## Overview This page documents `webhook unresolvedPayWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. ## Notes * This page describes a callback payload sent by GatePay, not a merchant-initiated request. * Verify the signature first, then apply idempotent processing before updating business state. * For callback guidance organized by business flow, read this page together with the Notification guide. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY_UNRESOLVED` | | `bizId` | string | Business ID | | `bizStatus` | string | Business status, e.g. `UNRESOLVED_PENDING` | | `data` | string | JSON string containing unresolved payment details; parsed fields are listed below | ## data Field Reference | Field | Type | Description | | - | - | - | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | | `exceptionId` | string | Unresolved payment ID | | `orderType` | string | Order type: `acquiring_type` (acquiring); `payee_type` (payee QR code) | | `errorType` | string | Error reason code | | `originalOrderId` | string | Original Gate Pay order ID (empty for payee QR scenarios) | | `originalMerchantTradeNo` | string | Associated original merchant order number (empty for payee QR scenarios) | | `expectedAmount` | string | Expected order amount (empty for payee QR scenarios) | | `expectedChainCurrency` | array | Expected chain and currencies | | `actualAmount` | string | Actual order amount | | `actualCurrency` | string | Actual order currency | | `actualChain` | string | Actual blockchain network | | `customerName` | string | Customer name (empty for acquiring scenarios) | | `toAddress` | string | Recipient address | | `fromAddress` | string | Sender address | | `hash` | string | Transaction hash | | `updateTime` | int64 | Event timestamp in milliseconds | ## Callback Example ```json theme={null} { "bizType": "PAY_UNRESOLVED", "bizId": "100916", "bizStatus": "UNRESOLVED_PENDING", "data": "{\"accountId\":10002,\"exceptionId\":\"100916\",\"orderType\":\"payee_type\",\"errorType\":\"fix_error_currency\",\"originalOrderId\":\"\",\"originalMerchantTradeNo\":\"\",\"expectedAmount\":\"\",\"expectedChainCurrency\":[{\"chain\":\"MATIC\",\"currencies\":[\"USDT\"]}],\"actualAmount\":\"0.12\",\"actualCurrency\":\"USDC\",\"actualChain\":\"ARBEVM\",\"customerName\":\"channelId2293698068\",\"toAddress\":\"0x49D24D32b9ed2fc9e7AEd8a08976615988db4f6A\",\"fromAddress\":\"0x144Ff55c1a8C80C893b6272a87C228fc601E4de4\",\"hash\":\"0x76a445961ae0e6fea1197a73b59494ec4939f178639ae0683f6949a57f47fbc0\",\"updateTime\":1780036391365}" } ``` # Query Available Currency Balance Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/gift/balance global/api-reference/version/100/en/openapi/gift-card-openapi.json GET /v1/pay/balance Query the balance of all available currencies under the current merchant account. ## Overview This page documents the `GET /v1/pay/balance` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Batch Query Gift Cards Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/gift/batchQuery global/api-reference/version/100/en/openapi/gift-card-openapi.json POST /v1/pay/gift/batch/query Returns a paginated list of gift cards created by the current merchant, filtered by batch ID or creation time range. When both filters are provided, the API returns their intersection. ## Overview This page documents the `POST /v1/pay/gift/batch/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * Filter by batch ID, creation time range, or both. When both are provided, both filters apply. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Gift Card Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/gift/create global/api-reference/version/100/en/openapi/gift-card-openapi.json POST /v1/pay/gift/create Create a new gift card with specified title, template, currency and amount. ## Overview This page documents the `POST /v1/pay/gift/create` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Gift Card Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/gift/query global/api-reference/version/100/en/openapi/gift-card-openapi.json POST /v1/pay/gift/query Query gift card details by card number or redemption code. When both parameters are provided, key takes priority. ## Overview This page documents the `POST /v1/pay/gift/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Gift Card Template List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/gift/tempList global/api-reference/version/100/en/openapi/gift-card-openapi.json GET /v1/pay/gift/temp/list Get the list of available gift card cover templates. ## Overview This page documents the `GET /v1/pay/gift/temp/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Sub-account Creation Result Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/institutional/callbackNotification global/api-reference/version/100/en/openapi/institutional-openapi.json webhook institutionAccountWebhook When sub-account creation succeeds or fails, GatePay sends an asynchronous POST notification to the callback URL configured by the merchant. The callback payload includes `bizType`, `bizId`, `bizStatus`, `clientId`, and `data`, where `data` is a JSON string of the sub-account creation result object. The merchant must accept and parse the notification at that URL and return HTTP 200 to acknowledge receipt. ## Overview This page documents `webhook institutionAccountWebhook`. Parameters, response schema, and examples are rendered from the linked OpenAPI definition above. When sub-account creation succeeds or fails, GatePay sends a POST request to the callback URL configured by the merchant. The merchant should receive and parse the notification at that URL and return HTTP 200 to acknowledge receipt. ## Notes * Use `bizId` or `data.request_id` for idempotency after parsing `data`. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger scenarios * When sub-account creation completes (success or failure), GatePay sends a notification to your **callback URL** * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification) ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Notification type; INSTITUTION = sub-account creation | | `bizId` | string | Creation request ID | | `bizStatus` | string | Business status: INSTITUTION_ACCOUNT_SUCCESS = created, INSTITUTION_ACCOUNT_FAIL = creation failed | | `client_id` | string | Merchant client_id that created the sub-account | | `data` | string | Message content, JSON string; parsed structure is described in the table below | ## Parsed `data` Content | Field | Type | Description | | - | - | - | | `request_id` | string | Creation request ID | | `account_id` | string | Sub-account ID | | `customer_id` | string | Customer ID on the platform side | | `display_name` | string | Display name | | `status` | string | Account status: ACTIVE = created, FAIL = creation failed | | `created` | int64 | Creation time (milliseconds) | ## Callback examples **Full payload sent by GatePay:** ```json theme={null} { "bizType": "INSTITUTION", "bizId": "2060249001916727296", "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS", "clientId": "caoLHPyfvjtnJPJe", "data": "{\"request_id\":\"2060249001916727296\",\"account_id\":\"53695180\",\"customer_id\":\"2060249001845424128\",\"display_name\":\"ABC\",\"status\":\"ACTIVE\",\"created\":1780036614339}" } ``` **Parsed content of data:** ```json theme={null} { "request_id": "2060249001916727296", "account_id": "53695180", "customer_id": "2060249001845424128", "display_name": "ABC", "status": "ACTIVE", "created": 1780036614339 } ``` ### Sub-account creation failed ```json theme={null} { "bizType": "INSTITUTION", "bizId": "2060249001916727297", "bizStatus": "INSTITUTION_ACCOUNT_FAIL", "clientId": "caoLHPyfvjtnJPJe", "data": "{\"request_id\":\"2060249001916727297\",\"account_id\":\"\",\"customer_id\":\"2060249001845424128\",\"display_name\":\"ABC\",\"status\":\"FAIL\",\"created\":1780036614339}" } ``` # Sub-account Verification Result Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/institutional/verifyResultNotification global/api-reference/version/100/en/openapi/institutional-openapi.json webhook institutionVerifyResultWebhook When sub-account KYB verification completes (passed or rejected), GatePay sends an asynchronous POST notification to the callback URL configured by the merchant. The callback payload includes `bizType`, `bizId`, `bizStatus`, `clientId`, and `data`, where `data` is a JSON string of the verification result object. The merchant must accept and parse the notification at that URL and return HTTP 200 to acknowledge receipt. ## Overview This page documents `webhook institutionVerifyResultWebhook`. Parameters, response schema, and examples are rendered from the linked OpenAPI definition above. When sub-account KYB verification completes (passed or rejected), GatePay sends a POST request to the callback URL configured by the merchant. The merchant should receive and parse the notification at that URL and return HTTP 200 to acknowledge receipt. ## Notes * Use `bizId` for idempotency. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger scenarios * Triggered when KYB verification completes after a sub-account submits verification and the status becomes passed or rejected * GatePay sends the notification to the merchant's configured **callback URL** * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification) ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Notification type; INSTITUTION = institution notification | | `bizId` | string | Notification business ID | | `bizStatus` | string | Business status: PASSED = verification passed, FAILED = verification rejected | | `clientId` | string | Institution merchant client_id | | `data` | string | Message content as a JSON string | ## Parsed `data` Content | Field | Type | Description | | - | - | - | | `subAccountId` | string | Sub-account ID | | `authStatus` | string | Verification result: PASSED = passed, FAILED = rejected | | `accountType` | string | Verification type; always `KYB` | | `auditTime` | int64 | Audit completion time (milliseconds) | | `rejectReason` | string | Rejection reason; empty when passed | ## Callback examples **Verification passed:** ```json theme={null} { "bizType": "INSTITUTION", "bizId": "2060249001916727298", "bizStatus": "PASSED", "clientId": "caoLHPyfvjtnJPJe", "data": "{\"subAccountId\":\"53695180\",\"authStatus\":\"PASSED\",\"accountType\":\"KYB\",\"auditTime\":1780036714339,\"rejectReason\":null}" } ``` **Parsed content of `data`:** ```json theme={null} { "subAccountId": "53695180", "authStatus": "PASSED", "accountType": "KYB", "auditTime": 1780036714339, "rejectReason": null } ``` ### Verification rejected ```json theme={null} { "bizType": "INSTITUTION", "bizId": "2060249001916727299", "bizStatus": "FAILED", "clientId": "caoLHPyfvjtnJPJe", "data": "{\"subAccountId\":\"53695180\",\"authStatus\":\"FAILED\",\"accountType\":\"KYB\",\"auditTime\":1780036714339,\"rejectReason\":\"ID photo is unclear\"}" } ``` # Bank Countries Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/bank-countries global/api-reference/version/100/en/openapi/otc-fiat-openapi.json GET /withdraw/open/otc/api/bank/country/list Query available countries for bank account registration. ## Overview This page documents the `GET /withdraw/open/otc/api/bank/country/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Bank Account Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/bank-create global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/bank/create Create a linked bank account for OTC settlement. ## Overview This page documents the `POST /withdraw/open/otc/api/bank/create` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). ## Supplemental Field Notes ### Request Format * Content-Type: `multipart/form-data` * Use this endpoint to add a bank account before OTC fiat withdrawal. A bank statement file must be uploaded together with the bank account details. ### `file` Upload Requirements * Type: `file` * Required: Yes * Description: The file must not exceed 4 MB and only `jpg`, `jpeg`, and `png` formats are accepted. Upload a bank statement issued within the last 3 months. The bank account name must exactly match the verified identity name. If there is any difference due to language or similar reasons, also provide supporting documents such as a bank certification letter, passport, or an official name-change receipt. # Delete Bank Account Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/bank-delete global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/bank/delete Delete a linked bank account. ## Overview This page documents the `POST /withdraw/open/otc/api/bank/delete` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Bank Account List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/bank-list global/api-reference/version/100/en/openapi/otc-fiat-openapi.json GET /withdraw/open/otc/api/bank/list List linked bank accounts. ## Overview This page documents the `GET /withdraw/open/otc/api/bank/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Submit Bank Account Material Supplement Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/bank-material-supplement global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/bank/material/supplement Submit additional KYC or compliance documents for an existing linked OTC bank account when GatePay requests a material supplement (for example after add-bank review or when the account is pending additional proof). ## Overview This page documents the `POST /withdraw/open/otc/api/bank/material/supplement` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant OTC endpoint. * Use this API to submit additional verification or compliance files for an existing bank account when the platform requests a material supplement. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). * **Limits:** At most **5** files per non-empty list; each file must be non-empty and **4 MB or smaller**; allowed filename extensions: `jpg`, `jpeg`, `png`, `pdf`. # OTC Order Status Update Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/callback global/api-reference/version/100/en/openapi/otc-fiat-openapi.json webhook otcCallbackWebhook OTC order result callback sent to the merchant callback URL for both on-ramp and off-ramp flows. ## Overview This page documents `webhook otcCallbackWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. Use this webhook to receive OTC on-ramp and off-ramp order status change notifications. ## Notes * Use `bizId` or `clientOrderId` for idempotency. * For OTC callbacks, `data` is a **JSON string** — call `JSON.parse` before reading fields. See below for the parsed structure. * Signature verification, retries, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## Trigger scenarios * GatePay sends notifications when OTC on-ramp or off-ramp order status changes * If delivery fails, GatePay retries according to the schedule in [Notifications overview](/global/api-reference/version/100/en/common/asyncNotification) ## Message Structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `OTC` | | `bizId` | string | OTC order ID | | `bizStatus` | string | OTC callback business status: `RECHARGE_SUCCESS` on-ramp succeeded, `RECHARGE_FAIL` on-ramp failed, `WITHDRAW_DISPATCHED` off-ramp payout dispatched, `WITHDRAW_SUCCESS` off-ramp succeeded, `WITHDRAW_FAIL` off-ramp failed, `WITHDRAW_REFUND` off-ramp refunded after successful payout | | `clientId` | string | Merchant client ID | | `data` | string | Order details as a JSON string; on-ramp (`type`=`BUY`) and off-ramp (`type`=`SELL`) differ after parsing — see Option below or field tables | ### On-ramp data fields (`type`=`BUY`, `bizStatus` is `RECHARGE_*`) | Field | Type | Description | | - | - | - | | `type` | string | Always `BUY` | | `orderId` | string | Platform order ID | | `clientOrderId` | string | Merchant-side order ID | | `fiatCurrency` | string | Fiat currency | | `fiatAmount` | string | Fiat amount | | `cryptoCurrency` | string | Cryptocurrency | | `cryptoAmount` | string | Cryptocurrency amount | | `fiatRate` | string | Exchange rate | | `updateTime` | string | Update time (millisecond timestamp string) | | `errMsg` | string | Error message | | `promoCode` | string | Promo code | | `transferRemark` | string | Transfer remark | | `paymentReceiptFileUrl` | string | Payment receipt download URL | | `tradeFee` | string | Total amount of all fee items. | | `feeCurrency` | string | Currency in which each fee item is denominated. | | `feeDetail` | array | Fee breakdown; see `feeDetail[]` below | ### Off-ramp data fields (`type`=`SELL`, `bizStatus` is `WITHDRAW_*`) | Field | Type | Description | | - | - | - | | `type` | string | Always `SELL` | | `orderId` | string | Platform order ID | | `clientOrderId` | string | Merchant-side order ID | | `fiatCurrency` | string | Fiat currency | | `fiatAmount` | string | Fiat amount | | `cryptoCurrency` | string | Cryptocurrency | | `cryptoAmount` | string | Cryptocurrency amount | | `fiatRate` | string | Exchange rate | | `updateTime` | string | Update time (millisecond timestamp string) | | `finalFiatAmount` | string | Final fiat amount | | `bankSlipInfo` | string | Bank receipt / slip URL | | `errMsg` | string | Error message | | `promoCode` | string | Promo code | | `refundAmount` | string | Refunded cryptocurrency amount | | `tradeFee` | string | Total amount of all fee items. | | `feeCurrency` | string | Currency in which each fee item is denominated. | | `feeDetail` | array | Fee breakdown; see `feeDetail[]` below | ### feeDetail\[] fields | Field | Type | Description | | - | - | - | | `feeType` | string | Fee type: `BANK` fee charged by the bank channel, `GATE_PAY` Gate Pay service fee amount, `SUBSIDY` promotional amount deducted from charged fees | | `amount` | string | Amount for this fee item. | ## Callback examples ### On-ramp success (`bizStatus=RECHARGE_SUCCESS`) ```json theme={null} { "bizType": "OTC", "bizId": "79550727153516601", "bizStatus": "RECHARGE_SUCCESS", "clientId": "UGxnuTtJHDuXPjYm", "data": "{\"type\":\"BUY\",\"errMsg\":\"\",\"orderId\":\"79550727153516601\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"10000\",\"updateTime\":\"1779958032486\",\"cryptoAmount\":\"10000\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146201\",\"cryptoCurrency\":\"USDT\",\"transferRemark\":\"\",\"paymentReceiptFileUrl\":\"\",\"tradeFee\":\"100\",\"feeCurrency\":\"USD\",\"feeDetail\":[{\"feeType\":\"BANK\",\"amount\":\"30\"},{\"feeType\":\"GATE_PAY\",\"amount\":\"80\"},{\"feeType\":\"SUBSIDY\",\"amount\":\"10\"}]}" } ``` ### Off-ramp dispatched (`bizStatus=WITHDRAW_DISPATCHED`) ```json theme={null} { "bizType": "OTC", "bizId": "79550727153516602", "bizStatus": "WITHDRAW_DISPATCHED", "clientId": "UGxnuTtJHDuXPjYm", "data": "{\"type\":\"SELL\",\"errMsg\":\"\",\"orderId\":\"79550727153516602\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"124710\",\"updateTime\":\"1779958032486\",\"bankSlipInfo\":\"https://gateio-payments.s3.ap-northeast-1.amazonaws.com/otc_trade_file/otc-trade-record-file43255011-d96f549e1869e47908db891fb512c308.pdf\",\"cryptoAmount\":\"124710\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146200\",\"cryptoCurrency\":\"USDT\",\"finalFiatAmount\":\"124710\",\"tradeFee\":\"10.88\",\"feeCurrency\":\"USDT\",\"feeDetail\":[{\"feeType\":\"BANK\",\"amount\":\"2.00\"},{\"feeType\":\"GATE_PAY\",\"amount\":\"10.00\"},{\"feeType\":\"SUBSIDY\",\"amount\":\"1.12\"}]}" } ``` # Cancel Deposit Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/deposit-cancel global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /payment/open/otc/api/recharge/cancel Cancel an OTC recharge order before payment is confirmed. ## Overview This page documents the `POST /payment/open/otc/api/recharge/cancel` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Confirm Deposit Payment Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/deposit-confirm global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /payment/open/otc/api/recharge/confirm Notify the system that the merchant has completed the offline fiat transfer. This endpoint uses multipart/form-data. When generating the signature, use the plain text string “timestamp\nnonce\n\n”, and do not append the multipart request body. ## Overview This page documents the `POST /payment/open/otc/api/recharge/confirm` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Deposit Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/deposit-create global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /payment/open/otc/api/recharge Create an OTC fiat recharge order. ## Overview This page documents the `POST /payment/open/otc/api/recharge` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). ## Usage Guidance * Call this endpoint only after a valid OTC quote has been obtained. * Persist `orderId` for later reconciliation. * The returned bank information should be treated as settlement instructions and stored together with the order snapshot. * Do not treat order creation itself as payment completion. The actual fiat remittance and confirmation step still need to happen. * **Institutional Sub-accounts**: To implement OTC deposits for institutional sub-accounts, institutional sub-account KYB certification must be completed first. For details, see: [Get Certification URL](/global/api-reference/version/100/en/endpoint/institutional/getCertificationUrl). # Deposit Detail Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/deposit-detail global/api-reference/version/100/en/openapi/otc-fiat-openapi.json GET /payment/open/otc/api/recharge/detail Query detail for a fiat recharge order. ## Overview This page documents the `GET /payment/open/otc/api/recharge/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Deposit List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/deposit-list global/api-reference/version/100/en/openapi/otc-fiat-openapi.json GET /payment/open/otc/api/recharge/list List OTC recharge orders. `startTime` and `endTime` are required. ## Overview This page documents the `GET /payment/open/otc/api/recharge/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # OTC Quote Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/quote global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/v1/quote Get a fiat-to-crypto quote for the OTC off-ramp flow. ## Overview This page documents the shared OTC quote API used by both on-ramp and off-ramp flows. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * Use `type=BUY` for on-ramp and `type=SELL` for off-ramp. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Withdrawal Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/withdraw-create global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/order/create Create an OTC withdrawal order after obtaining a quote. ## Overview This page documents the `POST /withdraw/open/otc/api/order/create` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). ## Usage Guidance * Create the order with a fresh quote token. * Make sure the bank account used in the request is already approved and available for settlement. * Store the expected fiat amount, fee fields (`tradeFee` / `feeCurrency` / `feeDetail`), and final settlement information for reconciliation. * Use callback plus detail query rather than relying on creation response alone. # Withdrawal Detail Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/withdraw-detail global/api-reference/version/100/en/openapi/otc-fiat-openapi.json GET /withdraw/open/otc/api/order/detail Query the detail of an OTC withdrawal order. ## Overview This page documents the `GET /withdraw/open/otc/api/order/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Withdrawal List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/otc/withdraw-list global/api-reference/version/100/en/openapi/otc-fiat-openapi.json POST /withdraw/open/otc/api/order/list Query OTC withdrawal orders in batch. ## Overview This page documents the `POST /withdraw/open/otc/api/order/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create QR Payment Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/qrpay/native global/api-reference/version/100/en/openapi/qrpay-openapi.json POST /v1/pay/transactions/native Create a QR payment order and return the prepay ID, QR content, and redirect URL. ## Overview This page documents the `POST /v1/pay/transactions/native` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * `qrContent` returns the content URL used to generate the QR code image, not a pre-rendered QR image itself. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Exchange Rate Query Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/rateexchange/query global/api-reference/version/100/en/openapi/rate-exchange-openapi.json POST /v1/pay/currency/exchange/rate/query This API provides real-time exchange rates between fiat currencies and cryptocurrencies. It supports multiple trading pairs and is available exclusively to Gate Pay merchants. ## Overview This page documents the `POST /v1/pay/currency/exchange/rate/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Payment Order List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/reconciliation/payOrderList global/api-reference/version/100/en/openapi/reconciliation-openapi.json GET /payment/open/v1/pay/order/list Query payment (collection) orders by time range with pagination. Supports filtering by order type, status, payment method, and other criteria. ## Overview This page documents the **Query Payment Order List** endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * Commonly used for end-of-day reconciliation and reporting sync. Pair with payment callbacks; list queries serve as a fallback data source. * For signing rules, see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). For integration steps, see [Reconciliation](/global/essentials/version/100/en/common/reconciliation). # Query Payout Order List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/reconciliation/withdrawSuborderQuery global/api-reference/version/100/en/openapi/reconciliation-openapi.json GET /withdraw/open/v1/withdraw/suborder/query Query payout (withdrawal) sub-orders by time range with pagination. Supports filtering by batch ID, status, audit status, and other criteria. ## Overview This page documents the **Query Payout Sub-order List** endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * Commonly used for reconciliation fallback and audit tracing. Pair with payout callbacks; list queries complement callback delivery. * For signing rules, see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). For integration steps, see [Reconciliation](/global/essentials/version/100/en/common/reconciliation). # Query Deduction Order Details Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/deductionOrderDetail global/api-reference/version/100/en/openapi/subscription/deductionOrderDetail-openapi.json GET /pay-subscription/open/v1/deduction/order/detail Query deduction order details ## Overview This page documents the `GET /pay-subscription/open/v1/deduction/order/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Subscription Deduction List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/deductionOrderList global/api-reference/version/100/en/openapi/subscription/deductionOrderList-openapi.json GET /pay-subscription/open/v1/deduction/order/list Query deduction order list ## Overview This page documents the `GET /pay-subscription/open/v1/deduction/order/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Subscription Order Status Transition Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderComplete global/api-reference/version/100/en/openapi/subscription/orderComplete-openapi.json POST /pay-subscription/open/v1/order/complete Subscription order status transition ## Overview This page documents the `POST /pay-subscription/open/v1/order/complete` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Subscription Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderCreate global/api-reference/version/100/en/openapi/subscription/orderCreate-openapi.json POST /pay-subscription/open/v1/order/create Create subscription order ## Overview This page documents the `POST /pay-subscription/open/v1/order/create` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Initiate Subscription Deduction Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderDeduct global/api-reference/version/100/en/openapi/subscription/orderDeduct-openapi.json POST /pay-subscription/open/v1/order/deduct Merchant-initiated deduction against a subscription order. Provide either `subscriptionOrderNo` or `merchantSubscriptionOrderNo`. `merchantDeductNo` must be unique per merchant for idempotency. ## Overview This page documents the `POST /pay-subscription/open/v1/order/deduct` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Subscription Order Details Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderDetail global/api-reference/version/100/en/openapi/subscription/orderDetail-openapi.json GET /pay-subscription/open/v1/order/detail Query subscription order details ## Overview This page documents the `GET /pay-subscription/open/v1/order/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Subscription Order List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderList global/api-reference/version/100/en/openapi/subscription/orderList-openapi.json GET /pay-subscription/open/v1/order/list Query subscription order list ## Overview This page documents the `GET /pay-subscription/open/v1/order/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Subscription Order Status Update Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/orderNotify global/api-reference/version/100/en/openapi/subscription/orderNotify-openapi.json webhook subscriptionOrderWebhook ## Overview This page documents `webhook subscriptionOrderWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. When a subscription order status changes, GatePay sends an asynchronous notification to the merchant-configured callback URL (`bizType` is `SUBSCRIPTION_ORDER_STATUS`). ## Notes * Use `bizId` or `data.subscriptionOrderNo` for idempotency after parsing `data`. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## When notifications are sent * GatePay sends a notification to the merchant **callback URL** when the subscription order status changes (authorized, running, cancelled, closed, etc.) * Top-level `bizStatus` matches `orderStatus` inside parsed `data` * No notification is sent when `bizStatus=CREATED` * If delivery fails, GatePay retries after **15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)**; you can also call [Subscription order detail](/global/api-reference/version/100/en/endpoint/subscription/orderDetail) to fetch the latest state ## Message structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `SUBSCRIPTION_ORDER_STATUS` | | `bizId` | string | Subscription order number (usually matches `data.subscriptionOrderNo`) | | `bizStatus` | string | Subscription order status; see table below | | `data` | string | Subscription order details as a JSON string | ### Structure example ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "CANCELLED", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` ## bizStatus / orderStatus values | Value | Description | | - | - | | `AUTHORIZED` | Authorized | | `CONFIRMING` | Confirming | | `TRIAL` | In trial | | `RUNNING` | Running | | `UNPAID` | Unpaid | | `COMPLETED` | Completed | | `CANCELLED` | Cancelled | | `CLOSED` | Closed | | `BLOCKED` | Blocked | ## data fields After parsing the `data` JSON string, common fields include: | Field | Type | Description | | - | - | - | | `subscriptionOrderNo` | string | Subscription order number | | `merchantSubscriptionOrderNo` | string | Merchant subscription order number | | `planNo` | string | Platform subscription plan number | | `planName` | string | Subscription plan name | | `planDesc` | string | Subscription plan description | | `merchantId` | string | Merchant ID that created the plan | | `productNo` | string | Product number | | `productName` | string | Product name | | `cryptoCurrency` | string | Cryptocurrency | | `chain` | string | Blockchain network (may be empty when no on-chain authorization) | | `userAddress` | string | User authorized address | | `authorizedAmount` | string | Authorized amount | | `cryptoAmount` | string | Single deduction amount | | `paidCount` | integer | Number of completed deductions | | `totalPaidAmount` | string | Total deducted amount | | `paymentChannel` | string | Payment channel, e.g. `GATEPAY`, `WEB3` (may be empty) | | `period` | string | Billing period, e.g. `MONTH`, `NONE` | | `interval` | integer | Billing interval | | `totalPayCount` | integer | Total number of deductions required | | `trialDays` | integer | Trial days | | `endTime` | int64 | Subscription end time in ms (`0` if not set) | | `lastPayTime` | int64 | Last deduction time in ms (`0` if none) | | `orderStatus` | string | Order status; matches top-level `bizStatus` | | `createTime` | int64 | Order creation time in ms | | `updateTime` | int64 | Order update time in ms | ## Callback example ### Running (`bizStatus=RUNNING`) ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "RUNNING", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"RUNNING\",\"paidCount\":2,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0.2\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` ### Order cancelled (`bizStatus=CANCELLED`) ```json theme={null} { "bizType": "SUBSCRIPTION_ORDER_STATUS", "bizId": "79544752854007999", "bizStatus": "CANCELLED", "data": "{\"authorizedAmount\":\"0\",\"chain\":\"\",\"createTime\":1779951098025,\"cryptoAmount\":\"0\",\"cryptoCurrency\":\"USDT\",\"endTime\":0,\"interval\":1,\"lastPayTime\":0,\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1779951098000_2059889959980175360\",\"orderStatus\":\"CANCELLED\",\"paidCount\":0,\"paymentChannel\":\"\",\"period\":\"NONE\",\"planDesc\":\"Users can authorize payment directly without topping up\",\"planName\":\"gateRouter authorization payment plan\",\"planNo\":\"84670588016525315\",\"productName\":\"gateRouter authorization payment plan\",\"productNo\":\"79396121215631409\",\"subscriptionOrderNo\":\"79544752854007999\",\"totalPaidAmount\":\"0\",\"totalPayCount\":0,\"trialDays\":0,\"updateTime\":1780037500658,\"userAddress\":\"\"}" } ``` # Payment Deduction Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/paymentNotify global/api-reference/version/100/en/openapi/subscription/paymentNotify-openapi.json webhook subscriptionOrderPaymentWebhook ## Overview This page documents `webhook subscriptionOrderPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. After a subscription billing cycle completes, GatePay sends an asynchronous notification to the merchant-configured callback URL. Depending on the payment channel, `bizType` may be `SUBSCRIPTION_PAYMENT` (Web3 on-chain deduction) or `ACCOUNT_AUTH_DEDUCTION` (Gate account authorized deduction). ## Notes * Use `bizId`, `paymentOrderNo`, or `deductOrderNo` for idempotency after parsing `data`. * Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature) for signing rules. ## When notifications are sent * GatePay sends a notification after each subscription billing cycle completes (success or failure) * If delivery fails, GatePay retries according to [Notifications overview](/global/api-reference/version/100/en/common/asyncNotification) * Use [Deduction order detail](/global/api-reference/version/100/en/endpoint/subscription/deductionOrderDetail) as a query fallback when needed ## Message structure | Field | Type | Description | | - | - | - | | `bizType` | string | `SUBSCRIPTION_PAYMENT` or `ACCOUNT_AUTH_DEDUCTION` | | `bizId` | string | Deduction order ID (for `SUBSCRIPTION_PAYMENT`, usually `paymentOrderNo`) | | `bizStatus` | string | See table below | | `data` | string | Deduction details as a JSON string; fields vary by `bizType` | ### bizStatus values | bizType | bizStatus | Description | | - | - | - | | `SUBSCRIPTION_PAYMENT` | `SUCCESS` | Web3 on-chain deduction succeeded | | `ACCOUNT_AUTH_DEDUCTION` | `DEDUCT_SUCCESS` | Gate account authorized deduction succeeded | | `ACCOUNT_AUTH_DEDUCTION` | `DEDUCT_FAILED` | Gate account authorized deduction failed | ## data fields (`bizType=SUBSCRIPTION_PAYMENT`) | Field | Type | Description | | - | - | - | | `subscriptionOrderNo` | string | Subscription order number | | `merchantSubscriptionOrderNo` | string | Merchant subscription order number | | `planNo` | string | Subscription plan number | | `paymentOrderNo` | string | Deduction order number for this cycle | | `merchantId` | string | Merchant ID | | `cryptoCurrency` | string | Cryptocurrency | | `chain` | string | Blockchain network | | `cryptoAmount` | string | Single deduction amount | | `userAddress` | string | User authorized address | | `authorizedAddress` | string | User authorized address (same as `userAddress` in some payloads) | | `merchantAddress` | string | Platform address that receives the deduction | | `txHash` | string | On-chain transaction hash | | `payStatus` | string | Deduction status: `SUCCESS` / `FAILED` | | `payTime` | int64 | Deduction time in ms | | `paymentChannel` | string | Payment channel; Web3 scenarios typically use `WEB3` | ## data fields (`bizType=ACCOUNT_AUTH_DEDUCTION`) | Field | Type | Description | | - | - | - | | `subscriptionOrderNo` | string | Subscription order number | | `merchantSubscriptionOrderNo` | string | Merchant subscription order number | | `merchantId` | string | Merchant ID | | `deductOrderNo` | string | Platform deduction order number | | `merchantDeductNo` | string | Merchant deduction order number | | `currency` | string | Deduction currency | | `amount` | number | Amount deducted in this cycle | | `totalDeducted` | number | Cumulative deducted amount | | `remainingAmount` | number | Remaining authorized balance | | `deductStatus` | string | Deduction status: `SUCCESS` / `FAILED` | | `deductTime` | int64 | Deduction time in ms | | `paymentChannel` | string | Payment channel; authorized deduction typically uses `GATEPAY` | ## Callback examples ### Web3 deduction success (`bizType=SUBSCRIPTION_PAYMENT`) ```json theme={null} { "bizType": "SUBSCRIPTION_PAYMENT", "bizId": "84670588016525429", "bizStatus": "SUCCESS", "data": "{\"authorizedAddress\":\"0x6ae9fb5258fb35d681f087dc343caf9d6e3d2cdc\",\"chain\":\"ARBEVM\",\"cryptoAmount\":\"0.1\",\"cryptoCurrency\":\"USDT\",\"merchantAddress\":\"0x26fd0b0898E235B996F8cBf184e97f6F8cd40676\",\"merchantId\":\"1627288\",\"merchantSubscriptionOrderNo\":\"2701761230\",\"payStatus\":\"SUCCESS\",\"payTime\":1776754665363,\"paymentChannel\":\"WEB3\",\"paymentOrderNo\":\"84670588016525429\",\"planNo\":\"84670588016525317\",\"subscriptionOrderNo\":\"84670588016525427\",\"txHash\":\"0xf82e60be5a922620e26a0e677a9b57a0daa527f0927940bde37bc4d9b57900c4\",\"userAddress\":\"0x20C58Cdf410Ac436D8c60c5163C47B7A5D91C91f\"}" } ``` ### Authorized payment deduction success (`bizType=ACCOUNT_AUTH_DEDUCTION`) ```json theme={null} { "bizType": "ACCOUNT_AUTH_DEDUCTION", "bizId": "79411443511329070", "bizStatus": "DEDUCT_SUCCESS", "data": "{\"amount\":0.079105,\"currency\":\"USDT\",\"deductOrderNo\":\"79547802280788015\",\"deductStatus\":\"SUCCESS\",\"deductTime\":1780017431027,\"merchantDeductNo\":\"8065258f169b683f5d742c06ac1ca547-f367d789274fa47e\",\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1776078867177_2039617990602551296\",\"paymentChannel\":\"GATEPAY\",\"remainingAmount\":196.830553,\"subscriptionOrderNo\":\"79411443511329070\",\"totalDeducted\":3.169447}" } ``` ### Authorized payment deduction failed (`bizType=ACCOUNT_AUTH_DEDUCTION`) ```json theme={null} { "bizType": "ACCOUNT_AUTH_DEDUCTION", "bizId": "79411443511329070", "bizStatus": "DEDUCT_FAILED", "data": "{\"amount\":0.079105,\"currency\":\"USDT\",\"deductOrderNo\":\"79547802280788016\",\"deductStatus\":\"FAILED\",\"deductTime\":1780017431027,\"merchantDeductNo\":\"8065258f169b683f5d742c06ac1ca547-f367d789274fa47e\",\"merchantId\":\"50372118\",\"merchantSubscriptionOrderNo\":\"SUB_1776078867177_2039617990602551296\",\"paymentChannel\":\"GATEPAY\",\"remainingAmount\":196.830553,\"subscriptionOrderNo\":\"79411443511329070\",\"totalDeducted\":3.169447}" } ``` # Query Subscription Plan Details Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/planDetail global/api-reference/version/100/en/openapi/subscription/planDetail-openapi.json GET /pay-subscription/open/v1/plan/detail Query subscription plan details ## Overview This page documents the `GET /pay-subscription/open/v1/plan/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Subscription Plan List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/planList global/api-reference/version/100/en/openapi/subscription/planList-openapi.json GET /pay-subscription/open/v1/plan/list Query subscription plan list ## Overview This page documents the `GET /pay-subscription/open/v1/plan/list` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Subscription Plan Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/planSave global/api-reference/version/100/en/openapi/subscription/planSave-openapi.json POST /pay-subscription/open/v1/plan/save Create subscription plan ## Overview This page documents the `POST /pay-subscription/open/v1/plan/save` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Product Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/productCreate global/api-reference/version/100/en/openapi/subscription/productCreate-openapi.json POST /merchant/open/v1/pay/merchant/product/create Create product ## Overview This page documents the `POST /merchant/open/v1/pay/merchant/product/create` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Product List Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/productPageQuery global/api-reference/version/100/en/openapi/subscription/productPageQuery-openapi.json POST /merchant/open/v1/pay/merchant/product/pageQuery Query product list details ## Overview This page documents the `POST /merchant/open/v1/pay/merchant/product/pageQuery` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Product Details Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/subscription/productQueryOne global/api-reference/version/100/en/openapi/subscription/productQueryOne-openapi.json POST /merchant/open/v1/pay/merchant/product/queryOne Query product details ## Overview This page documents the `POST /merchant/open/v1/pay/merchant/product/queryOne` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Native Pre-order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/webpayment/native global/api-reference/version/100/en/openapi/web-payment-openapi.json POST /v1/pay/transactions/native Create a Web payment prepay order and return the prepay ID, QR content and Web payment component redirect URL. ## Overview This page documents the `POST /v1/pay/transactions/native` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Close Pre-order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/webpayment/orderClose global/api-reference/version/100/en/openapi/web-payment-openapi.json POST /v1/pay/order/close When the merchant order is canceled, the merchant can proactively request GatePay to close an unpaid prepay order. Orders in the following statuses cannot be closed: `PAID` / `EXPIRED` / `ERROR` / `REJECTED` / `CANCELLED`. ## Overview This page documents the `POST /v1/pay/order/close` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * Orders in the following statuses cannot be closed: `PAID` / `EXPIRED` / `ERROR` / `REJECTED` / `CANCELLED`. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Order Status Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/webpayment/orderQuery global/api-reference/version/100/en/openapi/web-payment-openapi.json POST /v1/pay/order/query Query the status and detailed information of an order. ## Overview This page documents the `POST /v1/pay/order/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * This endpoint returns the order-query payload directly and does not use the outer `bizType` / `bizStatus` callback envelope. * For centralized payment orders, interpret `pay_amount` together with `orderAmount`. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Withdrawal Callback Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/callback global/api-reference/version/100/en/openapi/withdraw-callback-openapi.json webhook callbackWebhook When a batch withdrawal order status changes (e.g., all successful, all failed, or partially successful), GatePay will send an asynchronous POST notification to the callback URL configured by the merchant. The callback message contains the `main_order` object and `suborders` array. After receiving the callback, signature verification must be performed before processing business logic. Use `batch_id` + `merchant_withdraw_id` as the idempotency key to avoid duplicate updates. If no callback is received for an extended period, polling compensation can be done through the withdrawal query API. ## Overview This page documents `webhook callbackWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above. When batch withdrawal/payout status changes, GatePay notifies your callback URL using the dedicated **`WITHDRAW`** payload (**no** `data` field). ## Notes * Use `batch_id` + `merchant_withdraw_id` for idempotency. * Signature verification, retries, and the success response: [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification); signing: [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). * Use [Withdrawal query](/global/api-reference/version/100/en/endpoint/withdraw/withdrawQuery) if callbacks are delayed. ## Trigger Scenarios * When a batch withdrawal/payout order status changes (all succeeded, all failed, or partially succeeded), GatePay sends a notification to the **callback URL** configured at merchant registration * If delivery fails, see retry rules in [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). **Scope**: Batch and sub-order withdrawal/payout status changes, corresponding to **`bizType=WITHDRAW`** in the general callback taxonomy. For integration guidance, see [Payout](/global/essentials/version/100/en/outflow/payout). ## bizType Reference In the [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification) `bizType` enumeration, withdrawal notifications use **`WITHDRAW`** to indicate withdrawal/payout status changes. Unlike payment or refund callbacks that use the standard envelope (`bizType`, `bizId`, `bizStatus`, `client_id`, `data`), **`WITHDRAW` callbacks use a dedicated payload**: the request body contains `main_order` (batch header) and `suborders` (line items) directly, with batch status in `main_order.status`. ## bizStatus Values Terminal notification semantics align with the `bizStatus` values below. Batch progress is also reflected in `main_order.status` (including intermediate values such as `INIT` and `PROCESSING`). | Value | Description | | - | - | | `WITHDRAW_SUCCESS` | Entire batch succeeded; all sub-orders reached a terminal state (maps to `main_order.status=SUCCESS`) | | `WITHDRAW_PARTIAL` | Batch partially succeeded; some sub-orders succeeded and some failed (maps to `main_order.status=PARTIAL`) | | `WITHDRAW_FAIL` | Entire batch failed (maps to `main_order.status=FAIL`) | ## Message Structure | Field | Type | Description | | - | - | - | | `main_order` | object | Batch header; see table below | | `suborders` | array | Sub-order list; see table below | ### Example Message ```json theme={null} { "main_order": { "accountId": 10002, "batch_id": "831618381568", "merchant_id": 17329983, "status": "SUCCESS", "client_id": "igasgasdbub", "pay_back_status": "NO", "channel_id": "", "batchRemark": "" }, "suborders": [ { "accountId": 10002, "suborder_id": "30969031299072", "remark": "", "status": "DONE", "merchant_withdraw_id": "1839295815", "currency": "USDT", "amount": 2362.1, "memo": "" } ] } ``` ## Batch Status (`main_order.status`) | Value | Terminal | Description | | - | - | - | | `INIT` | No | Batch created; initial validation in progress | | `PROCESSING` | No | Batch processing; funds in transit | | `PARTIAL` | Yes | Some sub-orders succeeded, some failed | | `FAIL` | Yes | Entire batch failed | | `SUCCESS` | Yes | Entire batch succeeded; all sub-orders completed | **Typical callback sequence**: `INIT` → `PROCESSING` → terminal state (`SUCCESS` / `PARTIAL` / `FAIL`). ## main_order Field Reference | Field | Type | Description | | - | - | - | | `batch_id` | string | Batch ID | | `merchant_id` | int64 | Merchant ID | | `status` | string | Batch status; see table above | | `client_id` | string | `client_id` used when creating the batch | | `pay_back_status` | string | Rollback status | | `channel_id` | string | Customer name / channel identifier | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | | `batchRemark` | string | Remark. Maximum length 200 characters. | ## suborders Item Fields | Field | Type | Description | | - | - | - | | `suborder_id` | string | Sub-order ID | | `merchant_id` | int64 | Merchant ID | | `channel_id` | string | Customer name / channel identifier | | `chain` | string | Blockchain network | | `from_address` | string | Sender on-chain address | | `address` | string | Recipient address | | `currency` | string | Currency | | `amount` | number | Transfer amount | | `fee` | number | Fee | | `tx_id` | string | Transaction hash | | `memo` | string | On-chain memo/tag (not the business `remark`) | | `remark` | string | Remark. Maximum length 200 characters. | | `status` | string | Sub-order status: `DONE` (success) or `FAIL` (failure) | | `merchant_withdraw_id` | string | Merchant withdrawal ID; recommended idempotency key | | `fee_type` | int | Fee type: `0` internal deduction, `1` external deduction | | `batch_withdraw_id` | string | Batch withdrawal ID | | `desc` | string | Description | | `reconciliation_status` | int | Reconciliation status | | `is_placed` | int | Submission flag: `0` not submitted, `1` submitted | | `finish_time` | int64 | Completion time (milliseconds) | | `sub_amount` | number | Total sub-order amount | | `done_amount` | number | Actually completed amount | | `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. | Use `batch_id` + `merchant_withdraw_id` as the idempotency key to avoid duplicate updates. If no callback is received for an extended period, poll via [Withdrawal query](/global/api-reference/version/100/en/endpoint/withdraw/withdrawQuery). ## Callback Example ### Batch withdrawal fully succeeded (`main_order.status=SUCCESS`) ```json theme={null} { "main_order": { "accountId": 10002, "batch_id": "1526052914503263472", "merchant_id": 48177363, "status": "SUCCESS", "client_id": "DlaHYwkeGDjSGRVr", "pay_back_status": "NO", "channel_id": "", "batchRemark": "" }, "suborders": [ { "accountId": 10002, "fee": "0.0499", "desc": "", "chain": "BASEEVM", "tx_id": "0x2546829d95b7614acebde9dcc92d5b880ae82fa9791c2f80faa7ca668fc5cd3b", "amount": "0.1", "status": "DONE", "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf", "currency": "USDC", "fee_type": 0, "channel_id": "", "sub_amount": "0.1", "done_amount": "0.0501", "finish_time": 1780037579000, "merchant_id": 48177363, "suborder_id": "79553574716833917", "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe", "batch_withdraw_id": "1526052914503263472", "merchant_withdraw_id": "1526052914503263472", "reconciliation_status": 0, "memo": "", "remark": "" } ] } ``` ### Partial success (`main_order.status=PARTIAL`) ```json theme={null} { "main_order": { "accountId": 10002, "batch_id": "1526052914503263472", "merchant_id": 48177363, "status": "PARTIAL", "client_id": "DlaHYwkeGDjSGRVr", "pay_back_status": "NO", "channel_id": "", "batchRemark": "" }, "suborders": [ { "accountId": 10002, "fee": "0.0499", "desc": "", "chain": "BASEEVM", "tx_id": "0x2546829d95b7614acebde9dcc92d5b880ae82fa9791c2f80faa7ca668fc5cd3b", "amount": "0.1", "status": "DONE", "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf", "currency": "USDC", "fee_type": 0, "channel_id": "", "sub_amount": "0.1", "done_amount": "0.0501", "finish_time": 1780037579000, "merchant_id": 48177363, "suborder_id": "79553574716833917", "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe", "batch_withdraw_id": "1526052914503263472", "merchant_withdraw_id": "1526052914503263472", "reconciliation_status": 0, "memo": "", "remark": "" }, { "accountId": 10002, "fee": "0.0499", "desc": "", "chain": "BASEEVM", "tx_id": "", "amount": "0.1", "remark": "", "status": "FAIL", "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf", "currency": "USDC", "fee_type": 0, "channel_id": "", "sub_amount": "0.1", "done_amount": "0.0501", "finish_time": 1780037579000, "merchant_id": 48177363, "suborder_id": "79553574716833918", "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe", "batch_withdraw_id": "1526052914503263472", "merchant_withdraw_id": "1526052914503263473", "reconciliation_status": 0, "memo": "" } ] } ``` ### All failed (`main_order.status=FAIL`) ```json theme={null} { "main_order": { "accountId": 10002, "batch_id": "1526052914503263472", "merchant_id": 48177363, "status": "FAIL", "client_id": "DlaHYwkeGDjSGRVr", "pay_back_status": "NO", "channel_id": "", "batchRemark": "" }, "suborders": [ { "accountId": 10002, "fee": "0.0499", "desc": "", "chain": "BASEEVM", "tx_id": "", "amount": "0.1", "status": "FAIL", "address": "0x524287c1e5a312a12c76380a3227611d3cb20ddf", "currency": "USDC", "fee_type": 0, "channel_id": "", "sub_amount": "0.1", "done_amount": "0.0501", "finish_time": 1780037579000, "merchant_id": 48177363, "suborder_id": "79553574716833917", "from_address": "0x0D0707963952f2fBA59dD06f2b425ace40b492Fe", "batch_withdraw_id": "1526052914503263472", "merchant_withdraw_id": "1526052914503263472", "reconciliation_status": 0, "memo": "", "remark": "" } ] } ``` # Query Supported Withdrawal Chains Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/currencyChains global/api-reference/version/100/en/openapi/withdraw-openapi.json GET /v1/pay/wallet/currency_chains Query supported blockchain networks and related configuration for a specific currency. ## Overview This page documents the `GET /v1/pay/wallet/currency_chains` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Merchant Batch Transfer Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/reward-distribution/create global/api-reference/version/100/en/openapi/withdraw-openapi.json POST /v1/pay/batch/transfer Create a batch transfer order from a merchant to multiple users. ## Overview This page documents the `POST /v1/pay/batch/transfer` endpoint, which creates a batch transfer order from a merchant to multiple users. The full request schema, response structure, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This endpoint is grouped under `Payout` → `Reward Distribution`. * `X-GatePay-On-Behalf-Of` is optional for this endpoint. Pass it only when you need to specify the initiating account context in an institution-delegated scenario. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Merchant Batch Transfer Order Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/reward-distribution/query global/api-reference/version/100/en/openapi/withdraw-openapi.json POST /v1/pay/batch/transfer/query Query a merchant batch transfer order and its sub-order statuses by batch_id or merchant_batch_no. ## Overview This page documents the `POST /v1/pay/batch/transfer/query` endpoint, which queries a merchant batch transfer order and its sub-order statuses. The full request schema, response structure, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This endpoint is grouped under `Payout` → `Reward Distribution`. * `X-GatePay-On-Behalf-Of` is optional for this endpoint. Pass it only when you need to specify the initiating account context in an institution-delegated scenario. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Reward Distribution Notification Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/rewardDistributionNotify global/api-reference/version/100/en/openapi/batch-transfer-callback-openapi.json webhook batchTransferWebhook After all sub-orders in a reward distribution batch are paid successfully, GatePay sends a webhook with `bizType` `PAY_BATCH`. Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview. ## Overview This page documents asynchronous order-status notifications for reward distribution, corresponding to `webhook batchTransferWebhook`. GatePay sends this notification to the merchant callback URL **after all sub-orders in the batch are paid successfully**. The notification uses the standard notification envelope: * `bizType` is always `PAY_BATCH` * `bizId` is the batch order ID * `bizStatus` is the batch order status; it is `PAID` when the payout succeeds * `data` is a **JSON string** ## Notes * Signature verification, retries, and success response: [Notifications Overview](/global/api-reference/version/100/en/common/asyncNotification). * Signing rules: [Security and Signature](/global/api-reference/version/100/en/common/securityAndSignature). * Prefer idempotency on `merchant_batch_no` + `reward_id`. * If a notification is delayed, call [Merchant batch transfer order query](/global/api-reference/version/100/en/endpoint/withdraw/reward-distribution/query) for reconciliation. ## Trigger scenarios Reward-distribution notifications are sent only when **the entire batch is paid successfully**. In this case, `bizStatus` and each sub-order `status` are `PAID`. ## Message structure | Field | Type | Description | | - | - | - | | `bizType` | string | Always `PAY_BATCH` | | `bizId` | string | Batch order ID | | `bizStatus` | string | Batch order status; `PAID` when the payout succeeds | | `data` | string | Business payload as a JSON string; parse it as JSON first | ### Example message ```json theme={null} { "bizType": "PAY_BATCH", "bizId": "79553020665790540", "bizStatus": "PAID", "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"reward_id\":\"50888456789213330\",\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}" } ``` ## `data` fields After parsing `data`, the object fields are: | Field | Type | Description | | - | - | - | | `merchant_batch_no` | string | Merchant batch number | | `batchItemList` | array | Reward-distribution sub-order list | ### `batchItemList` item fields | Field | Type | Description | | - | - | - | | `amount` | string | Reward amount | | `channel_id` | string | Customer name / channel ID; omitted when not set | | `create_time` | int64 | Create time in milliseconds | | `currency` | string | Currency | | `receiver_id` | int64 | Receiver UID | | `reward_id` | string | Reward / business sub-order ID; omitted when not set | | `status` | string | Sub-order status; `PAID` when the payout succeeds | ## Callback example ### Reward distribution batch success ```json theme={null} { "bizType": "PAY_BATCH", "bizId": "79553020665790540", "bizStatus": "PAID", "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"reward_id\":\"50888456789213330\",\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}" } ``` ## Integration tips 1. Verify the signature before parsing the body. 2. Deserialize `data` as JSON, then read `merchant_batch_no` and `batchItemList`. 3. Identify the batch with `merchant_batch_no` and each reward with `reward_id`. 4. Treat each item's `status` as the actual payout result. 5. After successful handling, return HTTP 200 with the standard success body: ```json theme={null} { "returnCode": "SUCCESS", "returnMessage": "" } ``` # Query Withdrawal Records Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/walletWithdrawals global/api-reference/version/100/en/openapi/withdraw-openapi.json GET /v1/pay/wallet/withdrawals Query account withdrawal records list based on filter criteria. ## Overview This page documents the `GET /v1/pay/wallet/withdrawals` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Create Withdrawal Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/withdraw global/api-reference/version/100/en/openapi/withdraw-openapi.json POST /v1/pay/withdraw Create a batch withdrawal order. The merchant submits one batch ID with multiple withdrawal sub-orders. ## Overview This page documents the `POST /v1/pay/withdraw` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Withdrawal Status Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/withdrawQuery global/api-reference/version/100/en/openapi/withdraw-openapi.json POST /v1/pay/withdraw/query Query the status and details of a batch withdrawal order and its sub-orders by batch ID and detail status. ## Overview This page documents the `POST /v1/pay/withdraw/query` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Query Withdrawal Fee Source: https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/withdrawStatus global/api-reference/version/100/en/openapi/withdraw-openapi.json GET /v1/pay/wallet/withdraw_status Query withdrawal fee configuration and limits for a specific currency. ## Overview This page documents the `GET /v1/pay/wallet/withdraw_status` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above. ## Notes * Authentication uses the standard GatePay signed headers. * This page documents the standard merchant endpoint. * For shared signing rules, see [/global/api-reference/version/100/en/common/securityAndSignature](/global/api-reference/version/100/en/common/securityAndSignature). # Notifications Overview Source: https://docs.gate.com/eu/api-reference/version/100/en/common/asyncNotification Explains GatePay asynchronous notifications, including payload structure, status enums, retry rules, and signature verification. ## Reading path We recommend this order when integrating notifications: 1. **This page (overview)** — shared envelope, retries, signature verification, and `bizType` reference 2. **Business notification pages** — field tables and examples (the refund and reward-distribution pages in this menu) 3. **[Guide: Notification](/eu/essentials/version/100/en/common/notification)** — event catalog, terminal-state handling, and product-to-`bizType` mapping 4. **[Best practices](/eu/api-reference/version/100/en/common/bestPractices)** — payment query fallback, 10s refund rule, and security guidance ## Overview When order status changes (payment success, timeout, cancellation, closure, exception, and similar events), GatePay sends an asynchronous POST notification to the **callback URL** configured at merchant registration. * **Delivery**: GatePay delivers JSON notifications to your callback URL via POST. * **Retry**: If delivery fails due to network or other issues, GatePay retries after **15 seconds (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)**. If retries still fail, use the relevant query APIs to obtain the latest status. * **Idempotency**: The same business event may be delivered more than once. Implement idempotent processing using business-unique identifiers such as `bizId` and `merchantTradeNo`. ## Processing requirements 1. **Verify signature**: Validate the signature before processing business logic. Request headers include `X-GatePay-Timestamp`, `X-GatePay-Nonce`, and `X-GatePay-Signature`. See [Security and Signature](/eu/api-reference/version/100/en/common/securityAndSignature). 2. **Parse `data`**: For standard-envelope callbacks, `data` is a **JSON string** — call `JSON.parse` before reading fields. **Exception:** Some payout-shaped payloads may omit `data` and use a dedicated order list shape. On the EU site, prefer [Reward Distribution Notification](/eu/api-reference/version/100/en/endpoint/withdraw/rewardDistributionNotify) for batch reward callbacks. Top-level `client_id` / `clientId` may be absent or mixed; follow the actual callback. 3. **Acknowledge**: Return HTTP 200 with JSON `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. Returning `FAIL` or timing out triggers retries. ## Message structure | Field | Description | | - | - | | bizType | Business type | | bizId | Business ID | | bizStatus | Business status | | client_id / clientId | Application ClientId (field name varies; may be absent) | | data | Business payload as a JSON string (see each business notification page) | ### Message JSON example ```json theme={null} { "bizType": "PAY", "bizId": "order_123456", "bizStatus": "PAY_SUCCESS", "client_id": "your_client_id", "data": "{...}" } ``` ## bizType On the EU site, documented callback pages cover payment, refund, and reward-distribution notifications: | bizType | Description | | - | - | | `PAY` | Gate Pay order status | | `PAY_REFUND` | Refund status | | `PAY_BATCH` | Batch transfer / reward | ## Terminal states at a glance | bizType | bizStatus (examples) | Terminal | Suggested action | | - | - | - | - | | `PAY` | `PAY_SUCCESS` | Yes | Mark paid and fulfill | | `PAY` | `PAY_ERROR` / `PAY_CLOSE` | Yes | Mark failed/closed; stop polling | | `PAY_REFUND` | `REFUND_PROCESS` | No | Mark processing; wait or query | | `PAY_REFUND` | `REFUND_SUCCESS` / `REFUND_REJECTED` | Yes | Reconcile / manual review | ## bizStatus enum (payment) | bizStatus | Description | | - | - | | PAY_SUCCESS | Payment successful | | PAY_ERROR | Payment failed | | PAY_CLOSE | Payment closed | | REFUND_SUCCESS | Refund successful | | REFUND_PROCESS | Refund in process | | REFUND_REJECTED | Refund rejected | | PAID | Batch order paid | Other statuses may appear in production payloads but are not published in the EU API Reference. # Best Practices Source: https://docs.gate.com/eu/api-reference/version/100/en/common/bestPractices Provides recommended implementation patterns for callbacks, order queries, refunds, and security controls. ## 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 (twice), 30 seconds, 3 minutes, 10 minutes, 20 minutes, 30 minutes (three times), 60 minutes, 3 hours (three times), and 6 hours (twice)) ## 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. **Q: Which currencies are supported for placing orders?** A: On the EU site, orders are created with fiat pricing — pass `fiatCurrency` and `fiatAmount` at order creation, and the amount is converted to cryptocurrency using the real-time exchange rate. Settlement defaults to USDC. For the supported crypto currencies, see [Supported Currencies](/eu/api-reference/version/100/en/common/supportedCurrencies). # Error Codes Source: https://docs.gate.com/eu/api-reference/version/100/en/common/errorCodes Summarizes common GatePay error codes, their meanings, and recommended handling actions. | HTTP Status | Error Code | Description | Solution | | - | - | - | - | | `500` | `300000` | System error | System exception, please retry with the same parameters | | `500` | `300001` | Internal error | System exception, please retry with the same parameters | | `500` | `400000` | Unknown error | System exception, please retry with the same parameters | | `200` | `400001` | Request parameter format error | Check request data parameters and format | | `200` | `400002` | Signature verification failed | Check if the merchant's signature is correct | | `200` | `400003` | Request timestamp timed out | Check the timestamp field in the request header | | `200` | `400004` | API identity key invalid | Check whether the `GatePay-Api-Key` request header is configured correctly | | `200` | `400005` | Client identifier invalid | Check whether the `GatePay-Client-Id` request header is configured correctly | | `200` | `400007` | Unsupported media type | Check the media type set in the interface | | `200` | `400020` | Signature random number error | Please check whether the random number is empty | | `200` | `400201` | Merchant order number already exists | Please verify whether the merchant order number has been submitted repeatedly | | `200` | `400202` | Order does not exist | Check whether the order has been traded or whether the order number is correct | | `200` | `400203` | Merchant number does not exist | Check whether the merchant number is correct | | `200` | `400204` | Order status is incorrect | Check whether the order has expired, canceled, or closed, and use the query interface if necessary | | `200` | `400205` | Invalid currency | Check the currency type of the order | | `200` | `400304` | Refund ID does not exist | Check the requested refund ID | | `200` | `400305` | Merchant channel information does not exist | Check whether `channelId` is correct and not deleted | | `200` | `400603` | Order timed out | Please verify whether the order has expired | | `200` | `400604` | Invalid refund-related transaction order | Check whether the refund transaction order is in a completed state | | `200` | `400605` | Insufficient balance in the payment account | Insufficient balance in the payment account | | `200` | `400607` | Too many refunds | The number of refunds exceeds the limit | | `200` | `400608` | Refund amount exception | Please check the refund amount | | `200` | `400620` | Duplicate order payment | Please verify whether the merchant order number has been submitted repeatedly | | `200` | `400621` | Incorrect payment amount | Check the requested amount | | `200` | `400622` | Exchange rate fluctuations result in payment failure | You can try to apply again | | `200` | `400623` | Unsupported currency payment | Check the payment currency | | `200` | `400624` | Invalid order status notification address | Check whether the callback address provided by the merchant is valid | | `200` | `400702` | Merchant has not enabled channel payment permission | Please confirm whether the merchant has enabled the corresponding channel payment permission | | `200` | `500008` | Corresponding merchant not found | Check whether the requested merchant ID is correct | | `200` | `500100` | Payment QR code expired | Reorder and generate a new QR code | | `200` | `500101` | Duplicate payment QR code | Please verify the order status | | `200` | `500204` | Invalid recipient ID for refund transaction order | Please confirm that the recipient of the refund is a Gate user | | `200` | `500205` | Refund currency does not match | Please ensure that the refund currency is one of the order currency or the user's payment currency | | `200` | `500206` | Refund amount exceeds limit | Please check the refund amount of the order | | `200` | `550008` | Subaccount status abnormal | Retry later with the same parameters; contact support if the failure persists | | `200` | `550018` | Risk control engine rejected this transaction | Check the transaction characteristics or contact operations | | `200` | `550020` | Source IP / region is on the sanctions list | Please switch to a compliant network environment | | `200` | `550143` | Surcharge amount is invalid | Adjust the surcharge to a non-negative value that does not exceed the configured upper limit | | `200` | `550203` | Tolerance amount is invalid | Ensure the tolerance amount is >= 0 and less than the payable amount | | `200` | `550205` | Amount precision is invalid | Check whether the decimal precision of the order amount and surcharge meets requirements | | `200` | `5502724` | Channel name contains invalid characters | `channelId` only allows Chinese, English letters, numbers, underscores, hyphens, and spaces; remove special characters and retry | | `200` | `5502740` | Subaccounts do not support creating orders | Use the main account or an account with the appropriate permissions | | `200` | `5502761` | Request conflict | Use a different merchant order number, or retry idempotently with the same parameters | | `200` | `5504080` | Security item change limit exceeded within 24h | Please wait 24 hours after the security item change before retrying | # Merchant Access Source: https://docs.gate.com/eu/api-reference/version/100/en/common/merchantAccess Explains the base URL, credential preparation, and common request headers used by GatePay merchants. ## Base URL `https://openplatform-eu.gateapi.io` If this is your first time reading the GatePay documentation, start with [Quickstart](/eu/essentials/version/100/en/common/quickstart) and the [Merchant Access guide](/eu/essentials/version/100/en/common/accessguide), then return to this reference section after your application, signing, and callback setup are ready. ## Integration Setup 1. Sign in to the GatePay merchant portal at [https://www.gate.com/en-eu/merchant#/get-started](https://www.gate.com/en-eu/merchant#/get-started) 2. Complete the required business information and merchant application 3. Open the application configuration page and create a new application 4. View the configured application list and obtain the application ClientId ## Generate Secrets 1. Open the developer page and generate a **Payment API Secret Key** for payment API signing and callback verification 2. Generate an **Authorization Secret Key** for authorization-related signing flows 3. Configure the callback URL so asynchronous notifications can be verified and processed ## Key Parameters | Parameter | Description | | - | - | | Payment API key | Used for payment request signing and callback verification | | ClientId | Used to identify your application | ## Common request headers Standard merchant APIs use the following common headers: | Header | Description | | - | - | | X-GatePay-Certificate-ClientId | Application ClientId | | X-GatePay-Timestamp | Millisecond timestamp; the difference from server time must not exceed 30 seconds. | | X-GatePay-Nonce | Request nonce | | X-GatePay-Signature | Request signature calculated with the signing rules | # Security and Signature Source: https://docs.gate.com/eu/api-reference/version/100/en/common/securityAndSignature Explains protocol rules, shared response structure, request headers, and the GatePay signing algorithm. ## 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 ```json theme={null} { "status": "SUCCESS", "code": "000000", "label": "Success", "errorMessage": "", "data": "{...}" } ``` ### Failure example ```json theme={null} { "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`. ### 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-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** ```go theme={null} 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** ```java theme={null} 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 = "{\"merchantTradeNo\":\"order_12345\",\"fiatCurrency\":\"EUR\",\"fiatAmount\":\"100.50\"}"; String data = String.format("%s\n%s\n%s\n", timeStamp, nonce, body); String key = "your_secret_key"; String hmac = calculateHMAC(data, key); System.out.println(hmac); } } ``` **Python** ```python theme={null} 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 theme={null} \n\n\n ``` Where: * `` is the value of `X-GatePay-Timestamp` * `` is the value of `X-GatePay-Nonce` * `` 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 as a hexadecimal string 7. Place the computed signature into the `X-GatePay-Signature` header ### Example Request Structure The following example is provided only to explain how the signing string is constructed. It is not a complete business-ready request body for a specific endpoint. For actual required fields, always follow the corresponding API Reference page and OpenAPI definition. ```json theme={null} POST /v1/pay/transactions/native HTTP/1.1 Host: openplatform-eu.gateapi.io Content-Type: application/json X-GatePay-Certificate-ClientId: your_client_id X-GatePay-Timestamp: 1234567890000 X-GatePay-Nonce: abc123def456ghi789 X-GatePay-Signature: { "merchantTradeNo": "order_12345", "fiatCurrency": "EUR", "fiatAmount": "100.50" } ``` ## 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](/eu/essentials/version/100/en/common/notification) guide. ### Callback Payload Structure The payload below is shown to explain the common callback envelope. The object carried in `data` varies by product and business type, so it should always be read together with the relevant product guide and callback reference. GatePay will POST a JSON payload with the following structure: ```json theme={null} { "bizType": "PAY", "bizId": "329782527190433792", "bizStatus": "PAY_SUCCESS", "client_id": "iVNJZdekOCMJIsmV", "data": "{\"merchantTradeNo\":\"1894789022551797760\"}" } ``` Where: | Field | Type | Description | | - | - | - | | `bizType` | string | The type of business event (e.g., `PAY`, `PAY_REFUND`). | | `bizId` | string | The unique identifier for the payment order or business transaction. | | `bizStatus` | string | The current status of the transaction (e.g., `PAY_SUCCESS`, `REFUND_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. | ## Time Window Clarification Two different time windows appear in this documentation, and they apply to different scenarios: | Scenario | Time Window | Meaning | | - | - | - | | Merchant-initiated API request | 10 seconds | GatePay request-acceptance window for the request timestamp. Requests outside this drift may be rejected. | | Merchant-side callback verification | 5 minutes (recommended) | Recommended local anti-replay validation window for incoming callbacks. It is not the same as the platform request-acceptance threshold. | Read them as follows: * `10 seconds` applies to requests you send to GatePay. * `5 minutes` is a recommended merchant-side validation window when verifying callbacks. * If your security model requires a stricter callback window, you can reduce it as long as normal network delay is still tolerated. ## 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/en-eu/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](/eu/essentials/version/100/en/common/error) 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:** Keep merchant-initiated request timestamps within the 10-second acceptance window, and use a local callback-validation window such as 5 minutes for anti-replay checks. 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](/eu/essentials/version/100/en/common/overview) - App configuration and credential setup * [Notification](/eu/essentials/version/100/en/common/notification) - Detailed callback event handling * [Error Codes and Best Practices](/eu/essentials/version/100/en/common/error) - Error code reference and troubleshooting # Balance Source: https://docs.gate.com/eu/essentials/version/100/en/common/balance Account reconciliation is critical for maintaining financial accuracy and trust. This guide covers balance queries, fee verification, and funds ledger tracking for end-of-day and periodic reconciliation. ## Overview GatePay provides multiple reconciliation tools to ensure account accuracy: * **Balance Query**: Real-time available balance by currency * **Order Fee Query**: Verify fees and settlement amounts at the order level * **Funds Ledger Query**: Track all fund movements by transaction For request headers, signature rules, and callback verification, refer to [Authentication & Security](/eu/essentials/version/100/en/common/authentication). *** ## Balance Query The balance query API retrieves the available balance of a merchant payment account by currency. For settlement, payout, and risk decisions, real-time query results must be used. ### Common Use Cases * **Pre-settlement validation**: Confirm available balance before initiating settlement * **Period-end snapshots**: Capture balance at close of business for accounting * **Operational monitoring**: Real-time balance alerts and thresholds * **Multi-currency management**: Track balances across different currencies ### API Reference **Endpoint:** `GET /v1/pay/balance/query` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `currencies` | array | No | List of currency codes to query (e.g., \["USDC", "BTC", "ETH"]) | If no currencies are specified, the API returns balances for all currencies in the account. #### Response Fields | Field | Type | Description | | - | - | - | | `currency` | string | Currency code | | `available` | string | Balance available for immediate use | | `hold` | string | Amount held by pending orders or payouts | | `total` | string | Total balance (available + hold) | | `last_updated` | timestamp | Timestamp of last balance update | #### Example Request ```bash theme={null} curl -X GET "https://openplatform-eu.gateapi.io/v1/pay/balance/query?currencies=USDC,BTC,ETH" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": [ { "currency": "USDC", "available": "10500.50", "hold": "499.50", "total": "11000.00", "last_updated": 1704067205000 }, { "currency": "BTC", "available": "0.25", "hold": "0.05", "total": "0.30", "last_updated": 1704067205000 }, { "currency": "ETH", "available": "12.50", "hold": "0.00", "total": "12.50", "last_updated": 1704067205000 } ] } ``` ### Integration Steps 1. **Call the balance query API** using `GET /v1/pay/balance/query` with desired currencies 2. **Store balances** by currency in your merchant's local accounting system 3. **Compare with local records** to identify discrepancies 4. **Alert on thresholds** if balance falls below operational minimums *** ## Order Fee Query The order fee query API provides detailed fee breakdown and settlement amounts at the individual order level. Use this for financial reconciliation and exception investigation. ### Common Use Cases * **Financial reconciliation**: Verify fees match merchant expectations * **Multiple or partial payments**: Reconcile complex order scenarios * **Exception investigation**: Identify fee anomalies or discrepancies * **Settlement confirmation**: Confirm amounts before initiating payout ### API Reference **Endpoint:** `GET /api/open/v1/pay/order/fee/query` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `orderId` | string | Conditional | GatePay order ID | | `merchant_order_no` | string | Conditional | Merchant-generated order number | Provide either `orderId` or `merchant_order_no` (at least one required). #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | GatePay order ID | | `merchant_order_no` | string | Merchant order number | | `orderAmount` | string | Original order amount | | `payAmount` | string | Amount customer paid | | `settlementAmount` | string | Amount credited to merchant account | | `gatewayFee` | string | GatePay processing fee | | `networkFee` | string | Blockchain network fee (if applicable) | | `discountAmount` | string | Discounts or rebates applied | | `currency` | string | Settlement currency | | `status` | string | Order status | | `created_at` | timestamp | Order creation time | | `settled_at` | timestamp | Settlement completion time | #### Example Request ```bash theme={null} curl -X GET "https://openplatform-eu.gateapi.io/api/open/v1/pay/order/fee/query?merchant_order_no=ORDER_12345" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": { "orderId": "ORD_abc123", "merchant_order_no": "ORDER_12345", "orderAmount": "1000.00", "payAmount": "1000.00", "settlementAmount": "980.00", "gatewayFee": "20.00", "networkFee": "0.00", "discountAmount": "0.00", "currency": "USDC", "status": "SETTLED", "created_at": 1704067200000, "settled_at": 1704067800000 } } ``` ### Integration Steps 1. **Call the order fee query API** using `GET /api/open/v1/pay/order/fee/query` with order identifier 2. **Store the query result** alongside your local order master data 3. **Compare settlement amounts** with expected values 4. **Flag discrepancies** for manual review if fee structure differs *** ## Funds Ledger Query The funds ledger query provides a complete transaction history of all fund movements in and out of the merchant account. This is essential for audit trails and comprehensive reconciliation. ### Common Use Cases * **End-of-day reconciliation**: Aggregate all fund movements for the day * **Audit tracing**: Track fund origins and destinations for compliance * **Exception investigation**: Identify timing issues or missing transactions * **Financial reporting**: Generate detailed movement reports by type and currency ### API Reference **Endpoint:** `GET /v1/pay/bill/orderlist` #### Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `start_time` | timestamp | No | Start of time range (UTC milliseconds) | | `end_time` | timestamp | No | End of time range (UTC milliseconds) | | `page` | integer | No | Page number for pagination (1-indexed, default 1) | | `limit` | integer | No | Records per page (default 20, max 100) | | `currency` | string | No | Filter by currency code | | `type` | string | No | Filter by transaction type (see enumeration below) | | `order_id` | string | No | Filter by related order ID | #### Response Fields | Field | Type | Description | | - | - | - | | `ledger_id` | string | Unique ledger entry identifier (use as deduplication key) | | `type` | string | Transaction type (see enumeration below) | | `currency` | string | Currency of transaction | | `amount` | string | Transaction amount (positive or negative) | | `balance_before` | string | Balance before transaction | | `balance_after` | string | Balance after transaction | | `business_id` | string | Related order, refund, transfer, or payout ID | | `description` | string | Human-readable description | | `created_at` | timestamp | Transaction timestamp (UTC milliseconds) | | `metadata` | object | Additional context (e.g., fee breakdown) | #### Transaction Type Enumeration | Type | Direction | Description | | - | - | - | | `PAYMENT` | Inbound | Customer payment received | | `PAYOUT` | Outbound | Settlement to merchant's bank account | | `REFUND` | Outbound | Refund issued to customer | | `TRANSFER_IN` | Inbound | Funds transferred in from another account | | `TRANSFER_OUT` | Outbound | Funds transferred out to another account | | `CHARGE` | Outbound | Platform commission or fee deduction | | `SWAP` | Neutral | Currency conversion (may show as two entries) | | `ADJUSTMENT` | Variable | Manual adjustment (credit or debit) | | `DEPOSIT` | Inbound | Direct deposit by merchant | #### Example Request ```bash theme={null} curl -X GET "https://openplatform-eu.gateapi.io/v1/pay/bill/orderlist?start_time=1704067200000&end_time=1704153600000&limit=50" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1704067200000" \ -H "X-GatePay-Nonce: abc123def456" \ -H "X-GatePay-Signature: your_signature" \ ``` #### Example Response ```json theme={null} { "data": [ { "ledger_id": "LED_20240101_001", "type": "PAYMENT", "currency": "USDC", "amount": "500.00", "balance_before": "10000.00", "balance_after": "10500.00", "business_id": "ORD_abc123", "description": "Payment from order ORDER_12345", "created_at": 1704067200000, "metadata": { "order_no": "ORDER_12345", "payer": "customer@example.com" } }, { "ledger_id": "LED_20240101_002", "type": "REFUND", "currency": "USDC", "amount": "-100.00", "balance_before": "10500.00", "balance_after": "10400.00", "business_id": "REF_xyz789", "description": "Refund for order ORDER_12346", "created_at": 1704067800000, "metadata": { "order_no": "ORDER_12346", "reason": "Customer requested" } }, { "ledger_id": "LED_20240101_003", "type": "TRANSFER_OUT", "currency": "USDC", "amount": "-1000.00", "balance_before": "10400.00", "balance_after": "9400.00", "business_id": "TRN_20240101", "description": "Transfer to sub-account", "created_at": 1704068400000, "metadata": { "account_id": "SUB_12345", "batch_no": "TRN_20240101" } } ], "pagination": { "page": 1, "limit": 50, "total": 3, "has_next": false } } ``` ### Integration Steps 1. **Pull funds ledger records** by time range with pagination using `GET /v1/pay/bill/orderlist` 2. **Persist ledger records** in your database using `ledger_id` as the primary deduplication key 3. **Associate ledger records** with business orders using `business_id` and metadata 4. **Generate reconciliation summaries** aggregated by: * Currency * Transaction type * Date or time bucket * Related business entity (order, refund, transfer, etc.) 5. **Compare with local records** to identify discrepancies 6. **Flag unmatched records** for investigation *** ## Recommended End-of-Day Reconciliation Flow Follow this step-by-step process for comprehensive daily reconciliation: ### Step 1: Capture Account Balance Snapshot ```bash theme={null} GET /v1/pay/balance/query ``` Store the balance snapshot for each currency at end of business day (e.g., 11:59 PM UTC). Record: * Available balance * Hold amount * Total balance * Snapshot timestamp ### Step 2: Pull Funds Ledger Records ```bash theme={null} GET /v1/pay/bill/orderlist?start_time={start_of_day}&end_time={end_of_day}&limit=100 ``` Retrieve all transactions for the reconciliation period with pagination. Store in local database keyed by `ledger_id`. ### Step 3: Pull Order Fees and Settlement Amounts For each order settled during the day: ```bash theme={null} GET /api/open/v1/pay/order/fee/query?merchant_order_no={order_id} ``` Store fee breakdown and settlement details. ### Step 4: Match and Reconcile Records Create a reconciliation table with the following structure: | Ledger ID | Type | Currency | Amount | Business ID | Matched | Notes | | - | - | - | - | - | - | - | | LED_001 | PAYMENT | USDC | +500 | ORD_123 | ✓ | Matched with order | | LED_002 | REFUND | USDC | -100 | REF_456 | ✓ | Matched with refund | | LED_003 | TRANSFER_OUT | USDC | -1000 | TRN_789 | ✓ | Matched with transfer | **Matching logic:** * Match PAYMENT ledger entries to your order system using `business_id` * Match REFUND entries to your refund system * Match TRANSFER_OUT/IN entries to your transfer records * Match PAYOUT entries to your settlement records ### Step 5: Generate Discrepancy Report Identify records that do not match: | Category | Count | Details | | - | - | - | | Missing ledger entries | 0 | Orders with no corresponding ledger entry | | Extra ledger entries | 1 | Ledger entries with no corresponding order | | Amount mismatches | 0 | Matched records with different amounts | | Timing discrepancies | 2 | Entries recorded on different dates | ### Step 6: Perform Manual Review For each discrepancy: 1. **Review the ledger entry** description and metadata 2. **Correlate with business records** (orders, refunds, transfers) 3. **Investigate timing** (same-day vs. next-day settlement) 4. **Document resolution** (matched, explained, or escalated) ### Step 7: Output Reconciliation Result Generate a formal reconciliation statement: ``` End-of-Day Reconciliation Report Date: 2024-01-01 Start Balance (USDC): 10,000.00 Ending Balance (USDC): 9,900.00 Transactions: - Payments In: +5,000.00 - Refunds Out: -2,500.00 - Transfers Out: -1,000.00 - Fees Out: -500.00 - Adjustments: -100.00 Calculated Ending Balance: 9,900.00 Actual Ending Balance: 9,900.00 Status: BALANCED ✓ Discrepancies: 0 Unmatched Records: 0 ``` *** ## Error Handling and Troubleshooting ### Common Issues | Issue | Cause | Resolution | | - | - | - | | Balance differs from local records | Timing of settlement or fee posting | Query again after 5-10 minutes; check for pending transactions | | Missing ledger entries | Delayed posting or query time range misalignment | Expand time range by 1-2 hours; retry query | | Duplicate ledger entries | Database deduplication failure | Use `ledger_id` as primary key to prevent duplicates | | Fee discrepancies | Promotion, rebate, or rate change | Compare with current rate table; check for adjustments | For comprehensive error codes, see [Error Codes & Best Practices](/eu/essentials/version/100/en/common/error). *** ## Best Practices ### Data Persistence * **Primary Key**: Use `ledger_id` for ledger entries to ensure idempotency * **Unique Constraints**: Enforce unique constraints on (ledger_id) to prevent duplicates * **Indexing**: Index by (`created_at`, `currency`, `type`) for fast reconciliation queries ### Query Optimization * **Time ranges**: Query in 24-hour buckets for faster response times * **Pagination**: Use `limit=100` and iterate through pages to avoid timeout * **Filters**: Use `currency` and `type` filters to reduce result sets ### Alerting and Monitoring * **Threshold alerts**: Alert when available balance falls below operational minimum * **Discrepancy alerts**: Alert immediately when reconciliation identifies unmatched records * **Timing alerts**: Alert if ledger entries are delayed by more than 2 hours * **Callback failure alerts**: Alert if expected callbacks are not received within SLA ### Documentation and Audit * **Reconciliation logs**: Store reconciliation results with timestamp and user ID * **Discrepancy tracking**: Maintain audit trail of identified and resolved discrepancies * **Rate cards**: Document fee structure and any promotional adjustments * **Settlement terms**: Document when and how funds are settled to merchant accounts *** ## Related Documentation * [Authentication & Security](/eu/essentials/version/100/en/common/authentication) * [Notification & Callbacks](/eu/essentials/version/100/en/common/notification) * [Error Codes & Best Practices](/eu/essentials/version/100/en/common/error) * [Currency Conversion & Swap](/eu/essentials/version/100/en/internalflow/swap) * [General Overview](/eu/essentials/version/100/en/common/overview) # Error Source: https://docs.gate.com/eu/essentials/version/100/en/common/error This guide covers GatePay API error codes and recommended practices for handling errors, callbacks, and asynchronous operations. ## General Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 400001 | Invalid request parameters | General | Check whether the request parameters are valid | | 400002 | Signature verification failed | General | Check the signature algorithm, signature string, and signing key. See [Authentication and Security](/eu/essentials/version/100/en/common/authentication) | | 400003 | Request timestamp expired | General | Check the timestamp header | | 400007 | Unsupported Content-Type | General | Check whether Content-Type meets API requirements | | 400020 | Invalid nonce | General | Check whether X-GatePay-Nonce is empty or malformed | | 400201 | Duplicate merchant order number | Order-creation APIs | Check whether the same merchant order number was submitted repeatedly | | 400202 | Order not found | Query APIs | Check whether the order number is correct | | 400204 | Invalid order status | Order-operation APIs | Check whether the order is expired, cancelled, or closed | | 400603 | Order timed out | Payment APIs | Confirm whether the order has expired | | 400621 | Incorrect payment amount | Payment APIs | Check the requested amount | | 400622 | Conversion failed due to exchange-rate fluctuation | Quote / conversion APIs | Retry if permitted by business flow | | 400624 | Invalid callback URL | Order-creation APIs | Check whether the callback URL is valid. See [Notifications and Callbacks](/eu/essentials/version/100/en/common/notification) | *** ## Batch Payout Error Codes For detailed payout error handling, see [Reward Distribution](/eu/api-reference/version/100/en/endpoint/withdraw/reward-distribution/create). | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 550233 | Insufficient balance | Batch payout | Check available balance | | 550234 | Memo too long | Batch payout | Check memo length | | 550235 | Amount precision exceeds the allowed range | Batch payout | Check amount precision | | 550238 | Too many sub-orders | Batch payout | Check the number of sub-orders | | 550239 | amount is missing | Batch payout | Provide the amount field | | 550240 | currency is missing | Batch payout | Provide the currency field | | 550241 | address is missing | Batch payout | Provide the address field | | 550242 | chain is missing | Batch payout | Provide the chain field | | 550245 | batch_id already exists | Batch payout | Use a new batch_id or handle as idempotent | | 550249 | Invalid batch_id or withdraw_order_id | Batch payout | Check field format | *** ## Funds Ledger Query Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 5504060 | Invalid orderType parameter (1=merchant order number, 2=GatePay order number, 3=funds ledger number) | Funds ledger query | Correct the orderType parameter | | 5504061 | Query size exceeds the limit (≤ 500) | Funds ledger query | Reduce the number of records requested per call | *** ## QR Payment Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 400000 | Invalid request format | QR payment | Check request data format | | 400002 | Signature verification failed | QR payment | Check whether the merchant signature is correct. See [Authentication and Security](/eu/essentials/version/100/en/common/authentication) | | 400003 | Request timestamp expired | QR payment | Check the timestamp header | | 400007 | Unsupported media type | QR payment | Check the API Content-Type | | 400603 | Order timed out | QR payment | Confirm whether the order has expired | | 400621 | Incorrect payment amount | QR payment | Check the requested amount | | 400620 | Duplicate payment order | QR payment | Check whether the merchant order number was submitted repeatedly | | 500008 | Merchant not found | QR payment | Check whether the merchant ID is correct | | 500100 | Payment QR code has expired | QR payment | Create a new order to generate a new QR code | | 500101 | Duplicate QR payment | QR payment | Verify the order status | *** ## Web Payment Error Codes | Error Code | Description | Applicable API | Handling | | - | - | - | - | | 300000 | System error | Web payment | Retry with the same parameters | | 300001 | System error | Web payment | Retry with the same parameters | | 400000 | Unknown error | Web payment | Record the request, retry, or contact support | | 400001 | Invalid request parameter format | Web payment | Check the request parameters and data format | | 400002 | Signature verification failed | Web payment | Check whether the merchant signature is correct. See [Authentication and Security](/eu/essentials/version/100/en/common/authentication) | *** ## Best Practices ### Callback and Query Fallback Strategy Use a "callbacks first, query as fallback" confirmation model for reliable order status management: **Recommended approach:** 1. **Rely on callbacks** as the primary notification mechanism (see [Notifications and Callbacks](/eu/essentials/version/100/en/common/notification) for integration details) 2. **Implement signature verification** before processing any callback (see [Authentication and Security](/eu/essentials/version/100/en/common/authentication)) 3. **Use idempotency** to handle duplicate callbacks safely 4. **Store notifications durably** before processing 5. **Implement state-machine control** for callback processing **Fallback Query Strategy:** If callbacks are missing or delayed, use progressive backoff for status queries: * 5 seconds * 10 seconds * 30 seconds * 1 minute * 3 minutes * 5 minutes This strategy prevents overwhelming the API while ensuring timely order confirmation. ### Refund Confirmation Refunds are asynchronous operations. A successful refund API response indicates only that the request has been accepted; it does not confirm the refund was actually processed. **Required practice:** * Confirm final refund results through the refund query API or refund callback (see [Refund Notify](/eu/api-reference/version/100/en/endpoint/callpayment/refundNotify) for refund callback details) * Use the "callbacks first, query as fallback" pattern to verify refund completion * Never consider a refund complete based solely on the API response ### Security Best Practices **Authentication and Signature Verification** * Always verify callback signatures before processing (see [Authentication and Security](/eu/essentials/version/100/en/common/authentication)) * Never return `SUCCESS` in a callback response if signature verification fails * Check the request timestamp to prevent replay attacks **Key Management** * Do not expose server-side signing keys or credentials in client applications * Store merchant secrets securely using environment variables or secure vaults * Rotate signing keys periodically and maintain separate keys for test and production environments **Request Validation** * Validate all request parameters before processing * Check Content-Type headers and ensure they match API requirements * Use HTTPS with TLS 1.2+ for all API communications *** ## Related Documentation * [Reward Distribution](/eu/api-reference/version/100/en/endpoint/withdraw/reward-distribution/create) — Payout error codes and handling * [Notifications and Callbacks](/eu/essentials/version/100/en/common/notification) — Callback integration patterns * [Authentication and Security](/eu/essentials/version/100/en/common/authentication) — Signature verification and security practices # Notification Source: https://docs.gate.com/eu/essentials/version/100/en/common/notification GatePay sends asynchronous notifications to your configured callback URL whenever order status changes. This guide covers the notification structure, callback types, and integration best practices. ## Processing Requirements For every callback received, you must: 1. **Verify the signature first** — See [Authentication and Security](/eu/essentials/version/100/en/common/authentication) for signature verification details 2. **Parse the business data** and perform idempotent processing 3. **Return the agreed success response** Since the same business event may be delivered more than once, you must implement idempotency using a business-unique identifier. ## Recommended Processing Order To reduce the risk of duplicate processing, premature final-state decisions, or incorrect fund posting, process callbacks in the following order: 1. Validate headers and verify the signature 2. Parse `bizType`, `bizId`, and `bizStatus` 3. Run idempotency checks on the business-unique identifier 4. Update local business state 5. Return the success response 6. Use query APIs for final confirmation on critical fund events For payment, refund, reward-distribution, and other fund-related flows, callbacks should usually be treated as the primary event source, while final confirmation for critical outcomes should still be verified through the relevant query APIs. ## Trigger and Retry Mechanism **Trigger** When the order status changes (payment success, timeout, cancellation, closure, or exception), GatePay sends a notification to your configured callback URL. **Retry** If you do not return the agreed success response or the request times out, GatePay will retry the callback. **Signature Verification** You must verify all callback signatures before processing. See [Authentication and Security](/eu/essentials/version/100/en/common/authentication) for details. ## Callback Message Structure All callbacks contain the following top-level fields: | Field | Type | Description | | - | - | - | | bizType | string | Notification category | | bizId | string | Order ID or business ID | | bizStatus | string | Business status (varies by bizType) | | client_id | string | Merchant client_id | | data | string | Business payload as a JSON string; call `JSON.parse` before use. Structure varies by `bizType` — see each notification subpage. | **Example Callback:** ```json theme={null} { "bizType": "PAY", "bizId": "6948484859590", "bizStatus": "PAY_SUCCESS", "client_id": "cdhu-fgrfg44-5ggd-cdvsa", "data": "{\"merchantTradeNo\":\"M202603120001\",\"orderAmount\":\"100.00\"}" } ``` ## Callback Acknowledgement Response Return the following JSON response with HTTP 200: ```json theme={null} { "returnCode": "SUCCESS", "returnMessage": "" } ``` HTTP 200 status is recommended to indicate successful receipt. # Overview Source: https://docs.gate.com/eu/essentials/version/100/en/common/overview This guide introduces the prerequisites, base configuration, service endpoints, app creation, key management, and supported payment networks and currencies for GatePay external APIs. ## Recommended Reading Order If this is your first integration, the recommended reading order is: 1. [Quickstart](/eu/essentials/version/100/en/common/quickstart) 2. [Merchant Access](/eu/essentials/version/100/en/common/accessguide) 3. [Authentication](/eu/essentials/version/100/en/common/authentication) 4. [Notification](/eu/essentials/version/100/en/common/notification) 5. The guide and API Reference for your target product flow ## Merchant Onboarding and App Configuration ### Base URL | Component | Value | | - | - | | Service Base URL | `https://openplatform-eu.gateapi.io` | All API paths in this documentation must be combined with the base URL to form the full request URL. ### Create and Configure an App Follow these steps to set up your application in the GatePay Merchant Portal: | Step | Action | | - | - | | 1 | Log in to the GatePay Merchant Portal and complete merchant registration and initial setup. | | 2 | Fill in the required business information and submit your merchant application. | | 3 | Navigate to the app configuration page and create or configure a new application. | | 4 | Retrieve your `ClientId` from the application list. | | 5 | Configure the callback URL as needed to receive asynchronous notifications. | ### Configuration Credentials After completing app configuration, you will receive the following credentials: | Credential | Description | | - | - | | `ClientId` | Unique identifier for your application. Used in all API requests via the `X-GatePay-Certificate-ClientId` header (see [Authentication and Security](/eu/essentials/version/100/en/common/authentication) for details). | | Payment API Secret | Server-side signing key for payment-related API requests and signature verification. | | Authorization Secret | Server-side signing key for authorization API requests and signature verification (used only by authorization APIs). | | Callback URL | Endpoint configured to receive asynchronous payment notifications. | **Important:** Any API that uses asynchronous notifications requires a valid callback URL to be configured; otherwise, notifications cannot be delivered. For details on how to verify incoming callbacks, see [Authentication and Security](/eu/essentials/version/100/en/common/authentication). ### Common Request Headers Requests commonly use the following headers: | Header | Description | | - | - | | `X-GatePay-Certificate-ClientId` | Application identity | | `X-GatePay-Timestamp` | UTC timestamp in milliseconds | | `X-GatePay-Nonce` | Random nonce | | `X-GatePay-Signature` | Request signature generated from the signing rules | For full header, signing, and verification details, refer to the [Authentication and Security](/eu/essentials/version/100/en/common/authentication) guide. ## Supported Currencies The EU site supports 35 currencies, including BTC, ETH, USDC, BNB, SOL, XRP, DOGE, ADA, TRX, and more. For the full list, see [Supported Currencies](/eu/api-reference/version/100/en/common/supportedCurrencies). ## Next Steps * If you want to run the first end-to-end flow quickly, start with [Quickstart](/eu/essentials/version/100/en/common/quickstart) * For authentication details and request signing, see [Authentication and Security](/eu/essentials/version/100/en/common/authentication) * For payment API integration, refer to your specific payment flow documentation * For error handling and best practices, consult the error codes and troubleshooting guide # Quickstart Source: https://docs.gate.com/eu/essentials/version/100/en/common/quickstart Run your first GatePay payment flow with the minimum path: signing, order creation, callback handling, and final query. ## Overview This page provides a minimum runnable path for merchants who want to complete their first GatePay payment flow from end to end. This document set focuses on the production integration flow. Before you begin integration, complete merchant onboarding, app creation, key setup, and callback URL configuration. If this is your first integration, use the following order: 1. Obtain `ClientId` and signing secrets 2. Generate the signed request headers 3. Create your first checkout order 4. Receive and verify the asynchronous callback 5. Use the query endpoint for final confirmation ## Step 1: Prepare Credentials After creating your application in the merchant console, prepare at least the following: | Credential | Purpose | | - | - | | `ClientId` | Sent through the `X-GatePay-Certificate-ClientId` header | | Payment API Secret | Used to sign payment-related requests | | Callback URL | Used to receive asynchronous notifications | If you have not completed this setup, see [Overview](/eu/essentials/version/100/en/common/overview) and [Authentication](/eu/essentials/version/100/en/common/authentication). ## Step 2: Build the Signed Headers At minimum, GatePay request signing uses these headers: * `X-GatePay-Certificate-ClientId` * `X-GatePay-Timestamp` * `X-GatePay-Nonce` * `X-GatePay-Signature` The core canonical string is: ```text theme={null} timestamp\nnonce\nbody\n ``` Integration recommendations: * use UTC milliseconds for `timestamp` * use a one-time random string for `nonce` * keep `body` exactly identical to the actual request payload * log the canonical string locally before signing during integration debugging ### Python signing example ```python theme={null} import hmac import hashlib timestamp = "1710000000000" nonce = "abc123xyz789" body = '{"merchantTradeNo":"M202604150001","currency":"USDC","orderAmount":"10.00"}' secret = "your_payment_api_secret" payload = f"{timestamp}\n{nonce}\n{body}\n" signature = hmac.new( secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha512, ).hexdigest() print(signature) ``` ### Node.js signing example ```javascript theme={null} const crypto = require("crypto"); const timestamp = "1710000000000"; const nonce = "abc123xyz789"; const body = '{"merchantTradeNo":"M202604150001","currency":"USDC","orderAmount":"10.00"}'; const secret = "your_payment_api_secret"; const payload = `${timestamp}\n${nonce}\n${body}\n`; const signature = crypto .createHmac("sha512", secret) .update(payload, "utf8") .digest("hex"); console.log(signature); ``` For the full signing rules, see [Security and Signature](/eu/api-reference/version/100/en/common/securityAndSignature). ## Step 3: Create Your First Payment Order The web payment (native pre-order) flow is the fastest way to validate signing, order creation, callback handling, and order querying. **Request** ```http theme={null} POST /v1/pay/transactions/native ``` **Minimum request example** ```bash theme={null} curl -X POST "https://openplatform-eu.gateapi.io/v1/pay/transactions/native" \ -H "Content-Type: application/json" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1710000000000" \ -H "X-GatePay-Nonce: abc123xyz789" \ -H "X-GatePay-Signature: generated_signature" \ -d '{ "merchantTradeNo": "M202604150001", "fiatCurrency": "EUR", "fiatAmount": "10.00", "goods": { "goodsName": "Demo Order", "goodsDetail": "First payment integration test" }, "callbackUrl": "https://merchant.example.com/webhook/gatepay", "returnUrl": "https://merchant.example.com/result" }' ``` Use only the standard GatePay signed headers for ordinary merchant requests. **Key response fields** | Field | Description | | - | - | | `prepayId` | GatePay pre-order ID used for later queries | | `location` | Payment page redirect URL | | `qrContent` | QR-content URL returned in some modes | After order creation, redirect the user with the returned `location` value directly. Do not construct the checkout page URL manually. ## Step 4: Receive the Callback After the user completes payment, GatePay sends an asynchronous callback to your configured callback URL. **Example callback** ```json theme={null} { "bizType": "PAY", "bizId": "6948484859590", "bizStatus": "PAY_SUCCESS", "client_id": "your_client_id", "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}" } ``` Your callback handler should at minimum: 1. verify the signature 2. apply idempotent business processing 3. update the local order state 4. return HTTP 200 with the agreed acknowledgement body For the unified callback model, see [Notification](/eu/essentials/version/100/en/common/notification). ## Step 5: Query for Final Confirmation For payment flows, the recommended operating model is callbacks first and query as fallback. **Request** ```http theme={null} POST /v1/pay/order/query ``` **Minimum query example** ```bash theme={null} curl -X POST "https://openplatform-eu.gateapi.io/v1/pay/order/query" \ -H "Content-Type: application/json" \ -H "X-GatePay-Certificate-ClientId: your_client_id" \ -H "X-GatePay-Timestamp: 1710000005000" \ -H "X-GatePay-Nonce: query123" \ -H "X-GatePay-Signature: generated_signature" \ -d '{ "merchantTradeNo": "M202604150001" }' ``` Treat these as two different integration signals: * callbacks for real-time business progression * queries for final confirmation and reconciliation ## Pre-Go-Live Checklist * `ClientId`, secret, and callback URL are confirmed * request signing and callback verification are implemented server-side * `merchantTradeNo` and `prepayId` are persisted * callback idempotency is implemented * query endpoints are integrated as fallback * monitoring and failure alerting are in place # Convert Source: https://docs.gate.com/eu/essentials/version/100/en/internalflow/swap Currency conversion enables merchants to exchange currencies directly using balances in their payment accounts. This capability is essential for multi-currency operations and balance management. ## Overview The convert service supports the following scenarios: * **Post-collection conversion**: Convert received payments to settlement currency * **Unified settlement currency**: Maintain accounts in a single currency * **Balance rebalancing**: Optimize currency distribution across accounts For request headers, signature rules, and callback verification, refer to [Authentication & Security](/eu/essentials/version/100/en/common/authentication). ## Integration Flow The standard convert workflow follows these steps: ``` Query tradable scope → Get quote → Create swap order → Query result ``` Each step is described in detail below. ### Step 1: Query Tradable Currency Scope (Optional) **Endpoint:** `GET /v1/pay/convert/currency` Retrieves the list of currencies available for conversion. This step is optional but recommended for user interface initialization and validation. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `side` | string | No | Filter by `buy` or `sell` direction | #### Response Fields The response includes available currencies with precision and amount constraints: * `minBuyAmount`: Minimum buy amount (field precision rules apply) * `maxBuyAmount`: Maximum buy amount (field precision rules apply) * `minSellAmount`: Minimum sell amount (field precision rules apply) * `maxSellAmount`: Maximum sell amount (field precision rules apply) *** ### Step 2: Query Available Currency Pairs (Optional) **Endpoint:** `GET /v1/pay/convert/pair` Retrieves supported trading pairs and exchange rate information. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `currency` | string | No | Filter pairs by base currency | | `side` | string | No | Filter by `buy` or `sell` direction | *** ### Step 3: Get Quote **Endpoint:** `POST /v1/pay/convert/preview` Generates a quote for currency conversion. The quote includes an expiration timestamp; expired quotes cannot be used for order creation. #### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `buyCurrency` | string | Yes | Target currency to buy | | `sellCurrency` | string | Yes | Source currency to sell | | `buyAmount` | string | Conditional | Amount to buy (mutually exclusive with `sellAmount`) | | `sellAmount` | string | Conditional | Amount to sell (mutually exclusive with `buyAmount`) | **Note:** Provide either `buyAmount` or `sellAmount`, but not both. #### Response Fields | Field | Type | Description | | - | - | - | | `quoteId` | string | Unique quote identifier; required for order creation | | `exchangeRate` | string | Current exchange rate | | `buyAmount` | string | Amount in target currency | | `sellAmount` | string | Amount in source currency | | `expirationTime` | timestamp | Quote expiration timestamp | *** ### Step 4: Create Convert Order **Endpoint:** `POST /v1/pay/convert` Creates a currency conversion order using a valid quote. This endpoint is idempotent: submitting the same `clientReqId` multiple times will return the same business result. #### Request Parameters | Field | Type | Required | Description | | - | - | - | - | | `quoteId` | string | Yes | Quote ID from Step 3 | | `buyCurrency` | string | Yes | Target currency | | `sellCurrency` | string | Yes | Source currency | | `buyAmount` | string | Yes | Amount to buy | | `sellAmount` | string | Yes | Amount to sell | | `clientReqId` | string | Yes | Merchant-generated unique request ID for idempotency | #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | Platform order number for queries | | `clientReqId` | string | Echoed from request | | `status` | string | Initial order status (typically `processing`) | | `buyAmount` | string | Final buy amount | | `sellAmount` | string | Final sell amount | #### Example Request ```json theme={null} { "quoteId": "QUOTE_abc123", "buyCurrency": "BTC", "sellCurrency": "USDC", "buyAmount": "0.5", "sellAmount": "21500", "clientReqId": "SWAP_20240101_001" } ``` *** ### Step 5: Query Convert Order **Endpoint:** `GET /v1/pay/convert/order` Queries the status and details of a swap order. Supports multiple query keys for flexibility. #### Query Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `orderId` | string | Conditional | Platform order number | | `clientReqId` | string | Conditional | Merchant-generated request ID | **Note:** Provide either `orderId` or `clientReqId` (not both required, but at least one). #### Response Fields | Field | Type | Description | | - | - | - | | `orderId` | string | Platform order number | | `clientReqId` | string | Merchant request ID | | `status` | string | Order status (see enumeration below) | | `buyCurrency` | string | Target currency | | `sellCurrency` | string | Source currency | | `buyAmount` | string | Final buy amount | | `sellAmount` | string | Final sell amount | | `completionTime` | timestamp | Order completion timestamp | *** ## Convert Order Status Enumeration | Status | Description | | - | - | | `processing` | Order is being processed; check back later | | `success` | Conversion completed successfully; funds are now in the account | | `failure` | Conversion failed; funds returned to original account | ## Retry and Error Handling ### Handling Uncertain Responses If a network timeout or uncertain response occurs: 1. **Query first**: Use `GET /v1/pay/convert/order` with `clientReqId` or `orderId` to determine final status 2. **Only retry if necessary**: Only reuse the same `clientReqId` for order creation if the query result remains uncertain 3. **Preserve idempotency**: Keep `clientReqId` unchanged to ensure the same business result ### Common Failure Scenarios | Failure Reason | Description | Resolution | | - | - | - | | Insufficient balance | Account does not have enough funds in sell currency | Fund the account or reduce sell amount | | Unsupported trading pair | Currency pair is not available | Use a different currency pair | | Expired quote | Quote lifetime has elapsed | Generate a new quote using `POST /v1/pay/convert/preview` | | Invalid quantity precision | Amount does not match currency precision rules | Adjust amount to match precision requirements | | Amount limit exceeded | Amount exceeds currency limits | Review limits via `GET /v1/pay/convert/currency` | ## Callback Behavior The convert capability does not provide asynchronous callbacks. Final order confirmation must be obtained through the query API (`GET /v1/pay/convert/order`). For information on callbacks for other products, see [Notification & Callbacks](/eu/essentials/version/100/en/common/notification). ## Error Handling For comprehensive error codes and resolution steps, refer to [Error Codes & Best Practices](/eu/essentials/version/100/en/common/error). ## Integration Checklist * [ ] Retrieve available currency pairs from `GET /v1/pay/convert/pair` * [ ] Implement quote retrieval with expiration handling * [ ] Generate unique `clientReqId` for each swap request * [ ] Create swap orders with valid quotes * [ ] Implement query fallback for order confirmation * [ ] Handle all failure scenarios gracefully * [ ] Store order IDs for reconciliation * [ ] Monitor conversion rates and limits ## Related Documentation * [Authentication & Security](/eu/essentials/version/100/en/common/authentication) * [Account Queries and Reconciliation](/eu/essentials/version/100/en/common/balance) * [Error Codes & Best Practices](/eu/essentials/version/100/en/common/error) * [General Overview](/eu/essentials/version/100/en/common/overview)