Flutterwave Payments API
Agent-ready OpenAPI document · curated by JenticPaymentsPayment Processingbearer5 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Create customers, charge cards, and initiate transfers in Africa and globally through Flutterwave's v4 Payments API.
Use for: I need to charge a customer's saved card on Flutterwave, I want to create a customer record before saving their card, Get the status of a charge by ID, Find the right charge endpoint for one-time card payments
Not supported: Does not handle accounting, tax filing, or KYC document verification - use for Flutterwave card charges, payment method vaulting, and direct transfers only.
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.
Install Jentic One Beta
Connect the Flutterwave Payments API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Flutterwave Payments API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fflutterwave.com%2Fflutterwave" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fflutterwave.com%2Fflutterwave" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Flutterwave Payments API.
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
Patterns agents use Flutterwave Payments API for, with concrete tasks.
★ 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.
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.
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.
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.
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
5 endpoints — jentic publishes the only available openapi specification for flutterwave payments api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Global payment platform with deeper feature coverage outside Africa.
Choose Stripe when the merchant operates primarily outside Africa or needs richer subscription, invoicing, and Connect functionality.
FAQs
Specific to using Flutterwave Payments API through Jentic.
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.
GET STARTED