Order lifecycle and Webhooks

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`

{
  "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`

{
  "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`

{
  "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": ""
}

Getting Started

Client Admin Operations

Offramp

Onramp

User Operations

Sample Payloads

`ONRAMP_COMPLETED`

`COMPLETED`

`FAILED`

​Sample Payloads

​ONRAMP_COMPLETED

​COMPLETED

​FAILED

Sample Payloads

`ONRAMP_COMPLETED`

`COMPLETED`

`FAILED`