React SDK

The @zbdpay/ramp-react package is a React wrapper for the ZBD Ramp widget that enables Buying Bitcoin with USD directly to the Lightning Network.

Features

React Optimized: Built specifically for React with hooks and components
TypeScript Support: Full type safety with comprehensive TypeScript definitions
Ref API: Access to underlying ramp instance methods via React refs
Hook Support: useZBDRamp hook for programmatic usage
Session Token Based: Uses secure session tokens for authentication

Installation

npm
yarn
pnpm

npm install @zbdpay/ramp-react

yarn add @zbdpay/ramp-react

pnpm add @zbdpay/ramp-react

Quick Start

1. Create Session Token

First, create a session token using the ZBD API:

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

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. Use ZBDRamp Component

import { ZBDRamp } from '@zbdpay/ramp-react';

function App() {
  const handleSuccess = (data) => {
    console.log('Payment successful:', data);
  };

  const handleError = (error) => {
    console.error('Payment error:', error);
  };

  return (
    <ZBDRamp
      sessionToken="your-session-token"
      onSuccess={handleSuccess}
      onError={handleError}
      style={{ width: '100%', height: '600px' }}
    />
  );
}

API Reference

initRampSession

Creates a new session token for the ZBD Ramp widget.

InitRampSessionConfig

required

Configuration object for creating a session

Configuration Parameters

string

required

Your ZBD API key

string

required

User’s email address

string

required

Lightning address or Bitcoin address

QuoteCurrencyEnum

required

Quote currency (e.g., USD)

BaseCurrencyEnum

required

Base currency (e.g., BTC)

string

Webhook URL for notifications

string

Your internal reference ID

Record<string, any>

Additional metadata to attach to the session

ZBDRamp Component

React component that renders the ZBD Ramp widget.

Props

string

required

Session token from ZBD API

string | number

default:"100%"

Widget width

string | number

default:"600px"

Widget height (minimum 600px recommended)

string

CSS class for container

React.CSSProperties

Inline styles for container

Callback Props

(data: any) => void

Called when payment is successful

(error: RampError) => void

Called when an error occurs

(step: string) => void

Called when user navigates to a different step

(log: RampLog) => void

Debug/info logging callback

() => void

Called when widget is fully loaded

() => void

Called when user closes the widget

Ref API

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

useZBDRamp Hook

Hook for creating and managing ZBD Ramp instances programmatically.

const { createInstance, destroyInstance, instance } = useZBDRamp(options);

Usage Examples

Basic Component

import React from 'react';
import { ZBDRamp } from '@zbdpay/ramp-react';

function PaymentWidget({ sessionToken }) {
  const handleSuccess = (data: any) => {
    console.log('Payment successful:', data);
    // Handle successful payment
  };

  const handleError = (error: any) => {
    console.error('Payment error:', error);
    // Handle error
  };

  return (
    <div className="payment-container">
      <h1>Make a Payment</h1>
      <ZBDRamp
        sessionToken={sessionToken}
        onSuccess={handleSuccess}
        onError={handleError}
        style={{
          width: '100%',
          height: '600px',
          border: '1px solid #ddd',
          borderRadius: '8px'
        }}
      />
    </div>
  );
}

With Ref for Control

import React, { useRef } from 'react';
import { ZBDRamp } from '@zbdpay/ramp-react';
import type { ZBDRampRef } from '@zbdpay/ramp-react';

function ControlledPayment({ sessionToken }) {
  const rampRef = useRef<ZBDRampRef>(null);

  const closeWidget = () => {
    rampRef.current?.unmount();
  };

  const destroyWidget = () => {
    rampRef.current?.destroy();
  };

  return (
    <div>
      <button onClick={closeWidget}>Close Widget</button>
      <button onClick={destroyWidget}>Destroy Widget</button>

      <ZBDRamp
        ref={rampRef}
        sessionToken={sessionToken}
        onSuccess={(data) => console.log('Success:', data)}
        onError={(error) => console.error('Error:', error)}
      />
    </div>
  );
}

Using the Hook

import React, { useState } from 'react';
import { useZBDRamp } from '@zbdpay/ramp-react';

function HookExample({ sessionToken }) {
  const [isOpen, setIsOpen] = useState(false);

  const { createInstance, destroyInstance } = useZBDRamp({
    sessionToken,
    container: '#ramp-container',
    onSuccess: (data) => {
      console.log('Payment successful:', data);
      setIsOpen(false);
    },
    onClose: () => {
      setIsOpen(false);
    },
  });

  const openRamp = () => {
    setIsOpen(true);
    createInstance();
  };

  const closeRamp = () => {
    setIsOpen(false);
    destroyInstance();
  };

  return (
    <div>
      <button onClick={openRamp}>Open Payment</button>
      {isOpen && (
        <div>
          <button onClick={closeRamp}>Close</button>
          <div id="ramp-container" style={{ width: '100%', height: '600px' }} />
        </div>
      )}
    </div>
  );
}

Error Handling

import React, { useState } from 'react';
import { ZBDRamp } from '@zbdpay/ramp-react';
import type { RampError } from '@zbdpay/ramp-react';

