Generate Widget URL

Generate a signed widget URL to embed the ramp experience in an iframe. Server-side signing ensures wallet addresses are tamper-proof. Works for both buy (on-ramp) and sell (off-ramp) modes.

POSThttps://api.zenpays.com/payment/api/v1/on-ramp/widget-url

Bearer · API key

POSThttps://api.zenpays.com/payment/api/v1/off-ramp/widget-url

Bearer · API key

The on-ramp endpoint defaults to buy mode; the off-ramp endpoint defaults to sell mode.

Request

Headers

Header	Description
Content-Type REQUIRED	application/json
x-request-id OPTIONAL	Custom request ID for tracing

Public Endpoint

This endpoint does not require authentication headers.

Body Parameters

Parameter	Type	Description
mode OPTIONAL	string	buy, sell, or buy,sell (default depends on endpoint)
defaultFiat OPTIONAL	string	Default fiat currency (e.g. usd)
defaultCrypto OPTIONAL	string	Default crypto (e.g. btc_bitcoin)
defaultAmount OPTIONAL	number	Default amount
wallets OPTIONAL	string	TokenID:address format (e.g. btc:bc1q...)
networkWallets OPTIONAL	string	NetworkID:address format (e.g. ethereum:0x...)
walletAddressTags OPTIONAL	string	TokenID:tag format for memo coins
successRedirectUrl OPTIONAL	string	URL to redirect on success
failureRedirectUrl OPTIONAL	string	URL to redirect on failure
onlyFiats OPTIONAL	string	Restrict fiat options (comma-separated)
onlyCryptos OPTIONAL	string	Restrict crypto options (comma-separated)
onlyCryptoNetworks OPTIONAL	string	Restrict networks (comma-separated)
email OPTIONAL	string	Pre-fill user email
uuid OPTIONAL	string	Unique user identifier
partnerContext OPTIONAL	string	Custom tracking context

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "widgetUrl": "https://buy.onramper.com/?apiKey=...&mode=buy&defaultFiat=usd&defaultCrypto=BTC&wallets=btc:bc1q...&signature=abc123",
    "embedMode": "iframe"
  },
  "message": "Widget URL generated"
}

Response Fields

Parameter	Type	Description
widgetUrl OPTIONAL	string	Signed URL to embed in an iframe
embedMode OPTIONAL	string	Always iframe

Error Responses

Code	HTTP	Message
RAMP_WIDGET_URL_FAILED	500	Failed to generate buy widget URL
OFFRAMP_WIDGET_URL_FAILED	500	Failed to generate sell widget URL

Embedding the Widget

<iframe
  src="{widgetUrl}"
  height="660px"
  width="482px"
  title="Buy Crypto"
  allow="accelerometer; autoplay; camera; gyroscope; payment"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-top-navigation"
  style="border: none; border-radius: 12px;"
/>

Examples

cURL

# Buy widget
curl -X POST https://api.zenpays.com/payment/api/v1/on-ramp/widget-url \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "buy",
    "defaultFiat": "usd",
    "defaultCrypto": "BTC",
    "wallets": "btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "successRedirectUrl": "https://yourapp.com/success"
  }'

# Sell widget
curl -X POST https://api.zenpays.com/payment/api/v1/off-ramp/widget-url \
  -H "Content-Type: application/json" \
  -d '{
    "defaultFiat": "usd",
    "defaultCrypto": "BTC"
  }'

JavaScript

// Generate buy widget URL
const response = await fetch('https://api.zenpays.com/payment/api/v1/on-ramp/widget-url', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    mode: 'buy',
    defaultFiat: 'usd',
    defaultCrypto: 'BTC',
    wallets: 'btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
    successRedirectUrl: 'https://yourapp.com/success',
  }),
});

const { data } = await response.json();

// Embed in iframe
const iframe = document.createElement('iframe');
iframe.src = data.widgetUrl;
iframe.style.cssText = 'border:none; border-radius:12px; width:482px; height:660px;';
iframe.allow = 'accelerometer; autoplay; camera; gyroscope; payment';
document.getElementById('widget-container').appendChild(iframe);

Python

import requests

# Generate buy widget URL
response = requests.post(
    "https://api.zenpays.com/payment/api/v1/on-ramp/widget-url",
    json={
        "mode": "buy",
        "defaultFiat": "usd",
        "defaultCrypto": "BTC",
        "wallets": "btc:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "successRedirectUrl": "https://yourapp.com/success",
    },
)

data = response.json()["data"]
print(f"Widget URL: {data['widgetUrl']}")
print(f"Embed mode: {data['embedMode']}")

Integration Flow (Widget Mode)

1. POST /on-ramp/widget-url     → Get signed widget URL
2. Embed widgetUrl in iframe     → User completes purchase inside widget
3. User redirected to success/failure URL when done

Next Steps

• Config -- Check integration mode (widget vs API)
• Wallet Addresses -- Understand wallet resolution
• Buy Checkout -- API mode alternative