DEV Community: Chizurum Egwunwankwo

Building an E-Commerce Checkout with Interswitch Payment Gateway (Web Checkout) -

Chizurum Egwunwankwo — Fri, 10 Jul 2026 10:17:21 +0000

Take a customer from "Add to Cart" to a verified payment — including the failure cases the quickstart doesn't walk you through

You're building a checkout for an online store. A customer fills their cart, clicks "Pay," and from that moment a dozen things can happen, most of them fine, some of them not. They complete payment cleanly. They close the tab mid-OTP. Their card gets declined. Your callback fires but the money isn't actually real. A good checkout handles all of these, not just the success path.

This guide builds a complete e-commerce checkout on the Interswitch Payment Gateway using Web Checkout, then walks through the failure cases that separate a checkout that works in a demo from one that survives real customers.

A quick note on terminology before we start: Interswitch's Web Checkout has two integration methods: Inline Checkout (the payment popup opens over your page, no redirect) and Web Redirect (the customer is sent to Interswitch's payment page and back). We'll use Inline Checkout, since keeping the customer on your store is the better experience for e-commerce.

What We're Building

A checkout flow for an online store that:

Takes the customer's cart total and triggers an Interswitch payment
Handles the customer completing payment and the ways they don't
Verifies the payment server-side before fulfilling the order (the part that matters most)
Moves cleanly from test to production

Step 1 — Test Credentials

Parameter	Value
Merchant Code	MX6072
Pay Item ID	9405967
Client ID	IKIAB23A4E2756605C1ABC33CE3C287E27267F660D61
Secret	secret
Mode	TEST

When you go live, you'll generate your own.

Step 2 — Trigger Checkout From The Cart

For an e-commerce store, Inline Checkout is the right choice. The payment popup opens over your store, the customer never leaves your page, and the cart context stays intact.

Add the script:

<script src="https://newwebpay-sandbox.interswitchng.com/inline-checkout.js"></script>

Now wire it to your cart. The key move here is translating your cart total into what Interswitch expects:

function checkoutCart(cart) {
    // cart.total is in naira (e.g. 4500.00)
    // Interswitch expects kobo, so multiply by 100
    const amountInKobo = Math.round(cart.total * 100);

    // Generate a unique reference and store it against this order
    const txnRef = `order_${cart.orderId}_${Date.now()}`;

    window.webpayCheckout({
        merchant_code: "MX6072",
        pay_item_id: "9405967",
        txn_ref: txnRef,
        amount: amountInKobo,
        currency: 566,                          // NGN
        cust_email: cart.customerEmail,
        cust_name: cart.customerName,
        site_redirect_url: "https://yourstore.com/payment-complete",  // optional for inline; used by web redirect
        onComplete: (response) => handlePaymentResponse(response, cart.orderId, txnRef),
        mode: 'TEST'
    });
}

Two things here are the source of most real bugs, so take note of them:
Amount is in kobo. A ₦4,500 cart is 450000, not 4500. Convert at the boundary — Math.round(cart.total * 100) and never let naira leak into the API call.

txn_ref must be unique per attempt. Notice it includes both the order ID and a timestamp. The order ID alone isn't enough, because a customer might try to pay for the same order twice (first attempt failed, they retry). Each attempt needs its own reference, while still being traceable back to the order.

Step 3 — Handle What The Customer Actually Does

The quickstart shows you the success case. With real customers, it gets trickier. Here's the response handler that deals with reality:

function handlePaymentResponse(response, orderId, txnRef) {
    // resp === "00" indicates the customer completed the flow in the browser.
    // (Confirm the callback object's exact field names against a live test —
    //  see the note below.)
    if (response.resp === "00") {
        // Customer completed the flow — but DON'T fulfill yet.
        // Send to your server to verify before giving value.
        verifyAndFulfill(orderId, txnRef);
    } else {
        // Customer did not complete — declined, cancelled, or errored.
        // Do NOT fulfill. Show a retry option.
        showRetryOption(orderId, response.desc);
    }
}

