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

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 or Create Ramp Intent
• API path: Start with Buy Quotes (on-ramp) or Sell Quotes (off-ramp)
• Examples: See On-Ramp Flow and Off-Ramp Flow for complete walkthroughs