Ramp Webhooks

Ramp webhook events notify you when a ramp intent (buy or sell) reaches a terminal state.

Events

Event	Description
ramp.completed	Ramp intent completed (buy: crypto sent to wallet, sell: fiat payout submitted)
ramp.failed	Ramp intent failed (crypto send or payout submission failed)

Payloads

The payload varies depending on the ramp direction (buy vs sell) and outcome.

Buy Ramp Completed

Crypto has been sent to the customer's wallet:

{
  "event_type": "ramp.completed",
  "payment_data": {
    "merchant_id": "m_abc123",
    "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
    "type": "buy",
    "status": "completed",
    "fiatCurrency": "USD",
    "cryptoCurrency": "eth_ethereum",
    "amount": 100,
    "chain": "ethereum",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    "fireblocksTxId": "fb_tx_9a8b7c6d5e4f",
    "completedAt": "2026-03-16T14:30:00.000Z"
  }
}

Sell Ramp Completed

Fiat payout has been submitted to the customer's bank account:

{
  "event_type": "ramp.completed",
  "payment_data": {
    "merchant_id": "m_abc123",
    "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
    "type": "sell",
    "status": "completed",
    "fiatCurrency": "USD",
    "cryptoCurrency": "usdt_tron",
    "amount": 20,
    "payoutId": "po_xyz789",
    "payoutAmount": 19.50,
    "payoutCurrency": "USD",
    "completedAt": "2026-03-16T14:30:00.000Z"
  }
}

Ramp Failed

Buy or sell flow encountered an error:

{
  "event_type": "ramp.failed",
  "payment_data": {
    "merchant_id": "m_abc123",
    "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
    "type": "buy",
    "status": "failed",
    "fiatCurrency": "USD",
    "cryptoCurrency": "eth_ethereum",
    "amount": 100,
    "reason": "Crypto send failed",
    "failedAt": "2026-03-16T14:30:00.000Z"
  }
}

Payload Fields

Field	Type	Present	Description
merchant_id	string	Always	Your merchant ID
intentId	string	Always	Ramp intent ID (ri_...)
type	string	Always	"buy" or "sell"
status	string	Always	"completed" or "failed"
fiatCurrency	string	Always	ISO currency code (e.g. USD, EUR)
cryptoCurrency	string	Always	Crypto identifier (e.g. eth_ethereum, usdt_tron)
amount	number	Always	Original intent amount
completedAt	string	On success	ISO 8601 completion timestamp
failedAt	string	On failure	ISO 8601 failure timestamp
reason	string	On failure	Human-readable failure reason
chain	string	Buy success	Blockchain network (e.g. ethereum, tron)
destinationAddress	string	Buy success	Wallet address crypto was sent to
cryptoTxId	string	Buy success	Crypto transaction reference
payoutId	string	Sell success	Payout reference ID
payoutAmount	number	Sell success	Fiat amount paid out
payoutCurrency	string	Sell success	Fiat currency of payout