Skip to main content
The FLEX Web SDK (FlexOneTap) drops a FLEX payment option into any website. You load one script, initialize it with your merchant credentials, and call open() when the customer is ready to pay — FLEX renders the checkout experience and hands control back to your callbacks when the customer finishes, fails, or closes it.

No APIs required

The SDK runs entirely in the browser. You only need your merchant ID and API key.

Framework agnostic

Plain HTML, React, and Next.js examples are all covered below.
Estimated Time: 10-15 minutesPrerequisites:
  • A FLEX business account at business.yourflexpay.com
  • A settlement bank added to that account
  • A frontend you can add a <script> tag to

Integration Steps

1

Get Your API Credentials

Add a settlement bank, generate an API key, and copy your merchant ID from the business portal.
2

Load the SDK

Add the FLEX CDN script to your page.
3

Initialize the SDK

Create a FlexOneTap instance with your credentials.
4

Open the Checkout

Call open() with the transaction details and handle the callbacks.
5

Confirm and Go Live

Verify payments server-side, then switch to your production key.

Step 1: Get Your API Credentials

Everything you need for the SDK comes from the FLEX business portal.
1

Add a settlement bank

Log in at https://business.yourflexpay.com, then go to Settings → Settlement Bank → Add Settlement Bank.This is where FLEX pays out the money you collect, so add it before you start collecting payments.
2

Generate an API key

Open the API Keys tab. Copy your Merchant ID, then click Generate API Key and copy the key as well.
The API key is shown once, at generation time. Save it somewhere safe before you leave the page — if you lose it you will have to generate a new one.
3

Set your webhook and redirect URLs (optional)

Open the Webhook tab and enter your Webhook URL and Redirect URL.Both are optional for an SDK-only integration — the SDK’s onSuccess callback already tells your frontend the payment went through. Set the webhook URL anyway if you want a server-side notification you can trust for reconciliation, since callbacks in the browser can be missed if the customer closes the tab.
You should now have two values:

Step 2: Load the SDK

Add the FLEX CDN script to your page:
Once it loads, the SDK is available on window.FlexOneTap.
The script must finish loading before you call new window.FlexOneTap(...). In plain HTML, put the tag in <head> or before your own script. In React and Next.js, use the patterns in the React and Next.js sections below, which wait for the load event.

Step 3: Initialize the SDK

Constructor options

string
required
Your merchant ID from the API Keys tab of the business portal.
string
required
The API key you generated in the API Keys tab.
boolean
default:"false"
Enables verbose SDK logging in the browser console. Turn it on while integrating, off in production.
Create the instance once and reuse it for every checkout rather than constructing a new one per click.

Step 4: Open the Checkout

Call open() when the customer clicks your pay button:

open() options

string
required
Your own unique reference for this transaction. Use it to match the payment back to an order on your side — generate a fresh one per attempt and keep it unique.
number
required
Amount to collect, in NGN.
string
A short description shown to the customer during checkout, e.g. the order or invoice number.
number
How long the payment stays valid, in minutes. After it elapses the payment expires and the customer has to start again.
function
Called when the payment completes successfully. Use it to show a confirmation and update your UI.
function
Called when the payment fails. Use it to show an error and let the customer retry.
function
Called when the customer dismisses the checkout without completing payment. Use it to re-enable your pay button.

Plain HTML Example

The smallest complete integration:
index.html

React Example

In React, the script has to be loaded before the first open() call, and the component tree may mount before the script does. A small hook handles both: it injects the tag once, waits for load, and hands back a ready-to-use instance.
onClose fires when the customer dismisses the checkout, including right after a successful payment in some flows. Guarding it with status === 'pending' keeps a close event from wiping out a success state you already set.

Next.js Example

Next.js ships next/script, which loads the SDK once per page and gives you an onLoad hook — no manual DOM injection needed. The checkout itself touches window, so it has to live in a Client Component.

Environment variables

.env.local
NEXT_PUBLIC_* variables are inlined into the browser bundle, and so is anything the Web SDK needs — the merchant ID and API key are visible to anyone who views source. That’s inherent to a browser SDK, so treat this key as a public, checkout-only credential: never reuse a key that has broader Merchant API access here, and rotate it from the API Keys tab if you suspect misuse.

Step 5: Confirm and Go Live

  • The script loads and window.FlexOneTap is defined
  • The checkout opens on click
  • onSuccess fires and your UI updates after a completed payment
  • The payment shows up in the business portal
  • onClose fires when the customer dismisses the checkout
  • onError fires on a failed payment and the customer can retry
  • A payment left open past duration expires as expected
  • Double-clicking the pay button doesn’t open two checkouts
  • Your webhook URL is set in the Webhook tab
  • Your backend verifies the payment by reference before fulfilling the order
  • Duplicate webhook deliveries for the same reference are handled idempotently
  • debug is false
  • Settlement bank is set in Settings → Settlement Bank
  • Production merchant ID and API key are in your production environment variables

Troubleshooting

Your code ran before the CDN script finished loading. Initialize inside the script’s load event (onLoad in next/script, the hook in the React example) rather than at module scope.
Set debug: true and check the browser console. Most cases are a wrong merchantId/apiKey pair, or an amount that isn’t a number.
Strict Mode mounts effects twice in development. The hook above reuses the existing <script> tag and guards with cancelled, so it’s safe — if you wrote your own loader, make sure it doesn’t inject the script twice.
That’s expected if your backend never heard about it. onSuccess is browser-side only — set the webhook URL in the Webhook tab, or poll the payment by reference from your server.

Next Steps

Integration Guide

Server-side integration with the Merchant API

Payment Requests

Look up and manage payments by reference

Authentication

How Merchant API credentials work

Overview

Merchant API overview

Need Help?