# Flutterwave — how to use (mcp.ai)

Connect your Flutterwave account and use 53 tools for payment processing straight from your AI agent. Connect with your own API key. Flutterwave is a payments technology company that provides payment infrastructure and APIs enabling businesses to accept and send payments in Africa and globally.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_flutterwave?ms=1787293680000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `flutterwave_cancel_payment_plan`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/flutterwave`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/flutterwave/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/flutterwave/cancel/payment/plan` — Tool to cancel a payment plan. Use when you need to prevent all future subscriptions under this plan.
  - body: { id: string }
- `POST https://api.mcp.ai/api/flutterwave/create/beneficiary` — Tool to create a new transfer beneficiary. Use when you need to add a beneficiary before making a transfer.
  - body: { account_bank: string, account_number: string, beneficiary_name?: string }
- `POST https://api.mcp.ai/api/flutterwave/create/bulk/tokenized/charge` — Tool to create a bulk tokenized charge batch for charging multiple previously tokenized cards. Use when you need to process multiple recurring or subscription charges in a single batch. Each charge mu
  - body: { title: string, bulk_data: object[], retry_strategy?: object }
- `POST https://api.mcp.ai/api/flutterwave/create/bulk/virtual/account/numbers` — Tool to create multiple virtual account numbers. Use when you need to generate multiple static virtual accounts for customers in a single request.
  - body: { batch_ref: string, bulk_data: object[], narration?: string }
- `POST https://api.mcp.ai/api/flutterwave/create/payment/link` — Tool to create a hosted payment link. Use when you need a shareable payment URL for one-time transactions.
  - body: { amount: number|string, tx_ref: string, currency: string, customer: object, redirect_url: string, customizations?: object }
- `POST https://api.mcp.ai/api/flutterwave/create/payment/plan` — Tool to create a new payment plan. Use after confirming plan and customer details.
  - body: { name: string, amount?: number|string, currency?: string, duration?: integer, interval: string }
- `POST https://api.mcp.ai/api/flutterwave/create/refund` — Tool to create a refund for a transaction. Use when you need to initiate a refund after confirming the transaction ID and refund amount.
  - body: { id: string, amount: string }
- `POST https://api.mcp.ai/api/flutterwave/create/subaccount` — Tool to create a new subaccount. Use when you need to configure split disbursement accounts.
  - body: { meta?: object[], country?: string, split_type: string, split_value: number, account_bank: string, business_name: string, account_number: string, business_email: string, business_mobile?: string, business_contact?: string, business_contact_mobile?: string }
- `POST https://api.mcp.ai/api/flutterwave/create/virtual/account` — Tool to create a new virtual account number. Use after confirming customer details when assigning a unique account for bank transfers.
  - body: { bvn?: string, email: string, amount: number, tx_ref?: string, duration?: integer, lastname?: string, firstname?: string, frequency?: integer, narration?: string, phonenumber?: string, is_permanent?: boolean }
- `POST https://api.mcp.ai/api/flutterwave/delete/beneficiary` — Tool to delete a beneficiary by ID. Use when you need to remove a saved transfer beneficiary by its unique ID after confirming the ID.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/delete/subaccount` — Tool to delete a subaccount by ID. Use when you need to remove a subaccount from your Flutterwave account.
  - body: { id: string }
- `POST https://api.mcp.ai/api/flutterwave/disable/payment/link` — Tool to disable a Flutterwave payment link. Use when you need to prevent further payments from an existing link after confirming the link is valid.
  - body: { link: string }
- `POST https://api.mcp.ai/api/flutterwave/fetch/beneficiary` — Tool to retrieve details of a specific beneficiary by ID. Use after obtaining a beneficiary ID to fetch its full details from Flutterwave.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/fetch/subaccount` — Tool to retrieve details of a specific subaccount by ID. Use when you need full subaccount info after creating or updating splits.
  - body: { id: string }
- `POST https://api.mcp.ai/api/flutterwave/generate/transaction/reference` — Tool to generate a unique transaction reference. Use when initiating a new Flutterwave transaction requires a unique reference to prevent duplication.
- `POST https://api.mcp.ai/api/flutterwave/get/all/subscriptions` — Tool to retrieve all subscriptions, including cancelled ones. Use when you need a comprehensive list of subscription records for auditing or reporting.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/all/transactions` — Tool to retrieve a list of all transactions with optional filters. Use when you need to paginate or filter transaction history after confirming valid API credentials.
  - body: { page?: integer, status?: string, tx_ref?: string, to_date?: string, currency?: string, from_date?: string, customer_email?: string }
- `POST https://api.mcp.ai/api/flutterwave/get/all/wallet/balances` — Tool to retrieve all wallet balances across currencies. Use when reconciling balances after authentication.
- `POST https://api.mcp.ai/api/flutterwave/get/balances/per/currency` — Tool to retrieve wallet balance for a specific currency. Use after transactions to confirm available and ledger balances in a given currency.
  - body: { currency: string }
