DEV Community: Interswitch Developer Community

llms.txt Changed How I Integrate APIs: A Reton Case Study With Interswitch VAS

Gabriel R Mogaji — Wed, 30 Sep 2026 23:20:24 +0000

I build Reton, a trust-first digital wallet for Africa. Our flagship is Callback Protection: hold a payment, release it when you are ready, or raise a callback, with a timeline a person can actually follow.

A wallet that only moves money between Reton IDs is incomplete. People still buy airtime, data, electricity, and television. If they have to leave Reton to pay those bills, the balance stops feeling like money they can live on. Value Added Services had to sit on the same ledger we already treat as the source of truth.

I was not looking for a bank. I was looking for a payments rail. Interswitch is a payments company. Reton is the wallet. That sentence is the architecture. AI coding tools keep trying to smear it.

This is how Interswitch's llms.txt, Markdown documentation URLs, and reference pages changed the way I integrate APIs in Cursor, and how Reton still refuses to let a model invent payment behaviour.

The problem

Reton already owned customer wallets, Reton IDs, available and held balances as projections of a double-entry ledger, PIN-gated money movement, protected transfers, callbacks, and wrong-transfer recovery.

What we did not need to rebuild was a nationwide biller directory. Interswitch Quickteller VAS already reaches cable, electricity, telecom airtime and data, and related categories. Using that rail is a product decision. Treating that rail as the wallet is a design error.

The constraint was integration quality under time pressure, while pairing with an AI coding tool. I needed the correct VAS documents (bills payment is not airtime e-pins, and neither is send-money), those documents as clean text rather than a rendered marketing site, and a money path the model was not allowed to invent: debit the Reton ledger inside a database transaction, talk to Interswitch only through a gateway.

The old method was five browser tabs, a paste into chat, and hope the model still remembered which product the last URL belonged to. The better method is a machine-readable map of the documentation site, then one Markdown page at a time.

That map is llms.txt.

Wallet versus rail

If you skip this distinction, you will ship a demo, not a wallet.

Reton is the digital wallet: balances, Callback Protection, recovery, and the double-entry ledger.

Interswitch is the payments partner: cards, transfers, and bill payments underneath. It is not a bank. It is not Reton's ledger.

The only call chain I accept for bills:

Next.js /bills
  → POST /api/v1/bills/pay          (BillController: HTTP only)
    → BillPayService
        → PIN, KYC limits, fraud
        → LedgerService.debitAvailable
        → InterswitchGatewayInterface.payBill
        → LedgerService.creditAvailable   (clear rail decline only)
  → { "data": ... } or { "error": { "code", "message" } }

I will not take provider HTTP from a controller or from the browser, mutate Wallet balances outside LedgerService, or grant success because a query string contains resp=00.

Amounts on the ledger are kobo integers. The web app sends naira. The API converts and rejects bills under ₦100.

What `llms.txt` actually is

Interswitch publishes a documentation index at docs.interswitchgroup.com/llms.txt. It is a plain-text catalogue: titles, links, and short descriptions. It is not sitemap XML, not a blog post, and not a substitute for OpenAPI.

The same file tells you to append .md to a documentation URL to receive the page as Markdown. Those two conventions are instructions for humans and for models. I treat them as part of the integration.

I do not paste the whole index into every prompt. I fetch it once, pick a short list of URLs from the catalogue, then fetch those as .md.

Without the index, an agent searches the open web, mixes Quickteller versions, and invents paths with a straight face. With the index, the agent starts from Interswitch's own catalogue.

HTML documentation pages are built for browsers: navigation, scripts, theme wrappers. Models spend tokens on chrome. Markdown pages are built for reading. I stopped pasting HTML URLs into AI chats for Interswitch work.

How I actually pull the docs

I keep a vendor-notes folder, not a second brain for the model.

mkdir -p docs/vendor-notes/interswitch

curl -fsSL https://docs.interswitchgroup.com/llms.txt \
  -o docs/vendor-notes/interswitch/llms.txt

If the file starts with <!doctype, I did not get the index. I stop. I do not "remember Interswitch VAS" from training data and keep going.

Then I search the saved file for VAS language (bill, airtime, biller, voucher) and write matching Markdown URLs to a short list. For Reton that list is usually:

