JavaScript SDK

The @supa/pay-sdk is the easiest way to integrate Supapay into your web application. It handles the payment iframe, security handshakes, and event handling.

Installation

Via NPM

pnpm add @supa/pay-sdk

Via CDN

<script src="https://js.supa.pay/v1/sdk.js"></script>

Usage (token-based, recommended)

Create a payment intent on your backend (via the Supapay API), then open the hosted experience for the returned token. No amount or keys are passed from the browser.

import { SupaPay } from '@supa/pay-sdk';

// `token` comes from your backend after creating a payment intent.
const handle = SupaPay.open({
  token: 'pay_xxxxxxxxxxxxxxxx',
  // payUrl: 'https://pay.yourhost.com', // optional; defaults to NEXT_PUBLIC_PAY_URL
  onSuccess: ({ token, reference }) => {
    console.log('Paid:', token, reference);
    // Settlement is also confirmed server-side via webhook. This is just UX.
  },
  onClose: () => console.log('User dismissed the modal'),
  onError: (err) => console.error(err),
});

// Programmatically close if needed:
// handle.close();

SupaPay.open renders ${payUrl}/pay/{token} in a modal iframe and bridges PAYMENT_SUCCESS / WIDGET_CLOSE / PAYMENT_ERROR messages to your callbacks. It returns a handle with a close() method. The backdrop click and Escape also close it.

Usage (legacy key/amount widget)

1. Setup

Initialize the SDK with your Public Key. You can find your keys in the Supapay dashboard.

import { SupaPay } from '@supa/pay-sdk';

const pay = SupaPay.setup({
  key: 'pk_test_your_key_here',
  amount: 15000, // Amount in NGN
  currency: 'NGN',
  email: 'customer@example.com',
  onSuccess: (reference) => {
    console.log('Transaction Complete:', reference);
    // Verify transaction on your backend
  },
  onClose: () => {
    console.log('User closed the widget');
  }
});

2. Trigger Checkout

Call the .open() method when your user is ready to pay.

document.getElementById('checkout-btn').addEventListener('click', () => {
  pay.open();
});

Configuration Options

Option	Type	Description
key	string	Your Supapay public key.
amount	number	The amount to charge in kobo (or major unit depending on config).
currency	string	Currency code (e.g., NGN).
email	string	Customer email address.
onSuccess	function	Callback triggered after successful payment.
onClose	function	Callback triggered when the widget is closed.

Event Handling

The SDK uses window.postMessage internally to communicate with the iframe. You do not need to handle this manually unless you are building a custom wrapper.