--- title: Flutterwave API Integration on Truto slug: flutterwave category: Payment Gateway canonical: "https://truto.one/integrations/detail/flutterwave/" --- # Flutterwave API Integration on Truto **Category:** Payment Gateway **Status:** Beta ## MCP-ready AI tools Truto exposes 57 tools for Flutterwave that AI agents can call directly. - **list_all_flutterwave_customers** — List Flutterwave customers. Returns: id, email, address, name, phone, meta, created_datetime. Max 10 records per page. - **create_a_flutterwave_customer** — Create a new Flutterwave customer. Returns the created customer object including id, email, address, name, phone, and created_datetime. - **get_single_flutterwave_customer_by_id** — Retrieve a single Flutterwave customer by id. Returns the customer object including id, email, name, phone, address, meta, and created_datetime. Required: id. - **flutterwave_customers_search** — Search Flutterwave customers. Returns: id, email, address, name, phone, meta, created_datetime. - **update_a_flutterwave_customer_by_id** — Update a Flutterwave customer by id. Returns the updated customer object including id, email, address, name, phone, and created_datetime. Required: id. - **list_all_flutterwave_charges** — List charges in flutterwave, optionally filtered by status, date range, customer, payment method, or order. Returns: id, tx_ref, flw_ref, device_fingerprint, amount, currency, charged_amount, app_fee, merchant_fee, processor_response, auth_model, ip, narration, status, auth_url, payment_type, fraud_status, charge_type, created_at, account_id, order_id, redirect_url, amount_settled, reference,… - **create_a_flutterwave_charge** — Create a charge in flutterwave to initiate a payment via card or mobile money. Returns: id, tx_ref, device_fingerprint, amount, currency, created_at, redirect_url, meta. Required: tx_ref, amount, currency, email. - **get_single_flutterwave_charge_by_id** — Retrieve a single charge in flutterwave by its id. Returns: id, status, created_at, meta. Required: id. - **update_a_flutterwave_charge_by_id** — Update a charge in flutterwave by its id. Returns: id, tx_ref, device_fingerprint, amount, currency, status, created_at, redirect_url, meta. Required: id. - **create_a_flutterwave_orchestration_direct_charge** — Create a direct charge using the Flutterwave Orchestrator helper. Returns status, message, and a data object containing the charge id, amount, status, reference, redirect_url, next_action, payment_method_details, processor_response, and created_datetime. - **list_all_flutterwave_payment_methods** — List payment methods in Flutterwave. Returns a collection of payment method objects including id and attributes. Max 10 items per page. - **create_a_flutterwave_payment_method** — Create a payment method in Flutterwave. Returns the created payment method object including id and attributes. - **get_single_flutterwave_payment_method_by_id** — Retrieve a single Flutterwave payment method by id. Returns the payment method object including id, type, customer_id, created_datetime, client_ip, device_fingerprint, meta, and mobile_money details. Required: id. - **list_all_flutterwave_mobile_networks** — List supported mobile networks in Flutterwave for a given country, returning individual network records from the response data array. Returns mobile network records including id. Required: country. - **list_all_flutterwave_banks** — List all flutterwave banks supported in a specified country. Returns a collection of bank records each containing id, code, and name. Required: country. - **list_all_flutterwave_bank_branches** — List all flutterwave bank branches for a given bank. Returns: id, branch_code, branch_name, swift_code, bic, bank_id. Required: bank_id. - **create_a_flutterwave_wallets_account_resolve** — Verify wallet account information in Flutterwave by performing a wallet account lookup. Returns the resolved account details including account_number and account_name. - **list_all_flutterwave_wallets_statements** — List Flutterwave wallet statement transactions. Returns: amount, currency, balance_before, balance_after, reference, date, remarks, sent_currency, rate_used, sent_amount, statement_type, payout_id, transaction_type. - **create_a_flutterwave_direct_transfer** — Initiate a direct transfer in Flutterwave via the Orchestrator helper. Returns status, message, and data containing the queued transfer object including id, account_number, currency, amount, fee, status, reference, bank_name, and created_at. Required: account_bank, account_number, amount, currency, narration. - **list_all_flutterwave_wallets_balances** — List all Flutterwave wallet balances across every supported currency. Returns one record per currency with currency, available_balance, and ledger_balance. - **get_single_flutterwave_wallets_balance_by_id** — Get the Flutterwave wallet balance for a specific currency by id. Returns: status, message, data. Required: id. - **list_all_flutterwave_transfers** — List flutterwave transfers with optional filters by status, date range, currency, sender, recipient, or bulk ID. Returns: id, account_number, bank_code, full_name, created_at, currency, debit_currency, amount, fee, status, reference, meta, narration, approver, complete_message, requires_approval, is_approved, bank_name, debit_currency_amount, rate. - **create_a_flutterwave_transfer** — Create a flutterwave transfer to a bank account or mobile money wallet. Returns the queued transfer object including id, account_number, bank_code, full_name, currency, amount, fee, status, reference, narration, and bank_name. Required: account_bank, account_number, amount, currency. - **get_single_flutterwave_transfer_by_id** — Retrieve a single flutterwave transfer by id. Returns the transfer record including id, account_number, bank_code, full_name, created_at, currency, amount, fee, status, reference, narration, complete_message, requires_approval, is_approved, and bank_name. Required: id. - **update_a_flutterwave_transfer_by_id** — Update instructions for a deferred payout flutterwave transfer by id. Only applicable to deferred payout transfers. Returns: id, account_number, created_at, currency, debit_currency, amount, reference, meta, narration. Required: id. - **create_a_flutterwave_transfer_retry** — Retry a failed Flutterwave transfer or duplicate a successful one. Returns: status, message, data. Required: transfer_id. - **list_all_flutterwave_transfer_retries** — List all retry attempts for a Flutterwave transfer. Returns: id, account_number, bank_code, bank_name, full_name, currency, debit_currency, amount, fee, status, reference, narration, complete_message, meta, requires_approval, is_approved, created_at. Required: transfer_id. - **list_all_flutterwave_transfers_recipients** — List all Flutterwave transfer recipients. Returns: id. - **create_a_flutterwave_transfers_recipient** — Create a new Flutterwave transfer recipient. Returns: id. - **get_single_flutterwave_transfers_recipient_by_id** — Retrieve a single Flutterwave transfer recipient by id. Returns: id. Required: id. - **delete_a_flutterwave_transfers_recipient_by_id** — Delete a Flutterwave transfer recipient by id. Returns an empty 204 response on success. Required: id. - **list_all_flutterwave_transfers_senders** — List all transfer senders in Flutterwave. Returns an array of sender records; each record includes id and attributes. - **create_a_flutterwave_transfers_sender** — Create a new transfer sender in Flutterwave. Requires a JSON request body following the Flutterwave sender_in schema. Returns: id. - **get_single_flutterwave_transfers_sender_by_id** — Retrieve a single transfer sender by id from Flutterwave. Returns: id. Required: id. - **delete_a_flutterwave_transfers_sender_by_id** — Delete a transfer sender by id from Flutterwave. Returns an empty 204 response on success. Required: id. - **create_a_flutterwave_transfers_rate** — Retrieve an international transfer rate conversion in Flutterwave. Returns: status, message, and data containing the conversion rate, source currency/amount, and destination currency/amount. Required: amount, destination_currency, source_currency. - **get_single_flutterwave_transfers_rate_by_id** — Get a Flutterwave transfer rate conversion by its unique identifier. Returns: status, message, data. Required: id. - **list_all_flutterwave_settlements** — List Flutterwave settlements. Returns: id, account_id, merchant_name, merchant_email, settlement_account, bank_code, transaction_date, due_date, processed_date, status, is_local, currency, gross_amount, app_fee, merchant_fee, chargeback, refund, stampduty_charge, net_amount, transaction_count, processor_ref, disburse_ref, disburse_message, channel, destination, fx_data, flag_message,… - **get_single_flutterwave_settlement_by_id** — Retrieve a single Flutterwave settlement by id. Returns the full settlement object including id, status, currency, gross_amount, net_amount, merchant_name, merchant_email, transaction_date, disburse_ref, and a transactions array with individual charge details. Required: id. - **list_all_flutterwave_chargebacks** — List flutterwave chargebacks, optionally filtered by date range or transaction reference. Returns: id, amount, flw_ref, status, stage, comment, meta, due_date, settlement_id, created_at, transaction_id, tx_ref. - **create_a_flutterwave_chargeback** — Create a new chargeback in flutterwave. Returns the created chargeback object including id, amount, flw_ref, status, stage, comment, meta, due_date, settlement_id, created_at, and transaction_id. - **get_single_flutterwave_chargeback_by_id** — Get a single flutterwave chargeback by id. Returns: id, status, meta, created_at. Required: id. - **update_a_flutterwave_chargeback_by_id** — Update a flutterwave chargeback by id (accept or decline it). Returns the updated chargeback object including id, amount, flw_ref, status, stage, comment, meta, due_date, settlement_id, created_at, and transaction_id. Required: id, action, comment. - **list_all_flutterwave_refunds** — List all refunds in Flutterwave, optionally filtered by date range. Returns: id, amount_refunded, status, flw_ref, comment, settlement_id, meta, created_at, account_id, transaction_id. - **create_a_flutterwave_refund** — Create a refund in Flutterwave. Returns the created refund record including id, amount_refunded, status, flw_ref, comment, settlement_id, created_at, account_id, and transaction_id. - **get_single_flutterwave_refund_by_id** — Retrieve a single Flutterwave refund by id. Returns: id, amount_refunded, status, flw_ref, comment, settlement_id, meta, created_at, account_id, transaction_id. Required: id. - **get_single_flutterwave_fee_by_id** — Retrieve transaction fees from Flutterwave for a given payment scenario. Returns: status, message, data. - **list_all_flutterwave_orders** — List Flutterwave orders. Returns: id, amount, fee, tx_ref, order_reference, created_at, total_amount, flw_ref, meta. Optionally filter by status. Max 10 items per page. - **create_a_flutterwave_order** — Create a new order in Flutterwave. Returns the created order object including id, amount, fee, tx_ref, order_reference, total_amount, and created_at. - **get_single_flutterwave_order_by_id** — Retrieve a single Flutterwave order by id. Returns: id, created_at, meta. Required: id. - **update_a_flutterwave_order_by_id** — Update an existing Flutterwave order by id. Returns the updated order object including id, amount, fee, tx_ref, order_reference, total_amount, flw_ref, and meta. Required: id. - **create_a_flutterwave_orchestration_direct_order** — Create a direct order in Flutterwave using the orchestration helper. Returns: status, message, and a data object containing the order details including amount, fee, tx_ref, order_reference, created_at, and total_amount. - **list_all_flutterwave_virtual_accounts** — List all virtual accounts in flutterwave. Returns virtual account objects including id and account-specific attributes. Optionally filter results by reference, from_datetime, or to_datetime. - **create_a_flutterwave_virtual_account** — Create a new virtual account in flutterwave. Returns the created virtual account object including id and account-specific attributes. - **get_single_flutterwave_virtual_account_by_id** — Retrieve a single flutterwave virtual account by id. Returns the virtual account object including id and account-specific attributes. Required: id. - **update_a_flutterwave_virtual_account_by_id** — Update a flutterwave virtual account by id. Returns the updated virtual account object including id and account-specific attributes. Required: id. - **create_a_flutterwave_bank_account_resolve** — Resolve a Flutterwave bank account to retrieve the account holder's details. Returns: account_number, account_name. ## How it works 1. **Link your customer's Flutterwave account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Flutterwave.** The Proxy API is a 1-to-1 mapping of the Flutterwave API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed African payment acceptance into your platform** — Let your merchants accept cards, bank transfers, and mobile money across African markets without you having to integrate with dozens of local banks and telcos. Truto handles the Flutterwave connection so your users can start collecting payments in minutes. - **Automate cross-border contractor and vendor payouts** — HR, payroll, and marketplace platforms can disburse funds to bank accounts and mobile money wallets across Africa directly from their UI. Verify recipient details, calculate FX rates, and retry failed transfers without leaving your product. - **Reconcile settlements into accounting and ERP workflows** — Pull daily settlement batches, fees, and refunds from your users' Flutterwave accounts and map them to the right ledger entries. Eliminates the manual CSV exports finance teams do every month-end. - **Power invoice-to-virtual-account billing for B2B SaaS** — Subscription and invoicing tools can generate a unique Flutterwave virtual account per invoice so buyers can pay via local bank transfer. The platform marks invoices paid automatically when funds land. - **Native dispute and refund management inside your dashboard** — E-commerce, OMS, and support platforms can let merchants accept/decline chargebacks and issue refunds without context-switching to Flutterwave. Keeps the entire payment lifecycle in your product. ## What you can build - **Unified checkout creation for cards, bank transfers, and mobile money** — Use create_a_flutterwave_charge and list_all_flutterwave_payment_methods to let merchants spin up payment flows that adapt to the buyer's country and preferred method. - **Dynamic virtual account provisioning per customer or invoice** — Call create_a_flutterwave_virtual_account to generate a unique bank account number tied to an invoice, then track payment status via get_single_flutterwave_virtual_account_by_id. - **Bulk payouts with name verification and auto-retry** — Chain create_a_flutterwave_bank_account_resolve, create_a_flutterwave_transfer, and create_a_flutterwave_transfer_retry to push verified payouts to bank or mobile money recipients and recover from network failures automatically. - **Multi-currency wallet liquidity dashboards** — Surface real-time balances and statements per currency using list_all_flutterwave_wallets_balances and list_all_flutterwave_wallets_statements so merchants know when to top up before running bulk disbursements. - **Settlement-to-ledger sync for accounting platforms** — Pull list_all_flutterwave_settlements and list_all_flutterwave_refunds to break down gross amount, app fee, merchant fee, and net amount into double-entry accounting logs. - **Embedded chargeback and refund management** — Let merchants act on disputes inside your UI using list_all_flutterwave_chargebacks, update_a_flutterwave_chargeback_by_id, and create_a_flutterwave_refund — no Flutterwave dashboard required. ## FAQs ### How do end users authenticate their Flutterwave account? Your users connect their Flutterwave account by providing their API credentials, which Truto stores securely and attaches to every outbound call. You don't have to build or maintain the auth flow yourself. ### Which Flutterwave resources can I read and write through Truto? Truto exposes tools for customers, charges, orders, payment methods, virtual accounts, transfers (including retries, recipients, senders, and rates), wallets (balances and statements), settlements, refunds, chargebacks, fees, and supporting lookup data like banks, bank branches, and mobile networks. ### Can I support both pay-ins and payouts with the same integration? Yes. The same connection gives you access to charge creation, order management, and virtual account provisioning for pay-ins, as well as transfers, recipient management, FX rate lookups, and retry logic for payouts. ### Does Truto handle pagination and API quirks for list endpoints? Yes. Endpoints like list_all_flutterwave_charges, list_all_flutterwave_transfers, and list_all_flutterwave_settlements return normalized paginated responses through Truto so you don't have to manage Flutterwave's pagination cursors directly. ### Can I verify bank account ownership before sending a payout? Yes. Use create_a_flutterwave_bank_account_resolve to confirm the recipient name matches the account number before triggering create_a_flutterwave_transfer, which reduces failed payouts and fraud risk. ### How fresh is the data — does Truto poll or push? Truto's tools call Flutterwave's APIs on demand, so reads (like settlements, balances, or chargebacks) return live data at request time. For event-driven flows, you can poll list endpoints on your own schedule to detect new charges, transfers, or disputes.