Gate Pay FAQ

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 Explanation

API for Checking Withdrawal Status

https://www.gate.com/docs/developers/apiv4/en/#retrieve-withdrawal-status

Description

The "Check Withdrawal Status" API allows users to retrieve withdrawal fee information for different tokens across supported chains. Users can select the chain as needed.

Fee Parameters

withdraw_fix_on_chains: Fixed withdrawal fee

withdraw_percent_on_chains: Percentage-based withdrawal fee (applicable to certain special tokens, calculated as Withdrawal Amount × Percentage Rate)

Calculation Formula

Withdrawal Fee = Fixed Fee + (Percentage Fee Rate × Withdrawal Amount)

Additional Notes

Most commonly used chains only charge a fixed withdrawal fee, which updates every hour.

Please Make an API request before each withdrawal to obtain the latest fee data and ensure accurate calculations.

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 do the bills shown on the Gate app or web differ from the actual payment received?

The app or web displays the order amount, not the actual amount paid by the user. Even if the user’s payment differs from the order amount, the order amount will still be displayed. For detailed billing, always refer to the merchant backend.

Meaning of merchantTradeNo and merchantUserId in the Create Order API

1. merchantTradeNo: The order number in the merchant’s system, with a maximum length of 32 characters.
2. 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?

1. Fund Arrival Notification (TRANSFER_ADDRESS): A notification about the fund received.
2. 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?

1. 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.
2. 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.