This guide covers the technical details of integrating ZBD Onramp, including session management, widget parameters, and webhook handling.

​
Integration Flow

1

Initialize Session

Call the /v1/ramp-widget endpoint from your backend
2

Load Widget

Embed the returned widget URL in an iframe
3

Handle Events

Process webhooks and frontend messages

​
Session Initialization

Create a widget session by calling our API from your backend. This ensures your API key remains secure.

​
Endpoint

POST https://api.zebedee.io/v1/ramp-widget

​
Request

curl -X POST https://api.zebedee.io/api/v1/ramp-widget \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "email": "player@game.com",
    "webhook_url": "https://yourgame.com/webhooks/zbd",
    "quote_currency": "USD",
    "base_currency": "BTC",
    "destination": "spiderman@zbd.gg",
    "reference_id": "player_123_purchase_456",
    "metadata": {
      "player_id": "123",
      "game_session": "abc"
    }
  }'

​
Parameters

ParameterTypeRequiredDescription
emailstringYesEmail address of the user launching the Ramp
webhook_urlstringYesURL to receive webhook notifications
quote_currencystringNoCurrency to convert from (e.g., USD)
base_currencystringNoCurrency to convert to (e.g., BTC)
destinationstringNoDestination address for the funds (Lightning Address, onchain address, or USDC address)
reference_idstringNoYour internal reference ID for this transaction
metadataobjectNoAdditional metadata for the transaction
access_tokenstringNoExisting user session token

​
Response

{
  "success": true,
  "data": {
    "session_token": "eyJraWQiOiJzLWE1OWNk...",
    "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNk...",
    "expires_at": "2025-06-09T12:00:00Z"
  }
}
Widget sessions expire after 15 minutes. Create a new session if the user needs more time.

​
Widget Embedding

Once you have the widget URL, embed it in your application using an iframe.

​
Basic Implementation

<iframe 
  id="zbd-onramp"
  src="WIDGET_URL_FROM_API"
  style="width: 100%; height: 600px; border: none;"
  allow="camera; microphone"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
></iframe>

​
Security Best Practices

API Key Security

  • Never expose API keys in frontend code
  • Use environment variables
  • Rotate keys regularly
  • Restrict key permissions

Webhook Security

  • Always verify signatures
  • Use HTTPS endpoints only
  • Implement idempotency
  • Log all events

​
Next Steps

Customization

Learn how to customize the widget appearance

Need Help?

Contact Support - Our team is here to help with your integration. Schedule a technical support session.