Embed / CDN

The @sanwohq/embed package bundles the entire Sanwo SDK (all providers included) into a single script you can drop onto any HTML page. It works everywhere — static sites, CMS pages, landing pages, no-code platforms, or anywhere you can add a <script> tag.

Add the script

<script src="https://cdn.jsdelivr.net/npm/@sanwohq/embed/dist/sanwo.global.js"></script>

That’s it. The script exposes window.Sanwo and auto-initializes any payment buttons on the page.

Zero-code: data attributes

Add a button with data-sanwo-* attributes — no JavaScript required:

<button
  data-sanwo-provider="paystack"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-amount="500000"
  data-sanwo-currency="NGN"
  data-sanwo-email="customer@example.com"
>
  Pay ₦5,000
</button>

When clicked, the checkout opens automatically. The script scans for all [data-sanwo-provider] elements on page load.

Available data attributes

Attribute	Required	Description
data-sanwo-provider	Yes	paystack, flutterwave, razorpay, monnify, interswitch, or custom
data-sanwo-key	Yes	Your provider’s public/publishable key
data-sanwo-amount	Yes*	Amount in minor units (kobo, cents, paise). Not required when using data-sanwo-custom-amount
data-sanwo-currency	Yes	ISO 4217 currency code (NGN, USD, GHS, etc.)
data-sanwo-email	Yes*	Customer email. Not required when using data-sanwo-custom-amount (an input is shown instead)
data-sanwo-first-name	No	Customer first name
data-sanwo-last-name	No	Customer last name
data-sanwo-phone	No	Customer phone number
data-sanwo-description	No	Payment description
data-sanwo-reference	No	Custom reference (auto-generated if omitted)
data-sanwo-callback	No	Name of a window function to call with the result
data-sanwo-debug	No	Set to "true" for console logging
data-sanwo-custom-amount	No	Set to "true" to show an amount input form
data-sanwo-template-url	No	URL to a custom provider template (when provider is custom)
data-sanwo-template	No	Inline custom provider template HTML

Handling the result

Option 1: Callback function

<script>
  function handlePayment(result) {
    if (result.status === 'successful') {
      window.location.href = '/thank-you?ref=' + result.reference;
    }
  }
</script>

<button
  data-sanwo-provider="paystack"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-amount="500000"
  data-sanwo-currency="NGN"
  data-sanwo-email="customer@example.com"
  data-sanwo-callback="handlePayment"
>
  Pay ₦5,000
</button>

Option 2: DOM events

<script>
  document.addEventListener('sanwo:complete', function(e) {
    console.log('Payment result:', e.detail);
    // e.detail.status: "successful" | "cancelled" | "failed" | "pending"
  });
</script>

Custom amounts

Let customers enter their own payment amount — perfect for donations, tips, or pay-what-you-want products. Add data-sanwo-custom-amount="true" and Sanwo renders a styled amount input form automatically:

<div
  data-sanwo-provider="paystack"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-currency="NGN"
  data-sanwo-email="donor@example.com"
  data-sanwo-custom-amount="true"
  data-sanwo-button-text="Donate"
  data-sanwo-placeholder="Donation amount"
></div>

The form renders a currency-aware input field (with the correct symbol), an error display, and a pay button. Amounts are entered in major units (e.g., 5000 for ₦5,000) and automatically converted to minor units for checkout.

Custom amount attributes

Attribute	Required	Description
data-sanwo-custom-amount	Yes	Set to "true" to enable the amount form
data-sanwo-currency	No	Currency code (default: NGN). Determines the symbol shown
data-sanwo-email	No	If omitted, an email input field is shown
data-sanwo-min-amount	No	Minimum allowed amount (major units)
data-sanwo-max-amount	No	Maximum allowed amount (major units)
data-sanwo-placeholder	No	Input placeholder (default: “Enter amount”)
data-sanwo-button-text	No	Button label (default: “Pay Now”)

All standard attributes (data-sanwo-provider, data-sanwo-key, data-sanwo-callback, etc.) work with custom amounts too.

Example: donation with limits

<div
  data-sanwo-provider="paystack"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-currency="NGN"
  data-sanwo-custom-amount="true"
  data-sanwo-min-amount="500"
  data-sanwo-max-amount="1000000"
  data-sanwo-button-text="Donate Now"
  data-sanwo-placeholder="How much would you like to give?"
  data-sanwo-callback="onDonation"
></div>

<script>
  function onDonation(result) {
    if (result.status === 'successful') {
      alert('Thank you for your donation!');
    }
  }
</script>

Styling the form

The form uses BEM-style class names you can override:

.sanwo-amount-form { /* form container */ }
.sanwo-amount-input-wrapper { /* input row with currency symbol */ }
.sanwo-currency-symbol { /* ₦, $, £ prefix */ }
.sanwo-amount-input { /* the number input */ }
.sanwo-email-input { /* email input (when shown) */ }
.sanwo-amount-error { /* validation error text */ }
.sanwo-pay-button { /* submit button */ }

