Create Ramp Session

curl --request POST \
  --url https://api.zbdpay.com/api/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": {}
}
'

import requests

url = "https://api.zbdpay.com/api/v1/ramp-widget"

payload = {
    "email": "<string>",
    "webhook_url": "<string>",
    "access_token": "<string>",
    "quote_currency": "<string>",
    "base_currency": "<string>",
    "destination": "<string>",
    "reference_id": "<string>",
    "metadata": {}
}
headers = {
    "apikey": "<apikey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {apikey: '<apikey>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    webhook_url: '<string>',
    access_token: '<string>',
    quote_currency: '<string>',
    base_currency: '<string>',
    destination: '<string>',
    reference_id: '<string>',
    metadata: {}
  })
};

fetch('https://api.zbdpay.com/api/v1/ramp-widget', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zbdpay.com/api/v1/ramp-widget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'webhook_url' => '<string>',
    'access_token' => '<string>',
    'quote_currency' => '<string>',
    'base_currency' => '<string>',
    'destination' => '<string>',
    'reference_id' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <apikey>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zbdpay.com/api/v1/ramp-widget"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<apikey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zbdpay.com/api/v1/ramp-widget")
  .header("apikey", "<apikey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zbdpay.com/api/v1/ramp-widget")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apikey"] = '<apikey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

POST

api

ramp-widget

Create Ramp Session

curl --request POST \
  --url https://api.zbdpay.com/api/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": {}
}
'

import requests

url = "https://api.zbdpay.com/api/v1/ramp-widget"

payload = {
    "email": "<string>",
    "webhook_url": "<string>",
    "access_token": "<string>",
    "quote_currency": "<string>",
    "base_currency": "<string>",
    "destination": "<string>",
    "reference_id": "<string>",
    "metadata": {}
}
headers = {
    "apikey": "<apikey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {apikey: '<apikey>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    webhook_url: '<string>',
    access_token: '<string>',
    quote_currency: '<string>',
    base_currency: '<string>',
    destination: '<string>',
    reference_id: '<string>',
    metadata: {}
  })
};

fetch('https://api.zbdpay.com/api/v1/ramp-widget', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zbdpay.com/api/v1/ramp-widget",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'webhook_url' => '<string>',
    'access_token' => '<string>',
    'quote_currency' => '<string>',
    'base_currency' => '<string>',
    'destination' => '<string>',
    'reference_id' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <apikey>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zbdpay.com/api/v1/ramp-widget"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<apikey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zbdpay.com/api/v1/ramp-widget")
  .header("apikey", "<apikey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zbdpay.com/api/v1/ramp-widget")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apikey"] = '<apikey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"webhook_url\": \"<string>\",\n  \"access_token\": \"<string>\",\n  \"quote_currency\": \"<string>\",\n  \"base_currency\": \"<string>\",\n  \"destination\": \"<string>\",\n  \"reference_id\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

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

string

required

ZBD Project API Key

string

Content Type

Body Parameters

string

required

Email address of the user launching the Ramp

string

required

URL to receive webhook notifications

string

Existing user session token (for returning users)

string

Currency to convert from (e.g., USD)

string

Currency to convert to (e.g., BTC)

string

Destination address for the funds (Lightning Address or onchain address)

string

Your internal reference ID for this transaction

object

Additional metadata for the transaction

curl -X POST https://api.zbdpay.com/api/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"
  }'

const response = await fetch('https://api.zbdpay.com/api/v1/ramp-widget', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.ZBD_API_KEY
  },
  body: JSON.stringify({
    email: 'user@example.com',
    webhook_url: 'https://yourapp.com/webhooks/zbd'
  })
});

const data = await response.json();

{
  "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
  }
}

Flutter Platform Details

⌘I

Overview

SDKs

API

Customization

Events

Create Ramp Session

API Overview

Base URL

Authentication

SSL / HTTPS Access

Description

Usage

First

Second

Configuration

Header Parameters

Body Parameters

Error Responses

Webhook Events

Event Structure

​API Overview

​Base URL

​Authentication

​SSL / HTTPS Access

​Description

​Usage

First

Second

​Configuration

​Header Parameters

​Body Parameters

​Error Responses

​Webhook Events

​Event Structure

API Overview

Base URL

Authentication

SSL / HTTPS Access

Description

Usage

Configuration

Header Parameters

Body Parameters

Error Responses

Webhook Events

Event Structure