A note on field names: Interswitch's Web Redirect response is documented to return resp (response code — 00 means approved), desc (description), apprAmt (approved amount), txnref, and retRef. The Inline onComplete callback receives a response object that mirrors these, but the docs don't enumerate its fields explicitly, so console.log(response) once in the sandbox and confirm the exact keys before you rely on them. Whatever the field names, the rule in Step 4 is unchanged: the callback is never your source of truth.

But there's a case the response handler alone can't catch: the customer who closes the tab mid-payment. If a customer starts the OTP step and then closes the popup, your onComplete callback may never fire. As far as your frontend knows, nothing happened, but the payment might have actually gone through on Interswitch's side.

This is exactly why you cannot rely on the callback as your source of truth, and why the next step exists.

Step 4 — Verify Server-Side (The Rule You Never Break)

This is the most important section in this guide.

Never fulfill an order based on the client-side callback alone.

The callback firing with a success code means the customer completed the payment flow in their browser. It does not, by itself, prove the money is real and in your account. Two reasons this matters for an e-commerce store specifically-

First, the abandoned-tab problem from above - the callback might never fire even when payment succeeded. Your server needs to be able to check independently.

Second, client responses can be manipulated. A malicious user can fake a success response to your frontend. If you ship goods on that alone, you've shipped for free.

So before you mark the order paid and trigger fulfillment, your server independently verifies the transaction with Interswitch using your merchant code, the transaction reference you stored, and the amount:

// On your server — verify before fulfilling
async function verifyAndFulfill(orderId, txnRef, expectedAmountInKobo) {
    const merchantCode = "MX6072";

    const response = await fetch(
        `https://sandbox.interswitchng.com/collections/api/v1/gettransaction.json` +
        `?merchantcode=${merchantCode}` +
        `&transactionreference=${txnRef}` +
        `&amount=${expectedAmountInKobo}`,
        {
            method: 'GET',
            headers: { 'Content-Type': 'application/json' }
        }
    );

    const result = await response.json();

    // ResponseCode "00" = approved. Always confirm the returned
    // Amount matches your order total before giving value.
    const isApproved = result.ResponseCode === "00";
    const amountMatches = Number(result.Amount) === expectedAmountInKobo;

    if (isApproved && amountMatches) {
        markOrderPaid(orderId);
        triggerFulfillment(orderId);
    } else {
        flagForReview(orderId, result.ResponseDescription);
    }
}

Two things to note about this verification call:

Auth on the requery. The simplified call above passes only the query parameters. Some Interswitch setups require an additional Hash header on the gettransaction.json requery (a SHA-512 hash of the requery string plus your secret key). Confirm against your Developer Console whether your integration needs it, and add it before going live if so.
The returned Amount is also in kobo. You're comparing your expectedAmountInKobo against Interswitch's Amount, both in the minor unit so don't accidentally compare naira to kobo and trigger a false mismatch.

Check the amount, not just the status. Verify not only that a payment happened, but that the amount paid matches the order total. A customer paying ₦100 for a ₦45,000 order is a payment that "succeeded" and one you must never fulfill. Confirm both that the money is real and that it's the right money.

The flow is always: customer's browser says "I think I paid" → your server confirms "yes, the money is real and it's the correct amount" → only then do you give value. Build this from day one. It's far harder to retrofit after you've been fulfilling on trust.

Step 5 — Complete a Test Payment

With the flow wired up, use Interswitch's test cards to run a payment in sandbox. Enter a test card in the popup, complete the OTP, and watch your handler fire. Then deliberately test the failure paths: cancel mid-flow, close the tab, use a declining test card. A checkout you've only tested on the success path is a checkout you haven't really tested.

Step 6 — Go Live

When test works and the failure cases are handled:

Generate your own credentials and replace the sandbox ones
Change the sandbox host to the live host (script: newwebpay.interswitchng.com; verification: webpay.interswitchng.com)
Set mode: 'LIVE'

The code doesn't change. only credentials, URL, and mode. What you tested is what ships.

A note on base URLs: Interswitch uses a few sandbox hostnames across their docs and plugins (sandbox.interswitchng.com, newwebpay-sandbox.interswitchng.com, and others). The ones used here match the current Web Checkout documentation, but always confirm the exact base URLs against your Developer Console before going live.

