We use webhooks to provide your system with real-time, asynchronous updates on the lifecycle of your crypto payments (deposits) and payouts. When a significant event or status change occurs, Orbital will send an automated HTTP POST request to the notifyUrl you configured in your API call. This allows your application to react instantly to payment statuses without the need for constant polling.
Webhook Event Types and Statuses
Each webhook notification includes an eventType field, indicating the type of event that occurred, and often a status field, detailing the current state of the associated transaction.
Deposit Status Events
You’ll receive these statuses as your customer completes a deposit, from initiation to final credit, including cases of overpayment, underpayment, refunds, or failures.
| Transaction Status | Description |
|---|---|
initiated | The deposit invoice has been created and is awaiting the payer's cryptocurrency transfer. |
pending | The deposit has been detected on the blockchain, but requires further confirmations or internal processing. Funds are not yet credited to your balance. |
paid | The deposit has received sufficient blockchain confirmations and has been successfully received by Orbital. Funds are available for conversion or will be credited shortly. |
confirmed | The deposit has been fully confirmed on the blockchain. For fiat-target deposits, conversion is typically in progress or completed. |
credited | The deposited funds have been successfully converted (if applicable) and credited to your merchant balance. |
underpaid | The payer sent an amount less than the required invoice amount. Funds are typically held pending resolution or refund. |
awaiting_underpaid_refund | The deposit was underpaid, and the system is awaiting confirmation that the underpaid amount has been returned to the payer. |
overpaid | The payer sent an amount greater than the required invoice amount. Funds are typically held pending resolution or refund. |
refunded | The deposit (either full or partial, often due to underpayment/overpayment or expiry) has been successfully refunded to the payer. |
expired | The deposit invoice has expired without sufficient funds being received. |
failed | The deposit failed for an unexpected reason (e.g., blockchain issue, internal error). |
Payout Status Events
You’ll receive these statuses as your payout request is processed, from creation through completion, or if it fails.
| Transaction Status | Description |
|---|---|
initiated | The payout request has been successfully received and validated by Orbital. |
pending | The payout is being processed internally or awaiting blockchain confirmation. Funds are typically debited from the merchant's balance at this stage. |
debited | The funds for the payout have been successfully debited from the merchant's balance. The transaction is typically being sent to the blockchain. |
confirmed | The payout transaction has received sufficient blockchain confirmations and has been successfully sent to the receiver's wallet. |
failed | The payout failed (e.g., invalid address, insufficient network fees, internal error). Funds will be returned to the merchant's balance if debited. |
Travel Rule Update & Auto Refund Events
You’ll receive these updates when you need to update Travel Rule info or when a deposit refund is being processed.
| Transaction Status | Description |
|---|---|
info_required | The payment is on hold. Use PUT /crypto/deposit/receiving-address/travel-rule/:addressExternalID to provide the missing Travel Rule info within the allowed window. If not supplied in time, payment is automatically refunded. |
refunded | The payment was automatically refunded to the original sender. Check the refund transaction in the API (GET /crypto/payment/:id). No retry is possible; user must create a new deposit. |