Frequently Asked Questions
Order Amount Limits
1. Minimum Amount Limit:
Gate Payment: 0.0001 (all currency units)
Web3 On-Chain Payment: 0.01 USDT (or equivalent in other currencies)
Minimum Flash Exchange Amount: The currency pair query API will return the maximum and minimum values.
The order amount must not be lower than the set minimum amount. For example, if the minimum amount limit is 0.0001, the order amount must be ≥ 0.0001, such as 0.0001, 0.00011, etc.
2. Precision Limit:
The number of decimal places in the order amount must not exceed the set precision. For example, if the precision is set to 0.0001 (i.e., up to 4 decimal places), 0.001 is valid, but 0.00011 will result in an error and will not be rounded.
The order amount must meet both the minimum amount and precision requirements, otherwise, it cannot be submitted. For example, if the minimum amount is 0.0001 and the precision limit is 0.1, 0.01 would still not meet the precision requirement and will result in an error.
Withdrawal Fee Description
Withdrawal Fee API
https://www.gate.com/docs/gatepay/withdraw/en/#_3-5-query-withdrawal-fee
Description
Calling the “Withdrawal Fee Query” API will return the fees required for each blockchain network supported by the currency. Users can choose the appropriate chain based on their needs.
Please refer to the following two parameters:
Fee Parameters
- withdraw_fix_on_chains : Fixed withdrawal fee
- withdraw_percent_on_chains : Percentage-based withdrawal fee
(For some special currencies, the withdrawal fee is calculated as withdrawal amount × this percentage )
Calculation Method
The withdrawal fee is the sum of the following two parts:
Fixed fee + (percentage rate × withdrawal amount)
Other Notes
Currently, most commonly used chains only charge a fixed fee
(the fixed fee is updated hourly).
It is recommended to call this API each time you make a withdrawal to confirm the latest fee, as withdrawal fees are updated every hour.
Why is a payment made within the validity period marked as an expired order?
The payment time is determined based on when the transaction is detected on-chain, not when the user initiated the payment. A delay can occur between these two times.
Why the Billing Income and Expense Records Are Inconsistent Between the Gate App and the Merchant Dashboard
The billing information displayed in the Gate Pay merchant dashboard corresponds to the merchant balance account
(this account is only available to merchants registered with Gate Pay). It is mainly used for merchant fund collection and fund disbursement operations.
The Gate App, on the other hand, is a personal account on the Gate exchange.
Since the merchant balance account and the personal account are independent of each other, funds and billing records are not shared between them. Therefore, the billing information shown in the Gate App or on the Web platform may differ from the actual acquiring (collection) records.
Meaning of merchantTradeNo and merchantUserId in the Create Order API
- merchantTradeNo: The order number in the merchant’s system, with a maximum length of 32 characters.
- merchantUserId: The user account ID in the merchant’s system. This must be a valid user ID; otherwise, payment-related refunds to the address will fail as the system cannot identify the user.
Callback Information for On-chain Address Payments
Why Are There Two Callback Notifications for Payments?
- Fund Arrival Notification (TRANSFER_ADDRESS): A notification about the fund received.
- Order Status Change Notification (PAY_ADDRESS): A notification about changes in the order status.
Merchants need to rely on these two types of information to determine whether the order is successful to proceed with shipping or handle failed orders.
When Are Callback Notifications Sent?
- Fund Arrival Notification
Sent after the payment is confirmed on-chain, allowing the funds to be credited to the merchant’s account in real-time while notifying the merchant. - Order Status Change Notification
Triggered when the order status changes.
Understanding Callback Status
1. Fund Arrival Notification (biztype = TRANSFER_ADDRESS)
- TRANSFERRED_ADDRESS_IN_TERM: Funds are credited in real-time within the order’s validity period.
- TRANSFERRED_ADDRESS_DELAY: Funds received after the validity period are credited to the merchant’s payment account (post-validity period real-time credit).
- TRANSFERRED_ADDRESS_BLOCK: The transaction has potential security risk and is rejected. Please contact Gate Pay for assistance in refunding the payment.
2. Order Status Change Notification (biztype = PAY_ADDRESS)
- PAY_SUCCESS: Payment was successful.
- PAY_CLOSE: The order has expired.
- PAY_EXPIRED_IN_PROCESS: Awaiting on-chain confirmation of funds.
Payment Scenarios and Order Status Determination for On-chain Address Payments
1. Full or Overpayment within the Validity Period
Description : If a user pays the full or more than the required amount within the validity period, once confirmed on-chain, both callbacks are triggered.
Order Status Notification :
- Initially: bizStatus = PAY_EXPIRED_IN_PROCESS
- After confirmation: bizStatus = PAY_SUCCESS, doneAmountOnChain included.
Fund Arrival Notification : bizStatus = TRANSFERRED_ADDRESS_IN_TERM, credited amount = transferAmount.
2. Partial Payment within the Validity Period
Description : User pays less than the order amount within the validity period. Once confirmed on-chain, the amount is credited and a fund arrival notification is sent.
Order Status Notification : Not triggered.
Fund Arrival Notification : bizStatus = TRANSFERRED_ADDRESS_IN_TERM, amount = transferAmount.
3. Partial Payment without Supplement
Description : Partial payment is made, but no further amount is added before expiry.
Order Status Notification : Sent upon order expiry: bizStatus = PAY_CLOSE, amount = doneAmountOnChain.
Fund Arrival Notification : Already sent earlier when funds arrived. No repeat callback.
4. Partial Payment with Supplement
4.1Supplemented Within Validity Period
Order Status Notification :
- Upon supplement: bizStatus = PAY_EXPIRED_IN_PROCESS
- After confirmation: bizStatus = PAY_SUCCESS, doneAmountOnChain reflects the total received.
Fund Arrival Notification : Sent only after confirmation: bizStatus = TRANSFERRED_ADDRESS_IN_TERM, amount = transferAmount.
4.2 Supplemented After Validity Period
Order Status Notification :
- On expiry: bizStatus = PAY_CLOSE, amount = doneAmountOnChain.
- No additional order status notification after late supplement.
Fund Arrival Notification :
- Upon late supplement: bizStatus = TRANSFERRED_ADDRESS_DELAY, amount = transferAmount.
- doneAmountOnChain will not be included. Merchants need to aggregate multiple transferAmount values manually.
5. Payment Made After Expiry
Description : The user pays after the order has expired, regardless of the amount.
Order Status Notification : On expiry: bizStatus = PAY_CLOSE.
Fund Arrival Notification :Upon late payment: bizStatus = TRANSFERRED_ADDRESS_DELAY, amount = transferAmount. No doneAmountOnChain and no order status callback for post-expiry payments. Merchants must sum all received transferAmount values.
The merchant should determine the success of an order based on both the order status and the fund arrival callback notifications.