Value Added Services overview
Bills payment
Airtime recharge, virtual top-up
Airtime e-pins, only if we are actually issuing pins
Get billers, billers by category, biller payment item, biller categories
Customer validation
Create bill
VAS response codes

I copy those URLs from the saved index. Interswitch can rename a slug. The customer validation page in the live catalogue is customer-validation-1.md, not a guessed customer-validation.md. There is no query-transaction page in that index. Status for our funding requery lives under collections (transaction requery, get transaction status), which is a different product surface than Quickteller VAS.

I also keep send-money, card checkout, and the payments-section Pay Bill page out of a bills prompt. Pay Bill in the card/checkout guides is not Create Bill in VAS. The Bank API bills guide is written for banks. Reton is not a bank. Mixing those in one chat is how the agent wires the wrong endpoint.

Each fetch looks like this:

curl -fsSL \
  "https://docs.interswitchgroup.com/docs/value-added-services-overview.md" \
  -o docs/vendor-notes/interswitch/pages/vas-overview.md

The first heading should be the document title. If I see a theme shell, I refetch with .md. I attach one guide and one reference for the current task. Electricity this week means the bills guide plus customer validation plus payment item, not the e-pins guide.

Before any PHP, I make the agent fill a field sheet and cite the saved filename on every row: payment code, customer id, amount, request reference, terminal id. If it cannot cite a file, the row is not done. Payment codes and terminal ids come from merchant config and secrets, never from the browser, never from git.

Discovery and implementation are separate turns. A prompt I actually use:

Read the saved llms.txt and the .md pages I attached.
Interswitch is a payments company, not a bank, and not Reton's wallet. Reton owns balances and the double-entry ledger.
Do not search the public web for Interswitch VAS. Do not invent paths.
Do not write gateway code in this turn.

When implementation starts, I name the files it may touch:

backend/src/Wallet/BillPayService.php
backend/src/Controller/Api/V1/BillController.php
backend/src/Gateway/Interswitch/InterswitchGatewayInterface.php
backend/src/Gateway/Interswitch/HttpInterswitchGateway.php
backend/src/Gateway/Interswitch/NullInterswitchGateway.php
backend/src/Ledger/LedgerService.php (read; do not casually rewrite)
backend/tests/ApiV1Test.php

I refuse unbounded prompts such as "add Interswitch," "make bills like Opay," or "use whatever Quickteller endpoint you remember."

The money path

LedgerService is the only code allowed to change wallet balances. Bills are not a new accounting primitive. They are a debit of customer liability, then a rail result.

BillPayment stores wallet, biller category, customer reference, amount in kobo, payment code, and the idempotency key. We look that key up before any debit. If a row exists, we return it. Double-clicks are normal. The ledger cannot absorb them.

After PIN, KYC, and fraud checks, the rest runs inside a Doctrine transaction:

LedgerService::debitAvailable with kind bill_reserve and journal id bill-reserve:{reference}.
InterswitchGatewayInterface::payBill(paymentCode, customerId, amountKobo, reference).
If approved (ResponseCode 90000 on the HTTP gateway): mark completed, audit, return.
If the rail returns a clear decline: creditAvailable with kind bill_reverse, mark failed, throw provider_failed.

The controller never sees Interswitch JSON. The HTTP gateway maps provider fields into { approved, reference, raw_code } and posts to /quickteller/v1/transactions. NullInterswitchGateway always returns 90000 so tests and local UI can move. Empty live credentials must not be described as a live rail. The container still has to bind InterswitchGatewayInterface to the HTTP gateway in production. Compiling HttpInterswitchGateway is not the same as using it.

One gap I will not paper over: the first bills cut treats any non-approval, including a transport error, as a decline and reverses. That is safe only when Interswitch has actually said no. A timeout after the HTTP call left our process is not a decline. The correct next cut is to leave the bill pending with the reserve in place, then requery. BillPayment already has a pending status. pay() does not leave a row there yet.

If you later move the HTTP call outside the database transaction, you need that same pending path. Do not "optimise" by deleting the reverse on a documented decline.

Audit logs run after the journal. Audit is evidence. It is not the balance.

I want PHPUnit to prove the money path, not only HTTP 201: fund a wallet, POST /api/v1/bills/pay with Idempotency-Key, assert the Null happy path completes, replay the same key with no second debit, then force a provider failure and assert available balance is restored. Those bill cases are not in ApiV1Test yet. A green suite that never touches /bills/pay does not prove this.

