<!-- ZenPays documentation · https://docs.zenpayz.com/docs/rest-api/endpoints/ramp/ramp-overview -->

# Ramp Overview

ZenPays Ramp enables your customers to buy crypto with fiat (**On-Ramp**) and sell crypto for fiat (**Off-Ramp**). There are two ways to integrate: the **Widget** (recommended) or the **Direct API**.

## Integration Paths

### Widget Integration (Recommended)

Embed the ZenPays hosted widget in your app via iframe. The widget handles the entire flow — KYC verification, payment method selection, provider routing, and transaction tracking — so you don't have to.

```
Your Server                         Your Frontend                    ZenPays Widget
    │                                     │                               │
    │  1. POST /ramp-intents              │                               │
    │  ──────────────────►                │                               │
    │  ◄── intentId + redirectUrl         │                               │
    │                                     │                               │
    │         2. Pass redirectUrl ──────► │                               │
    │                                     │  3. Embed iframe (widgetUrl)  │
    │                                     │  ─────────────────────────►   │
    │                                     │                               │
    │                                     │     Customer completes flow   │
    │                                     │  ◄─────────────────────────   │
    │                                     │                               │
    │  4. Receive webhook (ramp.completed)│                               │
    │  ◄──────────────────────────────────┘                               │
```

**What you build:** Create an intent on your server, embed the widget URL in an iframe. That's it.

**What ZenPays handles:** KYC, payment UI, provider selection, error handling, status tracking.

### API Integration (Advanced)

Call the ramp APIs directly to build your own custom UI. You get full control over the user experience but must handle quotes, checkout creation, status polling, and error states yourself.

```
Your Server / Frontend                              ZenPays API
    │                                                    │
    │  1. GET  /on-ramp/quotes                           │
    │  ───────────────────────────────────────────►      │
    │  ◄─── quote options                                │
    │                                                    │
    │  2. POST /on-ramp/checkout                         │
    │  ───────────────────────────────────────────►      │
    │  ◄─── transactionId + redirectUrl                  │
    │                                                    │
    │  3. Redirect customer to payment page              │
    │                                                    │
    │  4. GET /on-ramp/transactions/:id  (poll)          │
    │  ───────────────────────────────────────────►      │
    │  ◄─── status: completed                            │
```

**What you build:** Your own quote display, checkout UI, payment flow, status polling, error handling.

**What ZenPays handles:** Provider routing, payment processing, crypto delivery.

## Which Should I Choose?

| | Widget | API |
|---|---|---|
| **Integration effort** | ~10 lines of code | Significant frontend work |
| **Time to go live** | Hours | Days to weeks |
| **KYC handling** | Built-in | You must build or skip |
| **Payment UI** | Hosted by ZenPays | You build it |
| **Provider selection** | Automatic | You call quotes + choose |
| **Error handling** | Built-in | You handle all states |
| **Customization** | Limited (colors, defaults) | Full control |
| **Best for** | Most merchants | Exchanges, advanced UIs |

:::tip Recommendation
**Start with the Widget.** It gets you to production fastest with the least maintenance. You can always migrate to the API later if you need deeper customization.
:::

## Supported Directions

| Direction | Description | Use Case |
|-----------|-------------|----------|
| **On-Ramp (Buy)** | Customer pays fiat, receives crypto | "Buy Bitcoin with USD" |
| **Off-Ramp (Sell)** | Customer sends crypto, receives fiat | "Sell USDT for INR" |

Both directions are supported by the Widget and API integration paths.

## Key Concepts

### Ramp Intents

A **Ramp Intent** is a server-side session that tracks a ramp transaction from creation to completion. Intents are required for widget integration and optional (but recommended) for API integration.

- Created on your server with your API key (authenticated)
- Returns a `redirectUrl` with the widget embedded
- Expires after 1 hour
- Triggers `ramp.completed` or `ramp.failed` webhooks

### Configuration Endpoints

Before building your integration, use the configuration endpoints to discover:

- **Supported Assets** — Which crypto and fiat currencies are available
- **Payment Methods** — Which payment methods work for a given currency
- **Defaults** — Default currencies and amounts per country
- **Ramp Config** — Current integration mode and feature flags

These endpoints are public (no authentication required) and useful for both Widget and API integrations.

## Next Steps

- **Widget path:** Start with [Generate Widget URL](./widget-url.md) or [Create Ramp Intent](./create-ramp-intent.md)
- **API path:** Start with [Buy Quotes](./buy-quotes.md) (on-ramp) or [Sell Quotes](./sell-quotes.md) (off-ramp)
- **Examples:** See [On-Ramp Flow](/docs/examples/on-ramp-flow) and [Off-Ramp Flow](/docs/examples/off-ramp-flow) for complete walkthroughs