<!-- ZenPays documentation · https://docs.zenpayz.com/docs/guides/webhooks/ramp-webhooks -->

# 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:

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

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

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