A Note on Transaction Verification

For the server-side verification step, you use the gettransaction.json endpoint to confirm status with Interswitch. One thing worth knowing as you architect this: the Transaction Search API does not currently cover IPG payments, so your verification uses IPG's own transaction status check (shown above), not Transaction Search. Keep those two systems distinct, they solve different problems.

Wrapping Up...

A real e-commerce checkout isn't the success path; it's the success path plus every way a customer can deviate from it. We built a flow that converts the cart correctly (kobo, unique references), handles the customer who completes payment and the one who closes the tab, and most importantly, verifies server-side that the money is real and the amount is right before shipping a single item.

The one rule, again, because it's the one that matters: the browser says "I paid," your server confirms "the money is real and correct," and only then do you fulfill.

Resources

Building checkout with Interswitch? Join the Interswitch Developer Community on Slack, share what you're building and get help from developers who've shipped it.

Building an Automated POS Settlement Monitor with Interswitch Transaction Search

Chizurum Egwunwankwo — Tue, 30 Jun 2026 17:04:50 +0000

If you run a business with POS terminals - a retail chain, a string of agent locations, a payments business with terminals in the field, you know the evening ritual. Transactions came in all day. Now you need to know which ones actually settled, which are still pending, and whether the money that hit your account matches what your terminals reported.

This guide does that. We'll build an automated settlement monitor using the Interswitch Transaction Search API; one that takes your terminals, finds the day's transactions, and tells you exactly what settled and what didn't.

On Coverage

Before we write a line of code, you need to know what Transaction Search actually covers, because building on the wrong assumption wastes your time.
Per Interswitch's transaction coverage, here's what's fully supported today:

Transaction Type	Transaction	Settlement
Purchase (POS & Web)	Full	Full
Transfer (ATM & POS)	Full	Full
Cash Withdrawal	Full	Full
Agency Banking	Full	Partial
Quickteller Transfers	Partial	Partial

The two types we'll build on - POS Purchase and POS Transfer - have full transaction and settlement coverage. That's deliberate. It means every reconciliation lookup in this guide returns complete data.

One thing to note: Interswitch Payment Gateway (IPG) purchases are not currently covered by Transaction Search. If you're verifying IPG web checkout payments, that's a different flow. Transaction Search is built for transactions that flow through the switch: POS, ATM, cash withdrawal, transfers.

What We're Building

A settlement monitor that does three things:

Authenticates against Interswitch Passport for an access token
Searches each terminal's transactions for a given day
Pulls full settlement details for each transaction and flags anything not yet settled

By the end you'll have a function you can drop into a cron job that runs every evening and emails you a settlement report.

Step 1 - Setup Your Project

Get your credentials first:

Create an account on the Interswitch Developer Console
Set up a Project and select Transaction Search from the available APIs
A test Client ID and Secret Key are generated for you

Step 2 - Authentication

Every Transaction Search call needs a Bearer token, obtained by exchanging your Client ID and Secret against the Interswitch Passport endpoint. Tokens are short-lived - cache and refresh rather than requesting one per call.

