> ## Documentation Index
> Fetch the complete documentation index at: https://guides.saber.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Order lifecycle and Webhooks

> Documents the ONRAMP_COMPLETED, COMPLETED, and FAILED webhook events for the crypto buy flow, with order statuses and sample JSON payloads.

This page describes the webhook events and order statuses for the crypto buy (onramp) flow.

The webhook is emitted only for the three statuses below. Other order states (such as `CREATED`, `ONRAMP_INITIATED`, `ONRAMP_INCONSISTENT` and `REFUND_COMPLETED`) may be observed via the transaction-status API but are never sent as webhooks for the onramp flow.

| **Status**         | **Description**                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `ONRAMP_COMPLETED` | Triggered when the user’s payment is successfully reconciled and internal conversion completes. |
| `COMPLETED`        | Triggered when the crypto withdrawal to the client’s specified wallet address is completed.     |
| `FAILED`           | Triggered when the order fails, e.g. the user’s payment could not be found.                     |

## Sample Payloads

All payloads also include a top-level `uuid` field (string) that always equals `id`. It is retained for backward compatibility and is a deprecated duplicate of `id`.

`source_id`, `bank_transaction_id`, and `tag` are always present and are serialized as an empty string (`""`) when unset, never `null`. `txn_hash` is always present (top-level string); it is serialized as an empty string (`""`) until the outgoing crypto withdrawal has an on-chain hash, so it is `""` on `ONRAMP_COMPLETED` and `FAILED`, and is populated only on `COMPLETED`. `failure_code` and `failure_desc` are present only when the order fails; on success these keys are absent from the payload (not `null`).

### `ONRAMP_COMPLETED`

```json theme={null}
{
  "payment_method": "upi_transfer",
  "source_id": "",
  "tag": "",
  "exchange_rate": 84.99,
  "fiat_amount": 2299.00,
  "created_at": 1694714157000,
  "id": "xxxxxx",
  "uuid": "xxxxxx",
  "bank_transaction_id": "xxxxxx",
  "fiat_symbol": "INR",
  "crypto_symbol": "USDT",
  "network": "MATIC",
  "crypto_wallet_address": "0xXXXXXXXXXXXXX",
  "crypto_amount": 27.05,
  "status": "ONRAMP_COMPLETED",
  "event": "CRYPTO_BUY",
  "user_id": "xxxxxx",
  "txn_hash": ""
}
```

### `COMPLETED`

```json theme={null}
{
  "payment_method": "upi_transfer",
  "source_id": "",
  "tag": "",
  "exchange_rate": 84.99,
  "fiat_amount": 2299.00,
  "created_at": 1694714157000,
  "id": "xxxxxx",
  "uuid": "xxxxxx",
  "bank_transaction_id": "xxxxxx",
  "fiat_symbol": "INR",
  "crypto_symbol": "USDT",
  "network": "MATIC",
  "crypto_wallet_address": "0xXXXXXXXXXXXXX",
  "crypto_amount": 27.05,
  "status": "COMPLETED",
  "event": "CRYPTO_BUY",
  "user_id": "xxxxxx",
  "txn_hash": "0xXXXXXXXXXXXXX"
}
```

### `FAILED`

```json theme={null}
{
  "failure_code": "FIAT_PAYMENT_TIMED_OUT",
  "created_at": 1694631289000,
  "exchange_rate": 84.99,
  "fiat_amount": 300.00,
  "tag": "",
  "crypto_symbol": "USDT",
  "network": "MATIC",
  "source_id": "",
  "bank_transaction_id": "",
  "failure_desc": "Payment not received within time limit",
  "status": "FAILED",
  "fiat_symbol": "INR",
  "crypto_wallet_address": "0xXXXXXXXXXXXXX",
  "payment_method": "upi_transfer",
  "crypto_amount": 3.53,
  "id": "xxxxxx",
  "uuid": "xxxxxx",
  "event": "CRYPTO_BUY",
  "user_id": "xxxxxx",
  "txn_hash": ""
}
```


## Related topics

- [Order lifecycle and Webhooks](/offramp/operations/lifecycle.md)
- [Traditional Rails](/offramp/currencies/inr-traditional.md)
- [USD Onramp](/onramp/currencies/usd.md)
- [Overview](/offramp/overview.md)