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

# Flutterwave Payments API

Jentic publishes the only available OpenAPI specification for Flutterwave Payments API, keeping it validated and agent-ready. Flutterwave is a payment platform serving Africa and global merchants who need to accept local payment methods at scale. The v4 Payments API exposes endpoints for creating customers, attaching payment methods, processing card charges, and initiating direct transfers. Authentication is bearer-token based, with separate sandbox and production hosts.

## For AI agents

Create customers, charge cards, and initiate transfers in Africa and globally through Flutterwave's v4 Payments API.

## Scope

Does not handle accounting, tax filing, or KYC document verification - use for Flutterwave card charges, payment method vaulting, and direct transfers only.

## Capabilities

- Create customer records with contact and KYC details
- Attach reusable payment methods to a customer profile
- Charge a payment method for a one-time transaction
- Look up the status of a charge by ID
- Initiate direct transfers to bank accounts or wallets
- Switch between sandbox and production via the servers list

## Use cases

### Accept Card Payments in Africa

Process one-time card charges through POST /charges, attaching the payment method created via /payment-methods to the customer record from /customers. Flutterwave handles local card networks, 3D Secure, and currency conversion across NGN, GHS, KES, ZAR, and global cards. Integration takes a few days end to end including webhook handling and reconciliation.

Example prompt: Create a customer, attach a payment method, and post a charge of NGN 5000 to that payment method via POST /charges, then read the status from GET `/charges/{charge_id}.`

### Direct Bank Transfers

Use POST /direct-transfers to send funds from a Flutterwave balance to a bank account or wallet. Suits payouts for marketplaces, gig platforms, and refund flows that need to push money out rather than pull it in. Each transfer references the destination account details and an amount in the source currency.

Example prompt: Initiate a direct transfer of NGN 25000 via POST /direct-transfers to a specified Nigerian bank account and return the transfer reference.

### Customer and Payment Method Vaulting

Create a customer through POST /customers, then attach payment methods via POST /payment-methods so subsequent charges can reference the saved instrument. This pattern keeps card data out of your servers while letting users pay with one click on repeat purchases. Customer records also support tax IDs and address data needed for compliance.

Example prompt: Create a customer with email 'user@example.com', attach a tokenized card via POST /payment-methods, and return the new payment method ID.

### AI Agent Payments via Jentic

Agents use Jentic's intent search to find the Flutterwave charge endpoint, load its schema, and execute calls under a scoped credential. This is the recommended pattern for assistants that take payment actions on behalf of a user - for example, processing a re-bill or initiating a refund. Jentic keeps the bearer token isolated.

Example prompt: Use Jentic to search 'process a card charge on Flutterwave', load the POST /charges schema, and charge the customer's saved payment method for the requested amount.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/customers` | Create a customer record |
| POST | `/payment-methods` | Attach a payment method to a customer |
| POST | `/charges` | Create a charge against a payment method |
| GET | `/charges/{charge_id}` | Look up a charge by ID |
| POST | `/direct-transfers` | Initiate a direct transfer to a bank or wallet |

## Key resources

- **Customers** — Create and look up customer records with KYC and contact details.
- **Payment Methods** — Attach reusable cards, bank accounts, or wallets to customers.
- **Charges** — Create and look up card charges by ID.
- **Transfers** — Initiate direct transfers to external bank accounts or wallets.

## Why Jentic

- **Setup:** Wiring the Flutterwave API by hand means managing its bearer secret key, choosing between the live host and the sandbox host, and building your own retry and error handling for payment calls. Through Jentic you install once, import Flutterwave from the API Directory, store the secret key once, and your agent calls it.
- **Permission scoping:** Flutterwave carries the customer and payment details in the request body rather than the URL path, so scoping is operations-only: you limit the agent to the operations it needs, such as creating a customer or reading a charge, and leave out charging a card or sending a direct transfer unless you add them. Every operation the agent can run is one you chose.
- **Credential handling:** Your Flutterwave secret key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a card charge on Flutterwave', and Jentic returns the POST /charges operation with its input schema so the agent supplies the right amount, currency, and payment method without browsing the reference docs.

## Related APIs

- **Paystack API** — Africa-focused payment gateway with strong Nigerian and Ghanaian coverage.
- **Stripe API** — Global payment platform with deeper feature coverage outside Africa.
- **SendGrid Mail API** — Email delivery for receipts and payment confirmations.

## FAQ

### Why is there no official OpenAPI spec for Flutterwave Payments API?

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

The Flutterwave v4 API uses HTTP bearer authentication with a secret key issued from the Flutterwave dashboard. Jentic stores the secret encrypted in your Jentic One instance and constructs the Authorization: Bearer header on outbound calls.

### Can I charge a saved payment method with the Flutterwave Payments API?

Yes, POST /charges accepts a customer ID and a payment method ID created via POST /payment-methods. After the charge is created, GET `/charges/{charge_id}` returns the final status.

### What are the rate limits for the Flutterwave Payments API?

The OpenAPI spec does not declare explicit rate limits. Flutterwave applies per-account throughput limits in production - back off on 429 responses and contact Flutterwave support to raise limits for high-volume merchants.

### How do I send a payout to a Nigerian bank account through Jentic?

Search Jentic for 'send a Flutterwave direct transfer', load the POST /direct-transfers schema, and execute with the destination bank code, account number, and amount in NGN. The response includes a transfer reference for tracking.

### Does the Flutterwave Payments API have a sandbox?

Yes, the spec lists a sandbox host (developersandbox-api.flutterwave.com) alongside the production host. Switch the base URL to test charges and transfers without moving real money.

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

Yes. Because you run Jentic One yourself, your own rules decide which Flutterwave operations the agent may call, so you can grant read-only access such as looking up a charge with GET `/charges/{charge_id}` while withholding money-moving operations like POST /charges or POST /direct-transfers. Since the customer and payment details travel in the request body rather than the URL, scoping here is operations-only: you enable exactly the endpoints the agent needs, such as creating a customer or attaching a payment method, and leave the rest off. Every operation the agent can run is one you chose, and the Flutterwave secret key stays with your instance rather than the agent.