API endpoints and setup instructions for configuring webhooks.
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
When do these events occur?
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
When do these events occur?
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. |
Compliance & Refund Events
When do these events occur?
You’ll receive these updates when there’s a change in compliance (KYT) status or when a deposit refund is being processed.
| Event / Transaction Status | Description |
|---|---|
crypto_payment_kyt_status_updated | The KYT status for a deposit/payout has been updated. This event signifies a change in the compliance assessment of the incoming/outgoing transaction. Further details are usually available within the webhook payload. |
crypto_refund_status_updated | The status of a refund initiated for a deposit has been updated. This indicates the progress or completion of returning funds related to a deposit back to the payer. Further details are usually available within the webhook payload. |