POST
/
v1
/
ramp-widget
Create Ramp Session
curl --request POST \
  --url https://api.zbdpay.com/v1/ramp-widget \
  --header 'Content-Type: application/json' \
  --header 'apikey: <apikey>' \
  --data '{
  "email": "<string>",
  "webhook_url": "<string>",
  "access_token": "<string>",
  "quote_currency": "<string>",
  "base_currency": "<string>",
  "destination": "<string>",
  "reference_id": "<string>",
  "metadata": {}
}'
{
  "success": true,
  "data": {
    "session_token": "eyJraWQiOiJzLWE1OWNkMjc4...",
    "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNkMjc4...",
    "session_id": "ses_9n3f7h2u4b",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}

​
API Overview

​
Base URL

All API requests should be made to: 
https://api.zbdpay.com

​
Authentication

All ZBD endpoints are protected by an API Key. To make requests against these endpoints you must pass a header property called apikey with your ZBD Project API Key. 
apikey: "your-api-key-here"
Get your API keys by scheduling a call with our sales team.

​
SSL / HTTPS Access

ZBD only provides a secure interface over HTTPS with SSL certificate support. Any requests that attempt to reach the ZBD API in an insecure fashion (plain-text over HTTP requests) will be rejected.

​
Description

This endpoint creates a session token and widget URL that can be used to embed the ZBD Ramp widget in your game or application.

​
Usage

The ramp widget allows your users to purchase Bitcoin or USDC using their preferred fiat currency. The session creation process involves:

First

Create a session with user details and configuration options

Second

Receive a widget URL and session token to embed in your application

​
Configuration

​
Header Parameters

​
apikey
string
required
ZBD Project API Key
​
Content-Type
string
Content Type

​
Body Parameters

​
email
string
required
Email address of the user launching the Ramp
​
webhook_url
string
required
URL to receive webhook notifications
​
access_token
string
Existing user session token (for returning users)
​
quote_currency
string
Currency to convert from (e.g., USD)
​
base_currency
string
Currency to convert to (e.g., BTC)
​
destination
string
Destination address for the funds (Lightning Address, onchain address, or USDC address)
​
reference_id
string
Your internal reference ID for this transaction
​
metadata
object
Additional metadata for the transaction
curl -X POST https://api.zbdpay.com/v1/ramp-widget \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "email": "user@example.com",
    "webhook_url": "https://yourapp.com/webhooks/zbd"
  }'

{
  "success": true,
  "data": {
    "session_token": "eyJraWQiOiJzLWE1OWNkMjc4...",
    "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNkMjc4...",
    "session_id": "ses_9n3f7h2u4b",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Please provide a valid email address"
  }
}
Common error codes:
  • INVALID_EMAIL - Email format is invalid
  • INVALID_WEBHOOK_URL - Webhook URL is not accessible
  • UNAUTHORIZED - Invalid API key
  • RATE_LIMITED - Too many requests

​
Webhook Events

Webhooks are sent as POST requests to your specified webhook_url.

​
Event Structure

All webhook events follow this structure: 
{
  "id": "evt_2n4f8gu3nf",
  "type": "ramp.purchase.completed",
  "created_at": "2025-06-09T10:30:00Z",
  "livemode": true,
  "data": {
    // Event-specific data
  }
}