- `POST https://api.mcp.ai/api/flutterwave/get/bank/branches` — Tool to retrieve branch codes for a specific bank. Use when you need branch information for transfers in countries like Ghana that require branch codes.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/banks/by/country` — Tool to retrieve all banks in a specified country. Use when you need to get available banks for transfers or payments in a specific country.
  - body: { country: string }
- `POST https://api.mcp.ai/api/flutterwave/get/bill/categories` — Tool to retrieve available bill categories. Use after authenticating to Flutterwave to display bill payment options to users.
- `POST https://api.mcp.ai/api/flutterwave/get/bulk/tokenized/charge` — Tool to retrieve the status of a bulk tokenized charge operation by ID. Use after initiating a bulk tokenized charge to check its processing status.
  - body: { bulk_id: string }
- `POST https://api.mcp.ai/api/flutterwave/get/bulk/virtual/account` — Tool to fetch bulk virtual account details using batch ID. Use this after creating bulk virtual accounts to retrieve the generated account numbers and their details.
  - body: { batch_id: string }
- `POST https://api.mcp.ai/api/flutterwave/get/multiple/refund/transactions` — Tool to retrieve multiple refund transactions with optional filters. Use when you need to fetch paginated refund data after confirming valid API credentials.
  - body: { page?: integer, status?: string, flw_ref?: string, to_date?: string, from_date?: string, page_size?: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/payment/plan` — Tool to retrieve details of a specific payment plan by ID. Use after obtaining the payment plan ID to fetch its details from Flutterwave.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/payment/plans` — Tool to retrieve a list of all payment plans. Use when you need to fetch and present your account’s configured billing plans.
- `POST https://api.mcp.ai/api/flutterwave/get/refund` — Tool to retrieve details of a specific refund by ID. Use after obtaining the refund ID to fetch its details from Flutterwave.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/transaction` — Tool to retrieve details of a specific transaction by ID. Use after obtaining the transaction ID to fetch its details from Flutterwave.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/flutterwave/get/transaction/fee` — Tool to retrieve the fee for a specific transaction. Use when you need to calculate the total charge including fees before initiating the transaction.
  - body: { amount: number, currency: string }
- `POST https://api.mcp.ai/api/flutterwave/get/transfer/fee` — Tool to retrieve the fee for initiating a transfer. Use when you need to estimate transfer costs before creating a transfer. Example: "Calculate the fee for transferring NGN 5000 to an account."
  - body: { type?: string, amount: integer, currency?: string }
- `POST https://api.mcp.ai/api/flutterwave/get/transfer/rates` — Tool to retrieve exchange rates for transfers between currencies. Use when you need to calculate conversion rates before initiating a cross-currency transfer.
  - body: { amount: number, source_currency: string, destination_currency: string }
- `POST https://api.mcp.ai/api/flutterwave/get/virtual/account/number` — Tool to fetch details of a virtual account number by order reference. Use when you need to retrieve account details after creation.
  - body: { order_ref: string }
- `POST https://api.mcp.ai/api/flutterwave/get/wallet/statement` — Tool to retrieve wallet balance history with optional filters. Use when you need to view transaction history and balance changes over a period.
  - body: { page?: integer, to_date?: string, currency?: string, from_date?: string }
- `POST https://api.mcp.ai/api/flutterwave/initiate/bvn/verification` — Tool to initiate BVN verification consent. Use when you need to verify a customer's Bank Verification Number (BVN) by obtaining their consent first. The customer will be redirected to a consent page w
  - body: { bvn: string, lastname: string, firstname: string, redirect_url: string }
- `POST https://api.mcp.ai/api/flutterwave/initiate/mobile/money/tanzania` — Tool to initiate a mobile money payment in Tanzania. Use after collecting customer details to charge via Tanzanian mobile money networks.
  - body: { meta?: object, email: string, amount: number, tx_ref: string, network?: string, currency: string, fullname?: string, client_ip?: string, phone_number: string, device_fingerprint?: string }
- `POST https://api.mcp.ai/api/flutterwave/list/all/beneficiaries` — Tool to list all saved beneficiaries. Use when you need to retrieve all transfer beneficiaries associated with your account.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/flutterwave/list/biller/products` — Tool to retrieve all products available under a specific biller. Use after getting bill categories to display available products for bill payment.
  - body: { id: string }
- `POST https://api.mcp.ai/api/flutterwave/list/billers` — Tool to retrieve available billers. Use after authenticating to Flutterwave to display bill payment biller options to users.
- `POST https://api.mcp.ai/api/flutterwave/list/chargebacks` — Tool to retrieve a list of chargebacks with optional filtering by Flutterwave reference. Use when you need to view all chargebacks or search for a specific chargeback by transaction reference.
  - body: { page?: integer, flw_ref?: string, per_page?: integer }
- `POST https://api.mcp.ai/api/flutterwave/list/payout/subaccount/refunds` — Tool to list all payout subaccount refunds with pagination support. Use when you need to retrieve payout subaccount refund history with optional page filtering.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/flutterwave/list/payout/subaccounts` — Tool to list all payout subaccounts. Use when you need to retrieve all payout subaccounts associated with your Flutterwave account.
- `POST https://api.mcp.ai/api/flutterwave/list/recurring/bills` — Tool to retrieve all recurring bill payments. Use when you need to view scheduled or active recurring billing arrangements.
- `POST https://api.mcp.ai/api/flutterwave/list/settlements` — Tool to retrieve all settlements with optional filters. Use when you need to fetch settlement records, view transaction settlements, or track payment disbursements.
  - body: { page?: integer, to_date?: string, from_date?: string, subaccount_id?: string }
- `POST https://api.mcp.ai/api/flutterwave/list/subaccounts` — Tool to fetch all collection subaccounts. Use when you need to retrieve the complete list of subaccounts for split disbursements.
  - body: { page?: integer, per_page?: integer }
- `POST https://api.mcp.ai/api/flutterwave/list/transfers` — Tool to fetch a list of bulk transfers from your Flutterwave account. Use when you need to retrieve transfer history, check transfer statuses, or filter transfers by reference or status.
  - body: { page?: integer, status?: string, reference?: string }
- `POST https://api.mcp.ai/api/flutterwave/resolve/bank/account` — Tool to verify and resolve bank account details. Use when you need to retrieve the account holder name for a Nigerian bank account by providing the account number and bank code.
  - body: { account_bank: string, account_number: string }
- `POST https://api.mcp.ai/api/flutterwave/resolve/card/bin` — Tool to resolve and retrieve card BIN information from Flutterwave. Use when you need to get issuer details, card type, and country information for a 6-digit BIN.
  - body: { bin: string }
- `POST https://api.mcp.ai/api/flutterwave/update/payment/plan` — Tool to update an existing payment plan. Use when you need to modify a payment plan's name or status.
  - body: { id: integer, name?: string, status?: string }
- `POST https://api.mcp.ai/api/flutterwave/update/subaccount` — Tool to update an existing subaccount. Use when you need to modify split disbursement settings or business details.
  - body: { id: string, split_type?: string, split_value?: string, account_bank?: string, business_name?: string, account_number?: string, business_email?: string }
- `POST https://api.mcp.ai/api/flutterwave/validate/bill/item` — Tool to validate a bill service before payment. Use before initiating a bill payment to confirm the customer identifier (account number, meter number, etc.) is valid and retrieve customer details.
  - body: { code: string, customer: string, item_code: string }
- `POST https://api.mcp.ai/api/flutterwave/verify/transaction/by/reference` — Tool to verify a transaction using its transaction reference. Use when you have a transaction reference (tx_ref) and need to confirm the transaction status and retrieve its details.
  - body: { tx_ref: string }
- `POST https://api.mcp.ai/api/flutterwave/view/transaction/timeline` — Tool to retrieve the event timeline for a transaction. Use after obtaining the transaction ID to audit or track the sequence of events.
  - body: { id: integer }

## Example prompts
- "What can I do in Flutterwave?"
- "Show me a summary of my Flutterwave account"

## More
- Page: https://mcp.ai/flutterwave
- Agent spec (llms.txt): https://mcp.ai/flutterwave/llms.txt
- Postman collection: https://mcp.ai/flutterwave/postman.json