javascript
// auth.js
async function getAccessToken(clientId, secret) {
    const credentials = Buffer.from(`${clientId}:${secret}`).toString('base64');

    const response = await fetch('https://passport-sandbox.interswitchng.com/passport/oauth/token ', {
        method: 'POST',
        headers: {
            'Authorization': `Basic ${credentials}`,
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: 'grant_type=client_credentials&scope=profile'
    });

    const data = await response.json();
    return data.access_token;
}

Step 3 - Find A Terminal's Transaction

This is where the POS case study comes alive. Quick Search lets you find transactions by terminal_id, exactly the field you have for every one of your POS devices. Combine it with a date and you get every transaction that terminal processed that day.

Field	Description	Notes
terminal_id	Identifies a terminal belonging to a merchant	8 chars — you have this for every device
merchant_code	Uniquely identifies a registered merchant	12 chars
stan	Transaction number from the terminal	6 digits
rrn	Retrieval Reference Number	12 digits
masked_pan	Card number (first 6 + last 4 visible)	16–19 digits
transaction date	The date the transaction occured (YYYY-MM-DD)	used in quick start
transaction_amount	Amount in lower denomination (₦20 → 2000)

Two rules that catch everyone: use transaction_date (YYYY-MM-DD), and transaction_amount is in the lower denomination — ₦200 is 20000, not 200.

// findTerminalTransactions.js
async function searchByTerminal(token, clientId, terminalId, date) {
    const response = await fetch(
        'https://switch-online-gateway-service.k9.isw.la/switch-online-gateway-service/api/v1/gateway/quick-search?page_size=20&page_number=1',
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${token}`,
                'ClientId': clientId,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                terminal_id: terminalId,
                transaction_date: date          // per docs (YYYY-MM-DD)
            })
        }
    );

    return await response.json();
}

Handling a full day of transactions

A busy terminal does more than 20 transactions a day, and search caps at 20 per page (page_size can't exceed 20). The response tells you totalPages — loop through page_number until you've covered them all.

async function getAllTerminalTransactions(token, clientId, terminalId, date) {
    let all = [];
    let pageNumber = 1;
    let totalPages = 1;

    do {
        const res = await fetch(
            `https://switch-online-gateway-service.k9.isw.la/switch-online-gateway-service/api/v1/gateway/quick-search?page_size=20&page_number=${pageNumber}`,
            {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'ClientId': clientId,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ terminal_id: terminalId, transaction_date: date })
            }
        );
        const page = await res.json();
        if (page.data) all = all.concat(page.data);

        totalPages = page.totalPages || 1;
        pageNumber++;
    } while (pageNumber <= totalPages);

    return all;
}

Step 4 - Pull Settlement Details

Search tells you a transaction happened. To know whether the money settled, take the transaction_id and call Get Transaction Details.

