canonical: https://jentic.com/apis/interswitchgroup.com/interswitchgroup

# Interswitchgroup Interswitch API

Jentic publishes the only available OpenAPI specification for the Interswitch API on the interswitchgroup.com domain, keeping it validated and agent-ready. This four-endpoint surface covers initiating a payment, retrieving transaction status, sending a transfer, and listing billers for bill-payment flows across Interswitch's African network. Authentication is an API key passed in the Authorization header. The interswitchgroup.com domain is Interswitch's parent group endpoint; it shares the same payment switch but exposes additional transfer and biller capabilities versus the narrower interswitch.com transaction surface.

## For AI agents

Initiate Interswitch payments and transfers, list billers, and look up transaction status across the group's African payment network.

## Scope

Does not handle refunds, KYC, dispute management, or card issuing - use for Interswitch group payment initiation, transfers, biller listings, and status lookup only.

## Capabilities

- Initiate a payment through the Interswitch group switch with merchant and amount details
- Retrieve a payment's status by transaction ID for reconciliation and customer-support flows
- Send a funds transfer between accounts on the Interswitch network
- List supported billers for utility, telecom, and government bill-payment integrations
- Authenticate machine-to-machine calls using an API key in the Authorization header

## Use cases

### Fintech Wallet Outbound Transfers

African fintech wallets that allow users to send money to other accounts call POST /transfers with the recipient details and amount, then track settlement status against the returned reference. The endpoint authorises against the merchant API key in the Authorization header. This is the core plumbing behind in-app 'send money' features for Nigerian and West African neobanks.

Example prompt: Send an Interswitch transfer of NGN 75,000 from wallet WLT001 to recipient account 0123456789 at bank code 058 with reference TRF-99821

### Bill Payment Aggregator

Bill-payment aggregators surface Interswitch's biller catalogue to end users by calling GET /billers, then initiating the customer's payment through POST /payments with the chosen biller's reference. The /billers endpoint returns the supported utility, telecom, education, and government billers. Aggregators avoid maintaining a hard-coded biller list by reading it directly from Interswitch.

Example prompt: List all Interswitch billers, filter for electricity utilities, and return the biller code for Eko Electricity Distribution

### Merchant Reconciliation

Merchants reconcile each day's Interswitch payments by retrieving status for known transaction IDs through GET `/payments/{transactionId}.` Settled payments feed accounting; pending or failed states drive customer follow-up or retry. The single-resource lookup keeps reconciliation scripts predictable across high-volume days.

Example prompt: Retrieve status for 500 payment transaction IDs from yesterday and emit a CSV bucketing each into settled, pending, or failed

### Agent-Driven Bill Pay Assistant

An AI agent helps consumers pay bills by interpreting a natural-language request ('pay my Ikeja electricity bill of 12,000 naira'), calling GET /billers to find the biller code, then POST /payments with the customer's wallet and the resolved biller. Jentic stores the API key in your Jentic One instance and injects it at execution time, so the agent never sees the raw credential.

Example prompt: Resolve the biller code for 'Ikeja Electric' via GET /billers and initiate a payment of NGN 12,000 from wallet WLT001 against that biller

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Initiate a payment |
| GET | `/payments/{transactionId}` | Retrieve payment status by transaction ID |
| POST | `/transfers` | Send a funds transfer |
| GET | `/billers` | List supported billers |

## Key resources

- **Payments** — Initiate payments and retrieve status by transaction ID
- **Transfers** — Send funds between accounts on the Interswitch network
- **Billers** — List supported billers for bill-payment integrations

## Why Jentic

- **Setup:** Wiring the Interswitch group API by hand means setting up its header API key and tracking the payments, transfers, and billers paths yourself. Through Jentic you install once, import the Interswitch API from the API Directory, store the merchant key once, and your agent calls it.
- **Permission scoping:** Interswitch group initiates payments and transfers by sending the target in the request body, with the transaction id in the path only for status reads, so limit the agent to the operations it needs, such as sending a transfer or listing billers. You choose the operations it may call, so payment initiation is not included unless you add it.
- **Credential handling:** Your Interswitch merchant API key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a transfer through Interswitch' or 'list billers', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without choosing between /payments and /transfers manually.

## Related APIs

- **Interswitch API (interswitch.com)** — Narrower transaction-and-validation surface on Interswitch's primary domain
- **Flutterwave API** — Pan-African payment processor with broader product coverage than the Interswitch switch surface
- **Paystack API** — Developer-friendly Nigerian payment API versus the Interswitch group's switch-tier integration

## FAQ

### Why is there no official OpenAPI spec for the Interswitch group API?

Interswitch does not publish a public OpenAPI specification for this surface. Jentic generates and maintains this spec so that AI agents and developers can call the Interswitch group API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Interswitch group API use?

It uses API-key authentication. Pass the merchant API key in the Authorization header (the spec defines an apiKey scheme named ApiKeyAuth at 'header' position 'Authorization'). Through Jentic, the key is stored in your Jentic One instance and injected at execution time.

### Can I send transfers between accounts with this API?

Yes. POST /transfers accepts the source and destination details with an amount and reference, returning a transaction reference. This is the endpoint behind wallet-to-wallet and wallet-to-bank send-money flows in fintech apps using the Interswitch network.

### What are the rate limits for the Interswitch group API?

The OpenAPI spec does not declare numeric rate limits. Interswitch enforces per-merchant pacing on its production switch; treat HTTP 429 as the canonical signal and back off. Higher throughput is negotiated as part of the merchant agreement.

### How do I list billers through Jentic?

Search Jentic for 'list Interswitch billers'. The SDK returns the GET /billers operation. Run pip install jentic, await client.search('list Interswitch billers'), then await client.execute(...) - no input parameters are required for the basic listing.

### How does this differ from the interswitch.com API?

Both expose the same Interswitch payment switch under different group domains. The interswitch.com surface in this corpus exposes 3 transaction-only endpoints (initiate, status, validate); the interswitchgroup.com surface adds /transfers and /billers for transfer and bill-payment flows, totalling 4 endpoints.

### Can I limit what my agent is allowed to do with the Interswitch API?

Yes. Because you run Jentic One yourself, your own rules decide which of the four Interswitch operations the agent may call, so you can allow it to list billers with GET /billers and check status with GET `/payments/{transactionId}` while withholding POST /transfers and POST /payments. Since payment initiation and transfers send the target account and amount in the request body, keeping those operations off the agent's allowed list means it cannot move funds even if a prompt asks it to. Your stored merchant API key is injected only for the operations you have permitted, so the agent's reach is exactly the set of endpoints you grant it.