The HTTP API

VAS on Reton sits at /bills.

GET /api/v1/bills returns our catalogue: airtime, data, electricity, TV, internet. It is not a live proxy of Interswitch's biller directory. The labels exist so the app can render tiles. Payment codes stay on the server.

POST /api/v1/bills/pay is a money POST.

Gates, in order:

Authentication. No User, 401 unauthenticated. There is no public pay endpoint for a nicer demo.

Idempotency-Key. Trim the header. Empty means 422. The Next.js moneyApi() helper always sends a UUID. The server still rejects a missing header so a future mobile client cannot skip it.

Body. biller, customer_reference (max 40), positive amount in naira, optional pin. Convert with (int) round(amount * 100). Reject below 10000 kobo.

PIN. If the user has a transaction PIN, verify it. Failure is 403 invalid_pin, not 500. If they have not set a PIN yet, PinService does not invent a requirement.

KYC. KycService::assertWithinLimits applies. A bill is a money movement. It is not exempt because it is "just airtime."

Fraud. FraudService::assess with bill_payment and amount_kobo. A hard block is fraud_blocked.

Everything maps to { "error": { "code", "message" } }. The browser never receives a raw Interswitch body.

On the client, submit through moneyApi, show structured errors, refresh the wallet on success. Never put the PIN in a query string.

Identifiers the server may trust

This is where models sound most confident and do the most damage.

Customer reference. Airtime and data take an MSISDN. Electricity takes a meter number. TV takes a smartcard / IUC. Internet takes an account id. Trim, reject empty, cap length. Do not send a meter number down an airtime path because the field was named accountNumber. Electricity and TV should run customer validation before debit. The first Reton slice still forwards the typed string. That is a known gap, not a finished inquiry flow.

Payment codes. Payment items are issued to your merchant in that environment. They are not global constants. Sandbox codes are not production truth.

Reton currently keeps category placeholders in BillPayService::BILLERS (90101 through 90105) so local and test have a string to send. Those values are not live Quickteller items. Production codes come from the Quickteller dashboard for that environment, stored in secrets, keyed by catalogue id. If the map is missing in production, fail closed. Do not send a placeholder to the live rail. If Cursor "remembers" a DSTV code from training data, discard it.

Amounts. Many airtime top-ups are customer-chosen: the user types naira, the server converts to kobo, then applies min/max, KYC, and available balance. Many electricity tokens and bouquet renewals are inquiry-defined: validate the customer, take the item or amount Interswitch returned, and debit that figure. If the JSON body disagrees with the inquiry, reject the pay request.

Reton's first bills slice still accepts body amounts for every category. Electricity and TV should move to inquiry-defined amounts before live volume. I would rather write that gap down than pretend the model closed it.

Request references. The saved bills payment guide is the source for length, charset, and merchant prefix. We generate one value, use it on the ledger (bill-reserve:{reference}), and send it as requestReference on payBill. Unique UUIDs are not the same as accepted rail identifiers. Current Reton references look like BP- plus hex. That is our generator, not a claim that every Quickteller environment will accept it.

The implementation prompt gets these refusals:

Do not invent payment codes.
Do not invent requestReference formats.
Do not debit an amount that did not pass server rules.
If the saved guide is silent, ask. Do not guess.

Requery, pending, and frontend lies

Bills that return a synchronous approve or decline are the easy case. Rails also return pending, drop packets, or send the user through a browser. The rule is the same for VAS, card, and wallet pay:

Never grant wallet value because the frontend said so.

resp=00 in a query string is not a ledger permission.

Sources of truth, in order:

Server requery of Interswitch with the reference you stored.
A signed webhook, verified before any handler mutates state.
Your BillPayment row plus ledger journals. If those disagree with (1) or (2), the journals win for the customer balance, and ops reconciles the rail.

The browser is not on this list.

Rail view	Bill status	Ledger
Approved	completed	Debit remains
Documented decline	failed	Reverse posted once
Pending or timeout after debit	pending	Debit remains; worker requeries
Unknown	do not complete	Do not reverse until requery says decline

