@pouchpay/widget

v0.13.26

Published

12 days ago

React widget component for PouchPay - Embeddable crypto on/off-ramp for African markets

@pouchpay/widget

Embeddable React widget for crypto on/off-ramp in African markets

A React component that enables seamless cryptocurrency buying (onramp) and selling (offramp) directly within your application. Built specifically for African markets with support for local payment methods and currencies.

Features

🚀 Simple Integration - Drop-in React component or vanilla JavaScript
💰 Onramp & Offramp - Support for both buying and selling crypto
🌍 African-Focused - Optimized for Nigerian Naira (NGN) with more currencies coming
🎨 Customizable - White-label support with theming options
📱 Mobile-Friendly - Responsive design that works on all devices
🔒 Secure - Built-in KYC and identity verification
⚡ Real-time Updates - Live transaction status tracking
💳 Local Payment Methods - Bank transfers and other local payment options

Supported Assets

Stablecoins: USDT, USDC
Networks: TRC20 (TRON), ERC20 (Ethereum), Polygon, BSC, Base, and more
Fiat Currencies: NGN (Nigerian Naira)

Installation

npm

npm install @pouchpay/widget

yarn

yarn add @pouchpay/widget

pnpm

pnpm add @pouchpay/widget

Quick Start

React Integration

import { PouchPayWidget } from '@pouchpay/widget';

function App() {
  return (
    <PouchPayWidget
      walletAddress="0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      cryptoCurrency="USDT"
      cryptoNetwork="TRC20"
      variant="modal"
      apiKey={process.env.REACT_APP_POUCHPAY_API_KEY}
    />
  );
}

Next.js Integration

The widget works seamlessly with Next.js (both App Router and Pages Router). Just add the 'use client' directive since the widget is a client-side component.

'use client';
import { PouchPayWidget } from '@pouchpay/widget';

export default function Page() {
  return (
    <PouchPayWidget
      walletAddress="0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      cryptoCurrency="USDT"
      cryptoNetwork="TRC20"
      variant="modal"
      apiKey={process.env.NEXT_PUBLIC_POUCHPAY_API_KEY}
    />
  );
}

Note: The widget is compatible with both React 18 and React 19, so it works with all Next.js versions including the latest App Router.

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
</head>
<body>
  <div id="pouchpay-widget"></div>

  <script src="https://unpkg.com/@pouchpay/widget/dist/pouchpay-widget.umd.cjs"></script>
  <script>
    PouchPayWidget.init({
      walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
      cryptoCurrency: 'USDT',
      cryptoNetwork: 'TRC20',
      variant: 'inline',
      apiKey: 'your-api-key'
    });
  </script>
</body>
</html>

Integration Modes

The widget supports three integration modes to fit different use cases:

1. Minimal Configuration (Recommended)

MoonPay-style integration where users choose whether to buy or sell crypto and enter the amount inside the widget.

<PouchPayWidget
  walletAddress="0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  cryptoCurrency="USDT"
  cryptoNetwork="TRC20"
  variant="modal"
  apiKey="your-api-key"
/>

Best for: Embedded widgets where you want users to configure everything inside.

2. Full Configuration

You specify type (onramp/offramp), amount, and all parameters upfront.

<PouchPayWidget
  createSession={{
    type: 'ONRAMP',
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    cryptoCurrency: 'USDT',
    cryptoNetwork: 'TRC20',
    amount: 100,
    countryCode: 'NG',
    currency: 'NGN',
  }}
  variant="inline"
  apiKey="your-api-key"
/>

Best for: Checkout flows where users already selected everything in your UI.

3. Hybrid Mode

Pre-select type and/or amount, but users can still change them.

<PouchPayWidget
  walletAddress="0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  cryptoCurrency="USDT"
  cryptoNetwork="TRC20"
  type="ONRAMP"        // Pre-select buy
  amount={100}         // Pre-fill amount
  variant="modal"
  apiKey="your-api-key"
/>

Best for: Guided flows where you want to help users but still give them control.

API Reference

PouchPayWidgetProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your PouchPay API key from the dashboard | | walletAddress | string | For onramp | Destination wallet address (required for buying crypto) | | cryptoCurrency | string | No | Crypto asset (e.g., 'USDT', 'USDC') | | cryptoNetwork | string | No | Network (e.g., 'TRC20', 'ERC20', 'POLYGON') | | variant | 'modal' \| 'inline' | No | Display mode (default: 'modal') | | type | 'ONRAMP' \| 'OFFRAMP' | No | Transaction type (onramp = buy, offramp = sell) | | amount | number | No | Fiat amount for onramp or crypto amount for offramp | | createSession | CreateSessionRequest | No | Full session configuration object | | sessionId | string | No | Resume an existing session | | theme | 'light' \| 'dark' \| 'auto' | No | Color theme (default: 'light') | | onSessionUpdate | (session) => void | No | Callback when session state changes | | onSuccess | (session) => void | No | Callback when transaction completes | | onError | (error) => void | No | Callback when an error occurs | | onClose | () => void | No | Callback when widget is closed (modal only) |

