We use webhooks to provide you 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.

Pay-In Status Events

You’ll receive these statuses as your customer completes a deposit, from initiation to final credit. These statuses apply to both Rapid Deposit and Invoice deposit types.

Transaction Status	Description
`initiated`	The deposit invoice has been created and is awaiting the payer's cryptocurrency transfer. This is the first status that appears on the transaction.
`pending`	The funds have been sent but there is at least one blockchain confirmation that is not in a final state (complete/failed).
`paid`	The deposit has received sufficient blockchain confirmations and the invoiced amount was paid accurately. For merchants not using an FX contract, this indicates the funds have been received in the original cryptocurrency.
`confirmed`	The deposit has been fully confirmed on the blockchain. For fiat-target deposits, conversion is typically in progress or completed. This can also appear if a deposit is made after an invoice has expired for merchants not using an FX contract.
`credited`	The deposited funds have been successfully converted (if applicable) and credited to your merchant balance. For merchants using an FX contract, this confirms the funds are available in their fiat account.
`underpaid`	The payer sent an amount less than the required invoice amount. This applies regardless of whether an FX contract is used. Funds are typically held pending resolution.
`overpaid`	The payer sent an amount greater than the required invoice amount. This applies regardless of whether an FX contract is used. Funds are typically held pending resolution.
`awaiting_underpaid_refund`	The deposit was underpaid, and a refund for the partial amount is being processed.
`refunded`	The deposit (either full or partial) has been successfully refunded to the payer.
`expired`	The deposit invoice has expired without sufficient funds being received.
`failed`	The deposit failed due to blockchain failures, KYT, or another unexpected reason. Funds will be returned to the user if they were sent.
`info_required`	The deposit is on hold pending additional information from the user, often related to Travel Rule requirements.

Pay-In Status Webhook Example

{
  "event": "crypto_payment_status_updated",
  "externalId": "12345-USDT-67240287-67",
  "id": "312abe61-d106-40ec-b4e2-e95607e9706d",
  "status": "pending",
  "type": "deposit",
  "updatedAt": "2025-08-29T11:56:11.908Z"
}

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`	When an end-user initiates a withdrawal, this is the first status that appears on the transaction.
`pending`	The funds have been sent but there is at least one blockchain confirmation that is not in a final state (complete/failed).
`debited`	This status is only relevant for merchants who have chosen to include an FX contract. Their fiat account has been debited for the pay out funds on the Orbital platform.
`confirmed`	The pay out funds have at least one blockchain confirmation in a complete state.
`failed`	The pay out has failed due to low balance or KYT. In a latter case, funds will be returned to the merchant.

Payout Status Webhook Example

{
  "event": "crypto_payment_status_updated",
  "externalId": "26Whu4566R40X7VG2L32RT",
  "id": "2222d525-f5a4-4119-ab6f-4e6c398b3896",
  "status": "initiated",
  "type": "payout",
  "updatedAt": "2025-08-29T11:59:54.014Z"
}

KYT (Know Your Transaction) Events

Orbital performs a KYT (Know Your Transaction) check on both pay-ins and pay-outs for all integration types. You will receive a webhook containing two key fields: kytStatus and kytAlertLevel.

KYT Status

This field indicates the review status of the transaction.

KYT Status	Description
`no_review`	The transaction has passed initial automated checks and does not require manual review.
`in_review`	The transaction is currently under manual review by the compliance team.
`dismissed`	A potential issue was reviewed and dismissed. The transaction can proceed.
`flagged`	The transaction has been flagged for a potential issue and requires further investigation.
`held`	The transaction is temporarily on hold pending the outcome of a review.
`refunded`	The transaction has been refunded due to a KYT compliance issue.

KYT Alert Level

This field indicates the associated risk level of the transaction.

KYT Alert Level	Description
`unknown`	There is not enough data to categorize the transaction risk.
`low`	The transaction risk is low.
`medium`	The transaction risk is medium.
`high`	The transaction risk is high.
`severe`	The transaction risk is severe.

KYT Webhook Examples

KYT Update for a Deposit

{
  "event": "crypto_payment_kyt_status_updated",
  "externalId": "M133455-USDT-67240287-556",
  "id": "312ggabe61-d106-40ec-b4e2-e95607e9706d",
  "kytAlertLevel": "unknown",
  "kytStatus": "no_review",
  "type": "deposit",
  "updatedAt": "2025-08-29T11:57:39.399Z"
}

KYT Update for a Payout

{
  "event": "crypto_payment_kyt_status_updated",
  "externalId": "26WRghhuu40X7VG2L32RT",
  "id": "2222d5fff25-f5a4-4119-ab6f-4e6c398b3896",
  "kytAlertLevel": "unknown",
  "kytStatus": "no_review",
  "type": "payout",
  "updatedAt": "2025-08-29T12:00:55.318Z"
}

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 the API to provide the missing Travel Rule info within the allowed window. If not supplied in time, the 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; the user must create a new deposit.

Travel Rule Missing Info Webhook Example

{
  "id": "33be948f-7f87-450d-8e03-14f5948027f4",
  "externalId": "merchant-externalid-infoff-06-05-2025-002",
  "status": "info_required",
  "type": "deposit",
  "updatedAt": "2025-06-05T07:39:38.037Z",
  "event": "crypto_payment_status_updated"
}

Auto-Refund Webhook Example

{
  "id": "37ddcef4-7e83-43ed-a581-46f579a71437",
  "externalId": "incoming-channel-missing-tr-details-2025-06-16T19:21:40",
  "status": "refunded",
  "type": "deposit",
  "updatedAt": "2025-06-16T19:25:40.222Z",
  "event": "crypto_payment_status_updated"
}