Skip to main content
The @zbdpay/ramp-ts package is the core TypeScript/JavaScript iframe wrapper for the ZBD Ramp widget that enables Bitcoin purchase interface for web applications.

​
Features

  • TypeScript First: Full type safety with comprehensive TypeScript definitions
  • PostMessage Communication: Real-time error handling, logging, and step tracking
  • Lightweight: No dependencies, tree-shakeable
  • Framework Agnostic: Works with any JavaScript framework or vanilla JS

​
Installation

  • npm
  • yarn
  • pnpm
  • CDN
npm install @zbdpay/ramp-ts

​
Quick Start

​
1. Create Session Token

First, create a session token using the ZBD API: 
import { initRampSession, QuoteCurrencyEnum, BaseCurrencyEnum } from '@zbdpay/ramp-ts';

const response = await initRampSession({
  apikey: 'your-zbd-api-key',
  email: 'user@example.com',
  destination: 'lightning-address@zbd.gg',
  quote_currency: QuoteCurrencyEnum.USD,
  base_currency: BaseCurrencyEnum.BTC,
  webhook_url: 'https://your-webhook-url.com',
});

const sessionToken = response.data.session_token;

​
2. Create and Mount Widget

import { createRamp } from '@zbdpay/ramp-ts';

const ramp = createRamp({
  sessionToken,
  container: '#ramp-container',
  onSuccess: (data) => console.log('Success:', data),
  onError: (error) => console.error('Error:', error),
  onStepChange: (step) => console.log('Step:', step),
});

ramp.mount();

​
API Reference

​
initRampSession

Creates a new session token for the ZBD Ramp widget.
​
config
InitRampSessionConfig
required
Configuration object for creating a session

​
Configuration Parameters

​
apikey
string
required
Your ZBD API key
​
email
string
required
User’s email address
​
destination
string
required
Lightning address or Bitcoin address
​
quote_currency
QuoteCurrencyEnum
required
Quote currency (e.g., USD)
​
base_currency
BaseCurrencyEnum
required
Base currency (e.g., BTC)
​
webhook_url
string
Webhook URL for notifications
​
reference_id
string
Your internal reference ID
​
metadata
Record<string, any>
Additional metadata to attach to the session

​
Response

interface InitRampSessionResponse {
  data: {
    session_token: string;    // Session token for widget
    expires_at: string;        // Token expiration time
    widget_url: string;        // Direct widget URL
  };
  error: string | null;       // Error message if failed
  success: boolean;           // Success status
  message: string;             // Response message
}

​
Example

import { initRampSession, QuoteCurrencyEnum, BaseCurrencyEnum } from '@zbdpay/ramp-ts';

try {
  const response = await initRampSession({
    apikey: 'your-zbd-api-key',
    email: 'user@example.com',
    destination: 'lightning-address@zbd.gg',
    quote_currency: QuoteCurrencyEnum.USD,
    base_currency: BaseCurrencyEnum.BTC,
    webhook_url: 'https://your-webhook.com',
    reference_id: 'order-123',
    metadata: { 
      userId: '456', 
      plan: 'premium' 
    },
  });

  if (response.success) {
    const sessionToken = response.data.session_token;
    console.log('Session created:', sessionToken);
  } else {
    console.error('Failed to create session:', response.error);
  }
} catch (error) {
  console.error('Session creation error:', error);
}

​
createRamp

Creates a new ZBD Ramp widget instance.
​
options
RampOptions
required
Configuration options for the widget

​
Options

​
sessionToken
string
required
Session token from initRampSession
​
container
HTMLElement | string
Container element or CSS selector
​
width
string | number
default:"100%"
Widget width
​
height
string | number
default:"100%"
Widget height (minimum 600px recommended)

​
Callback Options

​
onSuccess
(data: any) => void
Called when payment is successful
​
onError
(error: RampError) => void
Called when an error occurs
​
onStepChange
(step: string) => void
Called when user navigates to a different step
​
onLog
(log: RampLog) => void
Debug/info logging callback
​
onReady
() => void
Called when widget is fully loaded
​
onClose
() => void
Called when user closes the widget

​
Returns

interface RampInstance {
  mount: (container?: HTMLElement | string) => void;
  unmount: () => void;
  destroy: () => void;
}

​
Usage Examples

