Overview
Integration Guide
Complete guide to integrating ZBD Onramp into your application
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
Request
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
email | string | Yes | Email address of the user launching the Ramp |
webhook_url | string | Yes | URL to receive webhook notifications |
quote_currency | string | No | Currency to convert from (e.g., USD) |
base_currency | string | No | Currency to convert to (e.g., BTC) |
destination | string | No | Destination address for the funds (Lightning Address, onchain address, or USDC address) |
reference_id | string | No | Your internal reference ID for this transaction |
metadata | object | No | Additional metadata for the transaction |
access_token | string | No | Existing user session token |
Response
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
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