InterswitchGatewayInterface::requery lives on the gateway, not in the controller. On Reton today that method is wired for collections-style status (/collections/api/v1/gettransaction) and used when we settle funding. It is not yet a bills worker selecting unfinished BillPayment rows. I am describing the rule we already enforce for deposits, and the rule bills must inherit before we treat timeouts as declines.

POST /api/v1/webhooks/interswitch is public. We verify X-Interswitch-Signature on the raw body first (HMAC-SHA512), then decode JSON. Unsigned bodies are allowed only when the webhook secret is empty and the kernel is in debug. Production must not run that way. The handlers behind that route currently settle funding and virtual-account inbound, not bills. A VAS webhook that credits a bill without matching a reserved journal would be a new, explicit path, not a side effect I would let the model "reuse."

I reject diffs that credit a wallet in Next.js because searchParams.resp === '00', trust window.location for amount, or skip requery because "the SDK said success."

If a bill is pending, the UI says it is being confirmed. The current bills page says "payment successful" after a 201. That is honest only while pay() refuses to return pending.

What the model got wrong

llms.txt did not cause these mistakes. It made the right documents easy to attach, which made the mistakes easier to catch.

It treated Interswitch as the bank. Early drafts said Interswitch held customer balances. Wrong. Blur that in copy and you will blur it in the domain model.

It invented requestReference formats. The model emitted ULIDs because they look unique. Quickteller bill payments are pickier. Unique is not accepted.

It trusted the client for amounts. Lookup-based bills need a server-side inquiry. The model's first instinct is still "take amount from the body."

It assumed payment codes are universal. Codes are merchant- and environment-specific. A hard-coded code the model "remembers" is a smell.

It mixed product surfaces. Create Bill, Pay Bill, Bank API, and collections requery all mention bills or transactions. They are not interchangeable. The index is how I keep them apart.

What I will not merge

I run this as a human. Models will tick boxes they did not earn.

The saved llms.txt has to be plain text. In-scope pages have to be the .md files from that index, not a send-money or card guide dropped into a bills task. Copy never calls Interswitch a bank, and never describes Reton as only a frontend over Interswitch.

On money: the controller has no provider HTTP, debit happens before payBill, a documented decline reverses the same kobo amount, idempotent replay does not double-debit, PIN and KYC and fraud still run, timeouts are not stored as completed, and no Next.js route grants balance from query params.

Going live is a separate question from "it compiles." Secrets stay out of git. Production payment codes replace 90101-90105. The webhook secret is set and unsigned debug is off. Simulate funding is off. The Null gateway is not the production port.

cd backend && php vendor/bin/phpunit --colors=always

That command is necessary. For bills, it is not sufficient until the suite actually posts /api/v1/bills/pay.

Closing

I used to think "AI-friendly documentation" meant nicer sentences. Interswitch showed me it is closer to infrastructure: an index the agent can fetch, pages it can read without HTML noise, and contracts it can respect.

llms.txt did not replace engineering judgment on Reton. It removed the scavenger hunt, so judgment could stay on the part that matters: real money, moving correctly, for real people.

Start at docs.interswitchgroup.com/llms.txt. Append .md to the VAS, bills, or airtime page you need. Attach the reference page for field shape. Keep your own ledger rules stricter than the model's optimism.

Reton is live at retonpay.com.

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.

DEV Community: Interswitch Developer Community

llms.txt Changed How I Integrate APIs: A Reton Case Study With Interswitch VAS

The problem

Wallet versus rail

What llms.txt actually is

How I actually pull the docs

The money path

The HTTP API

Identifiers the server may trust

Requery, pending, and frontend lies

What the model got wrong

What I will not merge

Closing

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

What We're Building

Step 1 — Test Credentials

Step 2 — Trigger Checkout From The Cart

Step 3 — Handle What The Customer Actually Does

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

Step 5 — Complete a Test Payment

Step 6 — Go Live

A Note on Transaction Verification

Wrapping Up...

Resources

Building an Automated POS Settlement Monitor with Interswitch Transaction Search

On Coverage

What We're Building

Step 1 - Setup Your Project

Step 2 - Authentication

Step 3 - Find A Terminal's Transaction

Handling a full day of transactions

Step 4 - Pull Settlement Details

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

Putting It Together: The Settlement Monitor

When A Transaction Isn't Found

Wrapping Up

What `llms.txt` actually is