javascript
// getDetails.js
async function getTransactionDetails(token, clientId, transactionId) {
    const response = await fetch(
        `https://switch-online-gateway-service.k9.isw.la/switch-online-gateway-service/api/v1/gateway/transaction?transaction_id=${transactionId}`,
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${token}`,
                'client_id': clientId,
                'Content-Type': 'application/json'
            }
        }
    );
    return await response.json();
}

The response breaks into four blocks. For settlement reconciliation, the first two are what you need:

json
{
    "data": [{
        "globalOutputData": {
            "category": "PURCHASE",
            "amount": "210000",
            "transactionDate": "2023-10-09T17:47:35.240",
            "transactionStatus": "COMPLETED",
            "settlementDate": "2023-10-10",
            "settlementStatus": "SETTLED"
        },
        "transactionData": {
            "terminalId": "20573ZLY",
            "stan": "373758",
            "channel": "POS",
            "rrn": "696843517287",
            "responseCode": "00",
            "responseMessage": "Approved or completed successfully",
            "merchantCode": "2057LA200002957"
        },
        "settlementData": {
            "settlementBreakdownList": [ /* fee breakdown by party */ ],
            "settlementDataAvailable": true
        }
    }]
}

The globalOutputData block answers the two questions your reconciliation is really asking: transaction status (did the payment complete?) and settlement status (did the money move?).

The Insight That Saves You: Transaction Status and Settlement Status Are Different

This is the single most important thing in this guide.

A POS transaction can be COMPLETED but PENDING SETTLEMENT. The customer's card was charged, the purchase succeeded, your terminal printed "approved" but the money has not yet landed in your settlement account.

These are two independent facts.

The most common reconciliation mistake is treating "transaction succeeded" as "money received." They are not the same, and the gap between them is exactly what you're monitoring for. A transaction stuck in PENDING SETTLEMENT for longer than expected is the thing you want flagged.

The statuses you'll see:PENDING, COMPLETED, REVERSED Settlement status: SETTLED, PENDING SETTLEMENT, NO SETTLEMENT, UNSUPPORTED
And within the transaction data, the response code maps cleanly: 00 is approved, 09 (or none) is pending, anything else (91, 06, 51...) is a failure.

Putting It Together: The Settlement Monitor

Here's the whole thing: give it your terminals and a date, get back a clean settlement report flagging anything that hasn't settled:

javascript
async function runSettlementMonitor(clientId, secret, terminalIds, date) {
    const token = await getAccessToken(clientId, secret);
    const report = { settled: [], pending: [], failed: [], notFound: [] };

    for (const terminalId of terminalIds) {
        const transactions = await getAllTerminalTransactions(token, clientId, terminalId, date);

        if (!transactions.length) {
            report.notFound.push(terminalId);
            continue;
        }

        for (const txn of transactions) {
            const details = await getTransactionDetails(token, clientId, txn.transaction_id);
            const record = details.data[0].globalOutputData;

            const entry = {
                terminalId,
                amount: record.amount,
                transactionStatus: record.transactionStatus,
                settlementStatus: record.settlementStatus,
                settlementDate: record.settlementDate
            };

            if (record.settlementStatus === "SETTLED") {
                report.settled.push(entry);
            } else if (record.transactionStatus === "COMPLETED") {
                report.pending.push(entry);   // completed but not yet settled — watch these
            } else {
                report.failed.push(entry);
            }
        }
    }

    return report;
}

// Run it every evening for all your terminals
const report = await runSettlementMonitor(
    clientId, secret,
    ["20573ZLY", "20577C9O", "2TEP5C7W"],
    "2023-10-09"
);

console.log(`Settled: ${report.settled.length}`);
console.log(`Pending settlement (watch these): ${report.pending.length}`);
console.log(`Failed: ${report.failed.length}`);

Drop that into a cron job, pipe the output into an email or a Slack webhook, and you've automated reconciliation. The pending bucket is one to watch, those are completed transactions whose money hasn't landed yet.

When A Transaction Isn't Found

Interswitch is explicit that Transaction Search hasn't reached 100% coverage. If a POS transaction you know exists doesn't come back, treat the 404 as "not found in search" rather than "doesn't exist," and reconfirm through the Interswitch Help Desk. Build that into your notFound handling rather than letting it break the run.

Wrapping Up

We took three API calls: authenticate, search by terminal, get settlement details, and turned them into an automated settlement monitor for a POS business.

The key isn't any single call. It's the insight that transaction status and settlement status are different questions, and that the gap between them is exactly what reconciliation is about.

Resources:

Running POS terminals and building reconciliation tooling? Join our community on Slack and share what you're building.

A Guide To Using The Interswitch API Marketplace

Chizurum Egwunwankwo — Wed, 18 Feb 2026 08:40:20 +0000

Two weeks ago, we invited developers from the Interswitch developer community to a build night. The goal was to show - not just tell - the capabilities of our API Marketplace and how it makes discovery and consumption easier. In 3 hours, we had 5 completed projects.

This isn't just about the event - it's about the purpose of the marketplace: making API discovery easier and integrations seamless.

Why Marketplaces Matter: Solving Discovery and Fragmentation

Marketplaces solve more than just the discovery problem. They're the solution to fragmentation.

Think about the traditional developer experience:

Multiple API providers for different services
Separate accounts and credentials for each
Different authentication schemes
Scattered documentation
No centralized billing

The Interswitch API Marketplace changes this.

It's a one-stop shop that brings all the APIs you need into one central place. You no longer have to juggle different providers, create multiple accounts, or manage separate credentials for different APIs needed to build one product.

Key Benefits:

Centralized Discovery: Browse all available APIs in one place
Unified Authentication: One OAuth 2.0 scheme for all APIs
Single Sign-Up: One account, one dashboard, one wallet

APIs On The Marketplace

The Interswitch API Marketplace currently hosts 20+ APIs across 3 categories, with more coming soon.

Here's what's available, what each does, and what you can build with it:

A. Identity & Verification APIs

Bank Account Verification API: For authenticating bank details and verifying account ownership.
BVN Full Details API: Verification and validation of a Bank Verification Number (BVN) in real-time with complete customer information.
BVN Boolean Match API: Verify the existence and validity of a BVN in real-time (returns true/false without full details).
NIN API: Verification API that confirms and verifies a person's National Identity Number.
NIN Full Details API: Authentication and confirmation of a NIN in real-time with complete personal information.
Physical Address API: Validates and verifies customer-provided addresses by checking them against authoritative databases.
TIN API: Tax-focused API that authenticates Tax Identification Numbers
Domestic AML Search API: Helps businesses screen individuals against local anti-money laundering watchlists.
Driver's License Verification API: A verification API that confirms and verifies a person's Driver's License Number with the full details.
Driver's License Boolean Match API: Verify the existence and validity of a person's Driver's License Number in real-time (returns true/false without full details).
Facial Comparison API: The Facial Comparison API provides a secure and efficient way for businesses to verify a person's identity by comparing the similarity between two different images.
International Passport Lookup API: Enables businesses verify the validity of an individual's international passport details.
Credit History API: Enables businesses to retrieve comprehensive credit reports of individuals directly from Nigeria's leading credit bureau.
Global Search AML API: Helps businesses screen individuals against international anti-money laundering watchlists.

B. Transaction & Payment APIs

Bills Payment API:Offers the capability to integrate features cable TV subscriptions, utility bills, government services, airtime/data, and more into your application.

C. Security & Business APIs

Generate SafeToken API: The SafeToken OTP API provides secure multi-factor authentication and transaction verification for your application.
CAC API: Leverages the Corporate Affairs Commission (CAC) database to enable businesses to retrieve detailed information about a business or company registered with CAC including the company directors, shareholders and secretary.

And many others.

Next, I'll take you through the developer tools we have on the marketplace to make integration hassle-free.

Developer Tools

We prioritized developer experience to make integration simple, easy, and seamless. Here are the tools available for developers on the marketplace -

1. Postman Collection (Test Before You Code):

Not ready to code yet? Explore what APIs return before integrating.

Our pre-built Postman collection includes:

All API endpoints pre-configured
Example requests for common use cases
Environment variables template

How to use:

Visit any API page in the marketplace
Click "Test on Postman"
Import collection to Postman
Add your API keys to environment variables
Click "Send" to make test calls

Perfect for: Understanding API behavior, debugging issues, prototyping before coding.

2. Sandbox Environment:

Every API has a separate sandbox for testing:
Unlimited requests (no charges)
Test data provided (test BVNs, NINs, account numbers)
Separate keys from production (can't accidentally process real transactions)

Some of the test data provided include:

BVN Full Details: 11111111111
NIN Full Details: 11111111111
Drivers License: AAA00000AA00

3. Documentation (Your integration guide):

Our documentation contains guides, code snippets you can easily copy and troubleshooting guides to make integration seamless. It contains search functionality so you can find what you need fast.

To get the documentation for any API of your choice -

Visit the marketplace
Select the API of your choice
On the menu, click on ''Endpoint''. You'll find all you need for integration - code snippets, success response, error response, Postman credentials, etc

Documentation for all APIs on the marketplace can be found here.

4. Developer Support (Humans Who Actually Help):

If you get stuck while building, we've provided these support channels to help get you unblocked:

Slack Community: (7k+ developers): Real-time help from our support engineers and other developers in our community. The average response time is 5minsand you can join the community using this link.
Office Hours: If you prefer to speak with our developers directly, our monthly live sessions were created for this purpose. You can ask anything, debug live, learn best practices. Become a part of the community to know the timeline for each month and book a meeting.

The sections below explains how to get started - from account creation to going live.

Getting Started: From Sign-Up to First API Call in 15 Minutes

Let's walk through the process of getting started from creating an account, a project, getting API credentials, making your first call and viewing logs.

STEP 1: Create Your Account

Visit https://developer.interswitchgroup.com/marketplace
Click "Sign Up" (top right)
Enter email address, first name, last name, and password
Accept privacy policy & terms and conditions
Click "Create Account"
Check your email for verification link
Click the verification link

And, you're in.

The next step will be to create your first project.

STEP 2: Create Your First Project

Think of a project as a container for the APIs you want to use.

After logging in, click "Create Project"
Select "New Project" and fill in: A. Project Name: e.g., "My Identity Verification App" B. Description: e.g., "Testing BVN verification for KYC"
Select APIs: Choose the APIs you need

Click "Create Project"

The system generates test credentials (Client ID and Client Secret) for your project.

STEP 3: Get Your API Credentials

Click on your newly created project
Navigate to "Test Keys" tab
You'll see: Client ID: IKIA8574C7FB56… (example) Client Secret: ••••••••• (click "Show" to reveal)

⚠️ CRITICAL SECURITY RULE:
Never commit API keys to GitHub. Always use environment variables.

STEP 4: Make Your First API Call (10 minutes)
Let's make a real API call. I'll show you using cURL

Using cURL (Quick Test)
Step I: Get an access token

# Base64 encode your credentials
CREDENTIALS=$(echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64)

# Get access token
curl -X POST https://sandbox.interswitchng.com/passport/oauth/token \
  -H "Authorization: Basic $CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile"
}

Step II: Make an API call (example: BVN verification)

# Replace YOUR_ACCESS_TOKEN with the token from step 1
curl -X POST https://sandbox.interswitchng.com/api/v1/identity/bvn \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "22222222226"
  }'

STEP 5: View API Call Logs (Monitor Your Usage)
After making API calls, track them in your dashboard. Here's how:

Log in to the marketplace
Navigate to "Reports" section
View: A. Request: What you sent to the API B. Response: What the API returned C. HTTP Status: 200 (success), 400 (client error), 500 (server error) D. Timestamp: When the call was made E. API Endpoint: Which API you called

You can filter by:
A. Date range
B. API endpoint
C. Response status (success/failure)

You can download reports for reconciliation or debugging.

What Happens Next: From Sandbox to Production

You've made your first API call. Here's the path from testing to production:

Phase 1: Build & Test (Sandbox)

Integrate API into your application
Test all scenarios (success, failure, edge cases)
Test with multiple data points
Deploy to staging environment

Phase 2: Request to Go Live
When you're ready for production:

Click on your project in the dashboard
Select the API you want to go live with
Click "Go Live" button
System displays business onboarding requirements
Submit all required documents
Compliance reviews your request (usually within 1–3 business days)
Production keys issued upon approval by our Compliance team

Fund Your Wallet (For Production)

Once you've tested in sandbox and you're ready to go live:

Navigate to "Wallet" section
You'll see an account number assigned to you
Transfer funds from your bank app to this account number
Refresh the wallet page → Balance updates automatically
API calls deduct from this balance

Transaction tracking:

Credits: Wallet funding, failed call reversals
Debits: Successful API consumption

Phase 3: Production Launch

Switch from sandbox keys to production keys in your .env:

Update these values

ISW_PRODUCTION URL= use this production url
ISW_CLIENT_ID=production_client_id_here
ISW_CLIENT_SECRET=production_client_secret_here

After switching to production -

Your application will process real transactions.
Monitor usage in dashboard
Fund wallet to avoid service interruption
Set up monitoring and alerts

Start Building

If you're ready to start experimenting with the APIs:

Create your free account:[https://developer.interswitchgroup.com/marketplace]
Read the full documentation:([https://developer.interswitchgroup.com/]

Whether you're building a fintech product, onboarding users, or automating verification flows — the marketplace is designed to help you ship faster with fewer moving parts.

Happy Building!

How Interswitch Payment Gateway Works

Chizurum Egwunwankwo — Tue, 16 Sep 2025 13:29:25 +0000

Interswitch’s Payment Gateway (IPG)]offers a unified, end-to-end solution for both online and in-store transactions designed to meet the needs of technically savvy developers as well as non-technical business owners / merchants. Irrespective of who you are - a fintech founder building a custom checkout flow or a merchant looking for a simple, easy-to-use plug and play, IPG delivers reliability, security and flexibility.

Throughout this blog post, we’ll refer to Interswitch payment gateway as simply, IPG.

Two Approaches To Integrating With Interswitch Payment Gateway
There are 2 main ways to integrating with IPG; online payments and in-store payments.

Let’s explore these options

1. Online payments:
This method of integration into IPG is easy for both developers who are technically savvy and non-developers who simply want plug and play. Developers and Merchants have the options of taking the technical path for online payments (card APIs & hosted fields) and the non-technical options (web checkout & technical fields).

A. Technical Integration Options For Online Payments

- Card APIs:
Direct RESTful APIs let you control every aspect of the payment flow. A PCI-DSS (Payment Card Industry Data Security Standard) certification and PSSP (Payment Solution Service Provider License) is needed, but with this integration method, you have — complete control over UI & UX and a faster processing time.
This method is best for businesses with in-house technical teams who need full control

- Hosted Fields:
This is a customizable payment form elements that live within a website while maintaining security. This type of integration offers benefits such as customization options (colors, typography, borders and responsiveness) and secure integration (PCI compliance without burden). This is best for businesses that want brand consistency while maintaining PCI compliance without redirecting customers off-site.

It is important to note that both card APIs and hosted fields require technical expertise but offer different levels of control and PCI compliance requirements.

B. Non-technical Integration Options For Online Payments

- Web Checkout:
This is a ready-to-use payment page hosted by Interswitch. This option requires no technical expertise; just configure your branding, and you’re ready to accept payments in minutes. Interswitch handles all PCI compliance.

- Hosted Fields:
Customizable form elements that live within your website while maintaining security. Key benefits include — full Customization (match your website’s design seamlessly), secure Integration (PCI compliance without technical burden) and seamless UX (your customer stays on your website throughout).

Note that the web checkout and hosted field options both require minimal technical knowledge and can be set up quickly through the Interswitch merchant portal or with simple embed codes.

2. Instore Payments:

A. For Technically Savvy Users:

- POS Purchase APIs:
Integrate directly with payment processing for real-time, customizable in-store transactions. This method requires PCI DSS compliance, a PSSP license, and technical expertise.

- Android POS SDK:
Use ready-made components for card-present transactions, lifecycle management, and error handling.

Benefits: Full UX control, custom integrations, enterprise-grade security, and optimized performance.

B. For Non-Technical Users:

- POS Terminals:
Plug-and-play devices pre-installed with Interswitch software. Benefits include: no technical setup, automated settlement, instant reporting and lifetime maintenance.

IPG Supported Payment Methods
Interswitch Payment Gateway offers comprehensive online and offline payment options. These include card payments, pay with transfer, USSD and digital wallets.

Key benefits of using these payment available through IPG include but are not limited to pan African coverage, enhanced security, a unified integration process and a robust, consolidated reporting.

IPG-supported payment options and benefits.
Beyond the robust online and offline payment methods, Interswitch also offers POS devices for in-store payment hardware solutions. Benefits include, 24/7 technical support, multi-currency support, remote updates and devices are PCI PTS certified.

There are also in person payment solutions for businesses with IT resources and technically-savvy personnel as well as in person solutions for non-technical users.

Requirements for the POS purchase APIs are PCI DSS compliance, a PSSP license and tech expertise. The documentation for the Android POS SDK can be accessed on the quickteller business website. These devices offers these benefits to businesses — complete UX control, custom integration paths, enterprise-grade security and optimized performance.

To get started with POS terminals simply signup, request for POS, choose the devices you need, receive your terminal and begin to use it!

B. In-person Payment Solutions (For Non-Technical Users)

Non-technical users can maximize Interswitch’s ready-to-use POS terminals with pre-installed Interswitch software. For this in-person payment option, no technical setup or integration is required. Merchants also get automatic settlement (funds in your account the next day) and transaction reports, instant reporting (so they can track sales in real time), fraud protection and a lifetime maintenance (both hardware and software support).

Beyond this, onboarding is super easy! To get started, contact our sales team then select your preferred terminal model, go on to complete your merchant application and receive configured terminal within days.

Payment types accepted for this option are credit and debit cards, mobile wallets, QR payments, contactless and apply pay.

The terminal options for the in-person payment solutions include - countertop (fixed -location terminals), mobile POS (wireless connectivity), smart POS (android-based system) and integrated (POS + cash register).

In the next blog post, I’ll take a deep dive into IPG advanced features like split settlements, recurring billing, and analytics, as well as the resources for merchants and developers.

Get started with Interswitch Payment Gateway, here.