​
Basic Implementation

import { createRamp } from '@zbdpay/ramp-ts';

const ramp = createRamp({
  sessionToken: 'your-session-token',
  container: document.getElementById('ramp-container'),
});

ramp.mount();

​
With Event Handlers

const ramp = createRamp({
  sessionToken: 'your-session-token',
  onSuccess: (data) => {
    console.log('Payment successful:', data);
    // Update UI, redirect, etc.
    window.location.href = '/success';
  },
  onError: (error) => {
    console.error('Payment error:', error);
    // Show error message to user
    alert(`Error: ${error.message}`);
  },
  onStepChange: (step) => {
    console.log('Current step:', step);
    // Track user progress
    analytics.track('Ramp Step', { step });
  },
  onReady: () => {
    console.log('Widget ready');
    // Hide loading spinner
  },
  onClose: () => {
    console.log('Widget closed');
    // Handle user closing widget
  }
});

​
Custom Dimensions

const ramp = createRamp({
  sessionToken: 'your-session-token',
  width: '400px',
  height: '700px',
});

// Default iframe styles applied:
// - border: none
// - border-radius: 8px
// - allow: payment
// - allowtransparency: true
// - min-height: 600px

​
Programmatic Control

const ramp = createRamp({
  sessionToken: 'your-session-token',
});

// Mount to specific container
ramp.mount('#my-container');

// Unmount iframe (keeps instance alive)
ramp.unmount();

// Remount to different container
ramp.mount('#another-container');

// Clean up completely
ramp.destroy();

​
Error Handling

const ramp = createRamp({
  sessionToken: 'your-session-token',
  onError: (error) => {
    // Error structure
    console.error('Error Code:', error.code);
    console.error('Error Message:', error.message);
    
    if (error.details) {
      console.error('Error Details:', error.details);
    }
    
    // Handle specific error codes
    switch(error.code) {
      case 'SESSION_EXPIRED':
        // Create new session
        createNewSession();
        break;
      case 'KYC_REQUIRED':
        // Inform user about KYC
        showKYCMessage();
        break;
      default:
        // Generic error handling
        showErrorMessage(error.message);
    }
  },
});

​
TypeScript Support

The package includes comprehensive TypeScript definitions: 
import type {
  RampConfig,
  RampCallbacks,
  RampOptions,
  RampError,
  RampLog,
  RampInstance,
  PostMessageData,
  InitRampSessionConfig,
  InitRampSessionData,
  InitRampSessionResponse,
  QuoteCurrencyEnum,
  BaseCurrencyEnum,
} from '@zbdpay/ramp-ts';

​
Type Examples

// Define typed configuration
const config: InitRampSessionConfig = {
  apikey: process.env.ZBD_API_KEY!,
  email: 'user@example.com',
  destination: 'lightning-address@zbd.gg',
  quote_currency: QuoteCurrencyEnum.USD,
  base_currency: BaseCurrencyEnum.BTC,
};

// Handle typed responses
const handleSuccess = (data: any): void => {
  console.log('Payment completed:', data);
};

const handleError = (error: RampError): void => {
  console.error(`Error ${error.code}: ${error.message}`);
};

// Create typed instance
const ramp: RampInstance = createRamp({
  sessionToken: 'token',
  onSuccess: handleSuccess,
  onError: handleError,
});

​
Simple Iframe Alternative

If you don’t need JavaScript callbacks, you can use a simple iframe: 
<iframe 
  src="https://ramp.zbdpay.com?session_token=YOUR_SESSION_TOKEN"
  width="100%" 
  height="600px"
  allow="payment"
  style="border: none; border-radius: 8px;">
</iframe>

​
Framework Integrations

This is the core package. For framework-specific integrations, see:

React

React components and hooks

React Native

React Native components

Flutter

Flutter plugin

​
Try It Out

​
Interactive Example

To try the interactive example locally:
  1. Clone the repository: 
    git clone https://github.com/zbdpay/ramp-ts.git
cd ramp-ts
  2. Start a local server: 
    npx http-server . -p 8000 -o /example/js.html
  3. Fill the form with your API key and user details
  4. Click “Create Session & Load Ramp” to see it in action

​
CodeSandbox Example

Try it online: CodeSandbox Demo

​
Resources

​
Support

For support and questions:
⌘I