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.
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.Step 2: Load the SDK
Add the FLEX CDN script to your page:window.FlexOneTap.
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.
Step 4: Open the Checkout
Callopen() 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 firstopen() 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 shipsnext/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
Step 5: Confirm and Go Live
✅ Test the happy path
✅ Test the happy path
- The script loads and
window.FlexOneTapis defined - The checkout opens on click
-
onSuccessfires and your UI updates after a completed payment - The payment shows up in the business portal
✅ Test the unhappy paths
✅ Test the unhappy paths
-
onClosefires when the customer dismisses the checkout -
onErrorfires on a failed payment and the customer can retry - A payment left open past
durationexpires as expected - Double-clicking the pay button doesn’t open two checkouts
✅ Confirm server-side
✅ Confirm server-side
- Your webhook URL is set in the Webhook tab
- Your backend verifies the payment by
referencebefore fulfilling the order - Duplicate webhook deliveries for the same
referenceare handled idempotently
✅ Go live
✅ Go live
-
debugisfalse - Settlement bank is set in Settings → Settlement Bank
- Production merchant ID and API key are in your production environment variables
Troubleshooting
window.FlexOneTap is undefined
window.FlexOneTap is undefined
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.The checkout doesn't open
The checkout doesn't open
Set
debug: true and check the browser console. Most cases are a wrong merchantId/apiKey pair, or an amount that isn’t a number.Nothing appears in React Strict Mode
Nothing appears in React Strict Mode
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.onSuccess fires but the order isn't confirmed
onSuccess fires but the order isn't confirmed
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?
- Email: developers@yourflexpay.com