Disclaimer: This article contains AI translations and should only be used as reference. Contact Cobo’s support team through [email protected] if you have any questions.
Webhook Events
1. Pay-in Related
| Scenario | Event Name | Trigger Condition | Event Content |
|---|---|---|---|
| Order Mode | payment.order.status.updated | Triggered when a payment order status changes. Key nodes include: - Pending: Triggered only when an order is successfully created via a payment link.- Completed: Full payment received within the order validity period.- Expired: No completed deposit transactions within the validity period, or the order was canceled.- Underpaid: Completed deposit transactions exist, but the total amount received is less than the expected amount. | Please refer to the response parameters in Get pay-in order information. |
| Order Mode | payment.transaction.late | A deposit transaction that passed compliance scanning is received after the payment order has reached a final state (Underpaid, Expired, or Completed). | This data structure includes all fields from the Get transaction information response, plus: - acquiring_type: Collection type. Order indicates Order Mode.- order_id: Payment order ID.- psp_order_code: The unique identifier for the order in your system. |
| Top-up Mode | payment.transaction.created | A new deposit transaction is detected on a deposit address. | This data structure includes all fields from the Get transaction information response, plus: - acquiring_type: Collection type. TopUp indicates Top-up Mode.- payer_id: Unique identifier assigned by Cobo to track the payer.- custom_payer_id: Unique identifier in your system to track the payer. |
| Top-up Mode/Order Mode | payment.transaction.completed | In Top-up Mode, once a collection transaction passes the compliance screening, the funds will be successfully credited and recorded in the Actual Receipt amount. In Order Mode, for every transaction received within the order’s validity period, the funds will be successfully credited and recorded in the Actual Receipt amount upon passing the compliance screening. | Same as above |
| Unexpected Deposit | payment.transaction.external.created | An unexpected deposit transaction is detected (e.g., transactions not within current orders/deposit plans, or deposits in unsupported tokens). | This data structure includes all fields from the Get transaction information response. |
| Unexpected Deposit | payment.transaction.external.completed | The unexpected deposit transaction passed compliance scanning and has been successfully credited to the developer balance. | Same as above |
| Pay-in Check | payment.transaction.failed | The collection transaction failed the compliance screening. | This data structure includes all fields from the Get transaction information response, plus: - acquiring_type: Collection type. Order for Order Mode, TopUp for Top-up Mode.- order_id: Payment order ID.- psp_order_code: Unique identifier in your system.- payer_id: Unique identifier assigned by Cobo.- custom_payer_id: Unique identifier in your system. |
2. Pay-out Related
| Scenario | Event Name | Trigger Condition | Event Content |
|---|---|---|---|
| Refund | payment.refund.status.updated | Triggered when a refund order status changes. Key nodes include: - Pending: Triggered only when a refund order is successfully created via a refund link.- Completed: All refund transactions are completed.- PartiallyCompleted: Some refund transactions completed, while others failed.- Failed: All refund transactions failed. | Please refer to the response parameters in Get refund order information. |
| Single-Destination Payout/Transfer | payment.settlement.status.updated(To be deprecated) | Triggered when a payout/transfer request status changes: - Completed: All payouts/transfers completed.- PartiallyCompleted: Some completed, some failed.- Failed: All failed. | Please refer to the response parameters in Get settlement request information. |
| Single-Destination Payout/Transfer | payment.payout.status.updated | Triggered when a payout/transfer request status changes: - Completed: All payouts/transfers completed.- PartiallyCompleted: Some completed, some failed.- Failed: All failed. | Please refer to the response parameters in Get payout information. |
| Bulk Send (Crypto) | payment.bulk_send.status.updated | Triggered when a bulk send request status changes: - Completed: All sends completed.- PartiallyCompleted: Some completed, some failed.- Failed: All failed. | Please refer to the response parameters in Get bulk send information. |
Tips
To ensure absolute data accuracy and avoid concurrency conflicts, the Webhook payload does not include real-time balance changes or detailed fee deductions. If your use case requires this information, please refer to the following:- To update balances promptly based on Webhook notifications: Upon receiving a Webhook, immediately call the List merchant balances or Get developer balances endpoint to obtain the accurate balance for internal accounting.
- To obtain fee details associated with a transaction for reconciliation: Use the corresponding transaction query endpoints or Generate reports to retrieve fee reports for data verification.
- To monitor Fee Station balance changes and prevent business disruption: Periodically call List Fee Station token balance and set up internal alerting based on your consumption rate to avoid service interruptions due to insufficient fees.