Custom provider templates

Use any payment gateway — not just the built-in five — by providing your own provider template. This brings the full power of custom providers to the no-code embed.

Via data attributes

Set data-sanwo-provider="custom" and point to your template with data-sanwo-template-url:

<button
  data-sanwo-provider="custom"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-template-url="https://example.com/my-provider-template.html"
  data-sanwo-amount="500000"
  data-sanwo-currency="NGN"
  data-sanwo-email="customer@example.com"
>
  Pay with My Gateway
</button>

The template is fetched when the button is clicked. See the custom providers guide for how to write templates.

Custom provider attributes

Attribute	Required	Description
data-sanwo-template-url	Yes*	URL to fetch the HTML template from
data-sanwo-template	Yes*	Inline HTML template string
data-sanwo-provider-id	No	Custom provider ID (default: “custom”)
data-sanwo-provider-name	No	Custom provider name
data-sanwo-amount-in-minor-unit	No	Set to "false" if your provider expects major units

* Provide either data-sanwo-template-url or data-sanwo-template.

Via JavaScript

<script>
  // With inline template
  var sanwo = Sanwo.create({
    provider: 'custom',
    publicKey: 'pk_test_xxxxx',
    template: '<!DOCTYPE html>...',  // your provider template HTML
    providerId: 'my-gateway',
  });

  // With template URL (async)
  var sanwo = await Sanwo.createAsync({
    provider: 'custom',
    publicKey: 'pk_test_xxxxx',
    templateUrl: 'https://example.com/my-provider-template.html',
  });
</script>

Registering reusable providers

Register a custom provider once and reference it by name everywhere:

<script>
  Sanwo.registerProvider('my-gateway', Sanwo.createCustomProvider({
    template: '<!DOCTYPE html>...',
    id: 'my-gateway',
    name: 'my-gateway',
    displayName: 'My Gateway',
    amountInMinorUnit: true,
    supportedCurrencies: ['USD', 'NGN'],
  }));
</script>

<!-- Now use it like any built-in provider -->
<button
  data-sanwo-provider="my-gateway"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-amount="500000"
  data-sanwo-currency="NGN"
  data-sanwo-email="customer@example.com"
>
  Pay with My Gateway
</button>

Custom amounts + custom providers

Both features work together:

<div
  data-sanwo-provider="custom"
  data-sanwo-key="pk_test_xxxxx"
  data-sanwo-template-url="https://example.com/my-provider-template.html"
  data-sanwo-currency="USD"
  data-sanwo-custom-amount="true"
  data-sanwo-button-text="Pay"
></div>

Programmatic usage

For more control, use the JavaScript API:

<script>
  var sanwo = Sanwo.create({
    provider: 'paystack',
    publicKey: 'pk_test_xxxxx'
  });

  document.getElementById('pay-btn').addEventListener('click', async function() {
    var result = await sanwo.checkout({
      amount: 500000,
      currency: 'NGN',
      customer: {
        email: 'customer@example.com',
        firstName: 'John',
        lastName: 'Doe'
      },
      description: 'Premium Plan'
    });

    if (result.status === 'successful') {
      alert('Paid! Reference: ' + result.reference);
    }
  });
</script>

Sanwo.create(config)

Option	Type	Required	Description
provider	string	Yes	Provider name or "custom" for custom templates
publicKey	string	Yes	Provider public key
debug	boolean	No	Enable console logging
timeout	number	No	Checkout timeout in ms (default: 120000)
containerId	string	No	Custom container element ID
template	string	No	HTML template for custom providers
providerId	string	No	Custom provider ID
providerName	string	No	Custom provider name
amountInMinorUnit	boolean	No	Whether the custom provider expects minor units (default: true)

sanwo.checkout(options)

Returns a Promise<CheckoutResult>. See CheckoutOptions and CheckoutResult for full details.

Amount format

Amounts are always in minor units:

Currency	Unit	Example
NGN	kobo	₦5,000 → 500000
USD	cents	$50.00 → 5000
GHS	pesewas	GH₵100 → 10000
INR	paise	₹500 → 50000
KES	cents	KSh 1,000 → 100000

Available providers

Provider	ID	Regions
Paystack	paystack	Nigeria, Ghana, South Africa, Kenya
Flutterwave	flutterwave	Africa-wide
Razorpay	razorpay	India
Monnify	monnify	Nigeria
Interswitch	interswitch	Nigeria
Custom	custom	Any — bring your own template

Using with npm

If you prefer a module import (e.g., in a bundled project):

npm i @sanwohq/embed

import { create, createAsync, registerProvider, createCustomProvider } from '@sanwohq/embed';

const sanwo = create({
  provider: 'paystack',
  publicKey: 'pk_test_xxxxx'
});

// Custom provider from URL
const custom = await createAsync({
  provider: 'custom',
  publicKey: 'pk_test_xxxxx',
  templateUrl: 'https://example.com/my-template.html',
});