ONRAMP webhooks
Overview
ONRAMP webhooks notify the merchant system about fiat deposit order creation, confirmation, payment, expiration, and failure.
Use webhooks as the main way to update onramp order status in the merchant system. If you need to verify the current order state, use [POST] fiat/deposit/order.
Event types
| Event type | When it is sent |
|---|---|
| FIAT_DEPOSIT_ORDER_CREATED | Onramp order was created. |
| FIAT_DEPOSIT_ORDER_CONFIRM | Onramp order was confirmed and a payment link was issued. |
| FIAT_DEPOSIT_FIAT_FUNDS_RECEIVED | Customer fiat payment was received. |
| FIAT_DEPOSIT_ADJUSTMENT | Fiat deposit order amount or processing data was adjusted. |
| FIAT_DEPOSIT_ORDER_EXPIRED | Customer did not complete payment before the order expired. |
| FIAT_DEPOSIT_ORDER_FAILED | Onramp order payment or processing failed. |
Order state and webhook event names
The order state field and webhook eventType are related, but they are not identical.
Order state | Related webhook event |
|---|---|
| CREATED | FIAT_DEPOSIT_ORDER_CREATED |
| IN_PROGRESS | FIAT_DEPOSIT_ORDER_CONFIRM |
| PAID | FIAT_DEPOSIT_FIAT_FUNDS_RECEIVED |
| DEPOSIT_COMPLETED | Processing after fiat payment was completed. |
| EXTERNAL_WITHDRAWAL_IN_PROGRESS | External address withdrawal is in progress. |
| PAUSED | External address withdrawal requires attention. |
| COMPLETED | Final successful processing state. |
| FAILED | FIAT_DEPOSIT_ORDER_FAILED |
| EXPIRED | FIAT_DEPOSIT_ORDER_EXPIRED |
Webhook payload structure
Each webhook request contains a common envelope and an event-specific data object.
Common data fields
| Field | Type | Description |
|---|---|---|
| type | string | Event type. Usually matches eventType. |
| orderId | string | Calypso onramp order ID. |
| parentExternalId | string or number | System ID of the order. |
| idempotencyKey | string | External ID used during order creation. |
| externalId | string | Merchant-side order ID, if provided during order creation. |
| currency | string | Cryptocurrency received by the merchant. |
Amount and result fields
| Field | Type | Description |
|---|---|---|
| cryptoAmount | string or number | Cryptocurrency amount. |
| fiatCurrency | string | Fiat currency paid by the customer. |
| fiatAmount | string or number | Fiat amount. |
| reason | string | Failure reason, if included in the event. |
Webhook example
{
"requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
"id": 3,
"createdDate": "2026-06-29T12:13:05.909616",
"level": "SUCCESS",
"service": "FIAT_DEPOSIT",
"eventType": "FIAT_DEPOSIT_FIAT_FUNDS_RECEIVED",
"data": {
"type": "FIAT_DEPOSIT_FIAT_FUNDS_RECEIVED",
"orderId": "123e4567-e89b-12d3-a456-426614174003",
"externalId": "order-1001",
"idempotencyKey": "123e4567-e89b-12d3-a456-426614174002",
"fiatAmount": 100,
"fiatCurrency": "USD",
"cryptoAmount": 99.5,
"currency": "USDT_TRX"
}
}
Recommended handling
| Event | Recommended merchant action |
|---|---|
| FIAT_DEPOSIT_ORDER_CREATED | Save the order ID and merchant-side mapping. |
| FIAT_DEPOSIT_ORDER_CONFIRM | Redirect the customer to the payment page if it was not done yet. |
| FIAT_DEPOSIT_FIAT_FUNDS_RECEIVED | Mark fiat payment as received and wait for final processing state if needed. |
| FIAT_DEPOSIT_ADJUSTMENT | Update stored order amounts or processing data and verify the current state through [POST] fiat/deposit/order. |
| FIAT_DEPOSIT_ORDER_EXPIRED | Mark the order as expired and create a new order if payment is still required. |
| FIAT_DEPOSIT_ORDER_FAILED | Mark the order as failed and verify the current state through [POST] fiat/deposit/order. |
Related docs
| Document | Link |
|---|---|
| Create payment via ONRAMP | How to create a payment via ONRAMP |
| Webhook API reference | Webhook API |