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

# Interswitch API

Jentic publishes the only available OpenAPI specification for Interswitch API, keeping it validated and agent-ready. The Interswitch API exposes a focused payments surface for African card and account-based transactions: initiating a transaction, retrieving its status by transaction ID, and validating a payment instrument before debit. Authentication is an API key passed in the Authorization header. Interswitch is the dominant pan-African payment switch, and this spec covers the core transaction-creation and status-lookup flow used by merchants integrating its switching rails.

## For AI agents

Initiate Interswitch payments, validate payment instruments, and look up transaction status for African card and account flows.

## Scope

Does not handle refunds, payouts, biller listings, KYC, or dispute management - use for Interswitch transaction initiation, status lookup, and instrument validation only.

## Capabilities

- Initiate a payment transaction through the Interswitch switch with merchant and amount details
- Retrieve the status of a previously created transaction by its ID for reconciliation
- Validate a payment instrument or account ahead of debit to reduce decline rates
- Authenticate machine-to-machine calls using an API key in the Authorization header
- Operate against the Interswitch production base URL for live merchant integrations

## Use cases

### Nigerian E-Commerce Card Acceptance

Online merchants in Nigeria and other Interswitch markets accept card payments by calling POST /transactions with the order amount and customer details, then polling GET `/transactions/{id}` for the final status. The API key in the Authorization header authorises the merchant integration. Settlement and reconciliation happen against the same transaction ID returned at initiation.

Example prompt: Initiate an Interswitch transaction for NGN 25,000 against merchant MERCH001 with reference ORDER-44918 and store the returned transaction ID

### Pre-Debit Account Validation

Billers and recurring-payment platforms call POST /validation before debiting an account or card to confirm the instrument is active and chargeable, reducing the decline rate on the actual transaction. The validation endpoint returns the result without moving funds. This is particularly valuable for utility, telecom, and education-sector billers running large recurring batches.

Example prompt: Validate a customer card 5061-XXXX-XXXX-1234 against Interswitch ahead of an NGN 12,000 recurring debit and return the validation result

### Daily Transaction Reconciliation

Finance and ops teams reconcile the day's Interswitch transactions against internal order records by retrieving status for each known transaction ID through GET `/transactions/{id}.` Transactions that show settled status feed into accounting; pending or failed states feed back into the merchant retry or refund flow. The single-resource lookup pattern keeps the reconciliation script simple.

Example prompt: Loop through 1,200 transaction IDs from yesterday and call GET `/transactions/{id}`, then bucket each into settled, pending, or failed

### Agent-Driven Payment Recovery

An AI agent monitors failed Interswitch transactions, calls POST /validation against the underlying card or account to confirm whether the instrument is now active, and re-initiates the payment when validation succeeds. Jentic stores the API key in your Jentic One instance so the agent never sees the raw credential. Recovery loops that previously required manual ops review become an automated retry queue.

Example prompt: For each failed transaction in the last 24 hours, validate the underlying card and re-initiate the payment if validation returns active

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/transactions` | Initiate a payment transaction |
| GET | `/transactions/{id}` | Retrieve transaction status by ID |
| POST | `/validation` | Validate a payment instrument before debit |

## Key resources

- **Transactions** — Initiate payments and retrieve transaction status by ID
- **Validation** — Verify a payment instrument or account before debit

## Why Jentic

- **Setup:** Wiring the Interswitch API by hand means setting up its header API key and handling the specific transaction and validation payloads for each call. 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 initiates transactions and validation by sending the target in the request body, with the id appearing in the path only for status reads, so limit the agent to the operations it needs, such as initiating a transaction or checking its status. You choose the operations it may call, so instrument validation 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 'initiate an Interswitch transaction' or 'check transaction status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Interswitch API (interswitchgroup.com)** — Interswitch's group-domain endpoint covering payments, transfers, and billers
- **Flutterwave API** — Pan-African payment processor with broader product coverage versus Interswitch's switch core
- **Paystack API** — Developer-friendly Nigerian and African payment API versus Interswitch's switch-tier integration

## FAQ

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

Interswitch does not publish a public OpenAPI specification for this API surface. Jentic generates and maintains this spec so that AI agents and developers can call Interswitch 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 API use?

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

### Can I validate a card before charging it through the Interswitch API?

Yes. POST /validation takes the payment instrument details and returns whether the instrument is active and chargeable. Calling this before POST /transactions reduces decline rates on recurring debits and large-batch billing flows.

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

The OpenAPI spec does not declare numeric rate limits. Interswitch enforces per-merchant pacing on its production switch and rejects bursty traffic; treat HTTP 429 as the canonical signal and back off. Production limits are negotiated per merchant agreement.

### How do I initiate a transaction through Jentic?

Search Jentic for 'initiate an Interswitch transaction'. The SDK returns the POST /transactions operation with its input schema (merchant, amount, currency, reference). Run pip install jentic, await client.search('initiate an Interswitch transaction'), then await client.execute(...) with the transaction payload.

### Does the Interswitch API cover refunds?

This v1.0.0 spec exposes initiate, status lookup, and validation only - refunds are not represented in the three published endpoints. For refunds, use the merchant portal or the Interswitch Quickteller back-office flows until a dedicated refund endpoint is added to the spec.

### 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 Interswitch operations and credentials the agent may use, so you can grant only POST /transactions to initiate a payment and GET `/transactions/{id}` to read its status while withholding everything else. Instrument validation via POST /validation is not available to the agent unless you explicitly add it. Since Interswitch takes the payment target in the request body and only exposes the transaction id in the path for status reads, you scope access at the operation level rather than per record. The merchant API key stays in your own instance and is injected into the Authorization header only at execution time.