TypeScript SDK

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

yarn add @zbdpay/ramp-ts

pnpm add @zbdpay/ramp-ts

<script type="module">
  import { createRamp } from 'https://cdn.jsdelivr.net/npm/@zbdpay/ramp-ts/dist/src/index.js';
</script>

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;

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

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:

Clone the repository:

git clone https://github.com/zbdpay/ramp-ts.git
cd ramp-ts

Start a local server:

npx http-server . -p 8000 -o /example/js.html

Fill the form with your API key and user details
Click “Create Session & Load Ramp” to see it in action

CodeSandbox Example

Try it online: CodeSandbox Demo

Resources

Support

For support and questions:

GitHub Issues: Create an issue

Overview

SDKs

API

Customization

Events

Features

Installation

Quick Start

1. Create Session Token

2. Create and Mount Widget

API Reference

initRampSession

Configuration Parameters

Response

Example

createRamp

Options

Callback Options

Returns

Usage Examples

Basic Implementation

With Event Handlers

Custom Dimensions

Programmatic Control

Error Handling

TypeScript Support

Type Examples

Simple Iframe Alternative

Framework Integrations

React

React Native

Flutter

Try It Out

Interactive Example

CodeSandbox Example

Resources

Support

Overview

SDKs

API

Customization

Events

​Features

​Installation

​Quick Start

​1. Create Session Token

​2. Create and Mount Widget

​API Reference

​initRampSession

​Configuration Parameters

​Response

​Example

​createRamp

​Options

​Callback Options

​Returns

​Usage Examples

​Basic Implementation

​With Event Handlers

​Custom Dimensions

​Programmatic Control

​Error Handling

​TypeScript Support

​Type Examples

​Simple Iframe Alternative

​Framework Integrations

React

React Native

Flutter

​Try It Out

​Interactive Example

​CodeSandbox Example

​Resources

​Support

Features

Installation

Quick Start

1. Create Session Token

2. Create and Mount Widget

API Reference

initRampSession

Configuration Parameters

Response

Example

createRamp

Options

Callback Options

Returns

Usage Examples

Basic Implementation

With Event Handlers

Custom Dimensions

Programmatic Control

Error Handling

TypeScript Support

Type Examples

Simple Iframe Alternative

Framework Integrations

Try It Out

Interactive Example

CodeSandbox Example

Resources

Support