CreateSessionRequest

Full configuration object for creating a session:

type CreateSessionRequest = {
  type: 'ONRAMP' | 'OFFRAMP';
  walletAddress?: string;        // Required for onramp
  cryptoCurrency: string;        // e.g., 'USDT', 'USDC'
  cryptoNetwork: string;         // e.g., 'TRC20', 'ERC20'
  amount?: number;               // Fiat amount for onramp
  cryptoAmount?: number;         // Crypto amount for offramp
  countryCode: string;           // e.g., 'NG'
  currency: string;              // e.g., 'NGN'
};

Advanced Usage

Custom Container

For more control over where the widget renders:

import { mountPouchPayWidget } from '@pouchpay/widget';

const container = document.getElementById('my-custom-container');
const widget = mountPouchPayWidget({
  container,
  props: {
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    cryptoCurrency: 'USDT',
    cryptoNetwork: 'TRC20',
    apiKey: 'your-api-key'
  }
});

// Later, cleanup when done
widget.unmount();

Event Handling

Track session updates and handle completion:

<PouchPayWidget
  walletAddress="0x742d35..."
  cryptoCurrency="USDT"
  cryptoNetwork="TRC20"
  apiKey="your-api-key"
  onSessionUpdate={(session) => {
    console.log('Session status:', session.status);
    console.log('Current step:', session.nextStep);
  }}
  onSuccess={(session) => {
    console.log('Transaction completed!');
    console.log('Transaction hash:', session.txHash);
  }}
  onError={(error) => {
    console.error('Error:', error);
  }}
/>

Resuming Sessions

Resume an existing session by ID:

<PouchPayWidget
  sessionId="existing-session-id"
  apiKey="your-api-key"
/>

User Flow

Entry: User selects onramp (buy) or offramp (sell)
Configuration: Enter amount and confirm details
Email Verification: Submit email and verify with OTP code
KYC: Complete identity verification (one-time)
Payment (Onramp): Get bank account details and make transfer
Crypto Transfer (Offramp): Send crypto to provided address
Completion: Receive confirmation and transaction details

Theming & Customization

The widget supports light and dark themes:

<PouchPayWidget
  // ... other props
  theme="dark"
/>

More customization options coming soon.

TypeScript Support

This package is written in TypeScript and includes full type definitions:

import type { PouchPayWidgetProps, SavedBankAccount } from '@pouchpay/widget';

const config: PouchPayWidgetProps = {
  walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  cryptoCurrency: 'USDT',
  cryptoNetwork: 'TRC20',
  apiKey: 'your-api-key'
};

Getting an API Key

Visit https://dash.pouch.finance
Register and verify your email
Create a new API key in the dashboard
Use the test key for development and live key for production

Requirements

React: 18.0.0 or higher (including React 19)
React DOM: 18.0.0 or higher (including React 19)
Next.js: Compatible with all versions (App Router and Pages Router)

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

Examples

Check out the examples/ directory for complete working examples:

React with TypeScript
Next.js integration
Vanilla JavaScript
Vue.js integration

Troubleshooting

Widget not loading

Make sure you have React and ReactDOM loaded:

<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

Container not found error

Ensure you have a container element with the correct ID:

<div id="pouchpay-widget"></div>

TypeScript errors

Make sure you have the latest type definitions:

npm install --save-dev @types/react @types/react-dom

Support

📧 Email: [email protected]
📖 Documentation: https://docs.pouch.finance
💬 Discord: Join our community
🐛 Issues: GitHub Issues

License

MIT © PouchPay

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

Security

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker.

Made with ❤️ by the PouchPay team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@pouchpay/widget

Features

Supported Assets

Installation

npm

yarn

pnpm

Quick Start

React Integration

Next.js Integration

Vanilla JavaScript

Integration Modes

1. Minimal Configuration (Recommended)

2. Full Configuration

3. Hybrid Mode

API Reference

PouchPayWidgetProps

CreateSessionRequest

Advanced Usage

Custom Container

Event Handling

Resuming Sessions

User Flow

Theming & Customization

TypeScript Support

Getting an API Key

Requirements

Browser Support

Examples

Troubleshooting

Widget not loading

Container not found error

TypeScript errors

Support

License

Contributing

Security