function PaymentWithErrorHandling({ sessionToken }) {
  const [error, setError] = useState<string | null>(null);

  const handleError = (error: RampError) => {
    switch (error.code) {
      case 'INVALID_CONFIG':
        setError('Configuration error. Please check your settings.');
        break;
      case 'NETWORK_ERROR':
        setError('Network error. Please check your connection.');
        break;
      case 'PAYMENT_FAILED':
        setError('Payment failed. Please try again.');
        break;
      default:
        setError('An unexpected error occurred.');
    }
  };

  const clearError = () => setError(null);

  return (
    <div>
      {error && (
        <div style={{ color: 'red', marginBottom: '10px' }}>
          Error: {error}
          <button onClick={clearError}>×</button>
        </div>
      )}

      <ZBDRamp
        sessionToken={sessionToken}
        onSuccess={() => setError(null)}
        onError={handleError}
      />
    </div>
  );
}

Session Token Creation

import React, { useState } from 'react';
import { ZBDRamp, initRampSession, QuoteCurrencyEnum, BaseCurrencyEnum } from '@zbdpay/ramp-react';

function SessionTokenExample() {
  const [sessionToken, setSessionToken] = useState('');
  const [isLoading, setIsLoading] = useState(false);

  const createSession = async () => {
    setIsLoading(true);
    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',
      });

      if (response.success) {
        setSessionToken(response.data.session_token);
      } else {
        console.error('Failed to create session:', response.error);
      }
    } catch (error) {
      console.error('Error creating session:', error);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      {!sessionToken ? (
        <button onClick={createSession} disabled={isLoading}>
          {isLoading ? 'Creating Session...' : 'Create Session'}
        </button>
      ) : (
        <ZBDRamp
          sessionToken={sessionToken}
          onSuccess={(data) => console.log('Success:', data)}
        />
      )}
    </div>
  );
}

import React, { useState } from 'react';
import { ZBDRamp } from '@zbdpay/ramp-react';

function ModalExample({ sessionToken }) {
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsModalOpen(true)}>
        Open Payment Modal
      </button>

      {isModalOpen && (
        <div className="modal-overlay" onClick={() => setIsModalOpen(false)}>
          <div className="modal-content" onClick={(e) => e.stopPropagation()}>
            <button
              className="modal-close"
              onClick={() => setIsModalOpen(false)}
            >
              ×
            </button>

            <ZBDRamp
              sessionToken={sessionToken}
              onSuccess={(data) => {
                console.log('Payment successful:', data);
                setIsModalOpen(false);
              }}
              onClose={() => setIsModalOpen(false)}
              style={{ width: '100%', height: '600px' }}
            />
          </div>
        </div>
      )}
    </>
  );
}

TypeScript Support

The package includes comprehensive TypeScript definitions:

import type {
  ZBDRampProps,
  ZBDRampRef,
  RampConfig,
  RampCallbacks,
  RampOptions,
  RampError,
  RampLog,
  RampInstance,
  PostMessageData,
  InitRampSessionConfig,
  InitRampSessionData,
  InitRampSessionResponse,
  QuoteCurrencyEnum,
  BaseCurrencyEnum,
} from '@zbdpay/ramp-react';

Type Examples

// Define typed configuration
const config: InitRampSessionConfig = {
  apikey: process.env.REACT_APP_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 ref
const rampRef = useRef<ZBDRampRef>(null);

Complete Example App

The repository includes a complete example application:

# Clone and run example
git clone https://github.com/zbdpay/ramp-react.git
cd ramp-react/example
npm install
npm run dev

The example includes:

Session token creation form
Complete ZBD Ramp integration
Error handling and callbacks
TypeScript implementation

TypeScript

Core TypeScript/JavaScript SDK

React Native

React Native components

Flutter

Flutter plugin

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. Use ZBDRamp Component

API Reference

initRampSession

Configuration Parameters

ZBDRamp Component

Props

Callback Props

Ref API

useZBDRamp Hook

Usage Examples

Basic Component

With Ref for Control

Using the Hook

Error Handling

Session Token Creation

TypeScript Support

Type Examples

Complete Example App

TypeScript

React Native

Flutter

Resources

Support

​Features

​Installation

​Quick Start

​1. Create Session Token

​2. Use ZBDRamp Component

​API Reference

​initRampSession

​Configuration Parameters

​ZBDRamp Component

​Props

​Callback Props

​Ref API

​useZBDRamp Hook

​Usage Examples

​Basic Component

​With Ref for Control

​Using the Hook

​Error Handling

​Session Token Creation

​Modal Integration

​TypeScript Support

​Type Examples

​Complete Example App

​Related Packages

TypeScript

React Native

Flutter

​Resources

​Support

Features

Installation

Quick Start

1. Create Session Token

2. Use ZBDRamp Component

API Reference

initRampSession

Configuration Parameters

ZBDRamp Component

Props

Callback Props

Ref API

useZBDRamp Hook

Usage Examples

Basic Component

With Ref for Control

Using the Hook

Error Handling

Session Token Creation

Modal Integration

TypeScript Support

Type Examples

Complete Example App

Related Packages

Resources

Support