Gate Pay Callback Notification API Documentation: https://docs.gate.com/api-reference/version/100/en/common/asyncNotification
Interpreting Payment Callback Status Information
Dynamic Address Type
1. Dynamic Address Payment Funds Arrival Notification (biztype = TRANSFER_ADDRESS)
TRANSFERRED_ADDRESS_IN_TERM: Funds are credited instantly within the order validity period.
TRANSFERRED_ADDRESS_DELAY: If payment is credited after the validity period, the actual paid amount will be credited to the merchant's balance account (instant credit after the validity period).
2. Dynamic Address Payment Order Status Change Notification (biztype = PAY_ADDRESS)
PAY_SUCCESS: Payment successful.
PAY_CLOSE: Order expired.
PAY_EXPIRED_IN_PROCESS: Awaiting on-chain fund confirmation.
Static Address Type
1. Static Address Payment Success (biztype=PAY_FIXED_ADDRESS)
PAY_SUCCESS: Payment successful and funds credited.
2. Static Address Marked as Risk Address (biztype=FIXED_ADDRESS_RISK)
RISK_ADDRESS: Static address has been flagged as a risk address.
Abnormal Address Payment Type
For each abnormal payment transaction, Gate Pay will send a webhook notification to the corresponding merchant.
The bizType for this payment type is always PAY_UNRESOLVED.
Merchants need to determine the billing issue based on the errorType in the data and refer to the Gate Pay Abnormal Payment Handling Guide or contact their Gate Pay account manager.
- address_risk_address
— High-risk dynamic address - address_error_currency
— Incorrect currency for dynamic address - address_error_chain
— Incorrect blockchain network for dynamic address - fix_error_currency
— Incorrect currency for static address - fix_error_chain
— Incorrect blockchain network for static address - fix_risk_address
— High-risk static address - fix_delete
— Static address deleted - fix_partial_delete
— Static address partially deleted
About Callback Information for Dynamic Address Payments
Why Are There Two Types of Payment Callback Information?
- Funds Arrival Notification (TRANSFER_ADDRESS): Notification of the actual credited amount.
- Order Status Change Notification (PAY_ADDRESS): Notification of changes in order status.
Merchants need to use both types of information to determine whether an order was successful, so they can proceed with delivery or handle failed orders.
When Are Callback Notifications Sent?
- Funds Arrival Notification: After on-chain confirmation of successful payment, funds are credited to the merchant in real time, and a callback is sent to the merchant.
- Order Status Change Notification: Triggered when the order status changes.
Dynamic Address Payment Scenarios and Order Status Determination
1. One-Time Full or Overpayment Within Validity Period
Description: As long as the user pays the full or excess amount within the order validity period, a callback is sent in real time after on-chain confirmation.
Order Status: Initially, the system waits for on-chain fund confirmation and sends a callback with an intermediate status: bizStatus is PAY_EXPIRED_IN_PROCESS. After on-chain confirmation, the order is successful, and a callback is sent with bizStatus as PAY_SUCCESS and the credited amount as doneAmountOnChain.
Funds Arrival Notification: bizStatus is TRANSFERRED_ADDRESS_IN_TERM, credited amount is transferAmount.
2. Underpayment Within Validity Period
Description: If the user pays less than the order amount within the validity period, after on-chain confirmation, the actual paid amount is credited to the merchant, and a funds arrival callback is sent in real time.
Order Status: Within the validity period, the order status does not change, and no order status callback is sent.
Funds Arrival Notification: bizStatus is TRANSFERRED_ADDRESS_IN_TERM, credited amount is transferAmount.
3. Underpayment Within Validity Period, Not Made Up
Description: If the user pays less than the order amount within the validity period and does not make up the difference during the validity period.
Order Status: When the order validity period ends, an order status callback is sent. bizStatus is PAY_CLOSE, credited amount is doneAmountOnChain.
Funds Arrival Notification: The funds arrival callback was already sent after payment, and will not be sent again.
4. Underpayment Within Validity Period, Then Made Up
4.1 Make-up Payment Within Validity Period:
After the user makes up the remaining amount:
Order Status: The system waits for on-chain fund confirmation and sends a callback with an intermediate status: bizStatus is PAY_EXPIRED_IN_PROCESS.
Funds Arrival Notification: No funds arrival notification is sent while waiting for on-chain confirmation of the make-up payment.
After On-Chain Confirmation:
Order Status: Once the on-chain funds are confirmed and the total amount is sufficient, the order is considered successful. bizStatus is PAY_SUCCESS, credited amount is doneAmountOnChain (the total of all payments).
Funds Arrival Notification: bizStatus is TRANSFERRED_ADDRESS_IN_TERM, credited amount is transferAmount.
4.2 Make-up Payment After Validity Period:
Order Status: Since the full amount was not paid within the validity period, an order status callback is sent when the validity period ends. bizStatus is PAY_CLOSE, credited amount is doneAmountOnChain.
Funds Arrival Notification: The funds arrival callback was already sent after payment, and will not be sent again.
If the user makes up the remaining amount after the validity period: a funds arrival callback is sent with bizStatus as TRANSFERRED_ADDRESS_DELAY, credited amount is transferAmount. (In this case, no additional order status callback is sent, and the final callback does not include the doneAmountOnChain field. If the user completes payment using multiple transactions, the merchant must sum all transferAmount values from the callbacks to confirm the total credited amount.)
5. Expired Payment
Description: If the user pays after the order validity period, whether partially, fully, or overpays, funds are credited in real time after on-chain confirmation.
Order Status Change: Since no payment was made during the validity period, a callback is sent with bizStatus as PAY_CLOSE when the validity period ends.
Funds Arrival: No funds arrival notification.
Payment After Expiry: After the expiry, for each payment made, a funds arrival notification is sent with bizStatus as TRANSFERRED_ADDRESS_DELAY, credited amount is transferAmount. (In this case, no additional order status callback is sent, and the final callback does not include the doneAmountOnChain field. If the user completes payment using multiple transactions, the merchant must sum all transferAmount values from the callbacks to confirm the total credited amount.)
Merchants need to use both order status and funds arrival callback information to determine if the order was successful.
6. Abnormal Order Callback Information for Dynamic Address Payments
6.1 Paid with a Different Currency or Blockchain Network than the Order
The merchant will receive a callback with Biztype=PAY_UNRESOLVED and data.errorType=address_error_currency or address_error_chain.
6.2 Funds Flagged as Risky and Intercepted
The merchant will receive a callback with biztype=PAY_UNRESOLVED and data.errorType=address_risk_address.
About Callback Information for Static Addresses
1. Successful Payment Credited
A PAY_SUCCESS notification will be received, indicating payment was successful and funds have been credited.
2. Abnormal Payment Callback
2.1 Paid with a Different Currency/Network than the Order
The merchant will receive a callback with biztype=PAY_UNRESOLVED and data.errorType=fix_error_currency or fix_error_chain.
2.2 Risky Funds
The merchant will receive a callback with biztype=PAY_UNRESOLVED and data.errorType=fix_risk_address.
2.3 Payment Sent to a Deleted Static Address
The merchant will receive a callback with biztype=PAY_UNRESOLVED and data.errorType=fix_delete or fix_partial_delete.
3. Static Address Risk Notification
A notification will be received with bizType=FIXED_ADDRESS_RISK and bizStatus=RISK_ADDRESS, indicating that the static receiving address bound to the merchant has been identified as a risk address. Merchants should immediately delete the corresponding static address. If users continue to make payments to this address, funds will not be credited.
Disclaimer
The content provided herein is for reference and educational purposes only and does not constitute any financial, investment, trading, or legal advice, nor does it constitute an offer or solicitation to buy or sell any digital assets. Gate makes no express or implied representations or warranties regarding the accuracy, completeness, or timeliness of the information contained herein. Product features, interfaces, rules, and fee structures may be updated or adjusted at any time. Please refer to the latest announcements and the actual information displayed on the Gate platform for the most accurate details.
Digital asset investments involve significant risk, and prices may fluctuate substantially. You may lose the entire amount of your investment. Please make decisions cautiously based on your own financial situation and risk tolerance after fully understanding the associated risks. If necessary, you are advised to consult an independent professional financial or legal advisor.
For more information about potential risks, please refer to Gate's Risk Disclosure and User Agreement.
