Services
Each Flutterwave API area is a service class, reached through the facade. Methods return Flutterwave's decoded JSON response as an array.
use Flutterwave\Payments\Facades\Flutterwave;
Flutterwave::transfers()->create([...]);
Flutterwave::use('transfers')->create([...]); // same thing, by config keyErrors
When the API returns an error, methods throw Flutterwave\Payments\Exception\FlutterwaveException (or its NetworkConnection subclass when Flutterwave can't be reached):
use Flutterwave\Payments\Exception\FlutterwaveException;
try {
Flutterwave::transfers()->create($payload);
} catch (FlutterwaveException $e) {
$e->getMessage(); // Flutterwave's message
$e->getStatusCode(); // HTTP status
$e->getResponse(); // the full error body
}The exception is the transactions service: verifying, listing, refunding and fee lookups return the error body instead, so check $response['status'] === 'success'.
You can replace or turn off any service in the config.
Explorer
Service explorer
Every service and public method in the package, read from src/Services when the docs are built. Call any of them through the facade, for example Flutterwave::transfers()->create([...]).
112 methods
Flutterwave::balances()Balances
Wallet balances on your Flutterwave account.
all: array
Flutterwave::balances()->all()currency: array
Flutterwave::balances()->currency(string $currency)Flutterwave::banks()Banks
Bank lists and account-name lookups.
all: arrayList banks for a country code, e.g. NG, GH, KE, UG, ZA, TZ.
Flutterwave::banks()->all(string $country = 'NG')options: arrayThe country's banks as [['code' => '044', 'name' => 'Access Bank'], ...], sorted by name, for a dropdown. Cached for a day, since bank lists rarely change.
Flutterwave::banks()->options(string $country = 'NG')branches: array
Flutterwave::banks()->branches(int|string $bankId)resolveAccount: arrayResolve the account name for a Nigerian or Ghanaian bank account, or a Ghanaian mobile money number (pass the phone number and the provider's code).
Flutterwave::banks()->resolveAccount(string $accountNumber, string $bankCode, ?string $country = null)resolveMerchant: arrayResolve the business name behind a Flutterwave merchant ID, e.g. before a wallet-to-wallet transfer.
Flutterwave::banks()->resolveMerchant(string $merchantId)Flutterwave::beneficiaries()Beneficiaries
Saved transfer recipients.
create: arraySave a recipient. Get the bank code from banks()->options(). $name is required by Flutterwave; resolve it first with banks()->resolveAccount() if you don't have it.
Flutterwave::beneficiaries()->create(string $accountNumber, string $bankCode, ?string $name = null, ?string $currency = null, ?string $bankName = null)all: array
Flutterwave::beneficiaries()->all(array $filters = [])find: array
Flutterwave::beneficiaries()->find(int|string $id)delete: array
Flutterwave::beneficiaries()->delete(int|string $id)panel: arrayEverything the beneficiaries components need. Pass the request's query: `page`, and `country` for the bank list (default from config).
Flutterwave::beneficiaries()->panel(array $query = [])Flutterwave::bills()Bills
Airtime, data, electricity, cable TV and other bills, paid from your Flutterwave balance. Find what to pay in three steps: categories() gives category codes (AIRTIME, UTILITYBILLS...), billers($category) gives biller codes, and items($billerCode) gives item codes and prices. Validate the customer's meter, smartcard or phone number before paying: payments can't be undone.
categories: array
Flutterwave::bills()->categories(string $country = 'NG')billers: array
Flutterwave::bills()->billers(string $category, string $country = 'NG')items: arrayWhat the biller sells, with item_code, amount, fee and the customer number format (reg_expression, label_name).
Flutterwave::bills()->items(string $billerCode)validate: arrayCheck a customer number (meter, smartcard, phone...) and get the name on it. `data.minimum` and `data.maximum` are the provider's limits when they're not zero.
Flutterwave::bills()->validate(string $itemCode, string $customer)pay: arrayPay a bill. A unique `reference` is generated when you don't pass one, so you can look it up later.
Flutterwave::bills()->pay(string $billerCode, string $itemCode, string $customerId, int|float|string $amount, array $options = [])payValidated: arrayValidate the customer number first and only pay when it checks out and the amount is within the provider's limits. Returns the payment response.
Flutterwave::bills()->payValidated(string $billerCode, string $itemCode, string $customerId, int|float|string $amount, array $options = [])status: arrayLook up a bill payment by its reference (the tx_ref in the payment response).
Flutterwave::bills()->status(string $reference)history: arrayFilters: status (Successful, Failed, Reversed), from, to, page, limit, reference, category, country.
Flutterwave::bills()->history(array $filters = [])Flutterwave::bvn()Bvn
Verify a Nigerian customer's BVN with their consent: request consent, send the customer to the returned NIBSS page, then fetch the result with the reference. The result holds personal data, including a photo of the customer's face (bvn_data.faceImage). Store only what you need and never log it. The package doesn't log successful responses.
requestConsent: arrayReturns `data.url` (send the customer there to give consent) and `data.reference` (keep it).
Flutterwave::bvn()->requestConsent(string $bvn, string $firstName, string $lastName, ?string $redirectUrl = null)verification: array`data.status` is COMPLETED once the customer has consented; `data.bvn_data` then holds their details.
Flutterwave::bvn()->verification(string $reference)matches: boolTrue once the customer has consented and the BVN's names match the ones you have, ignoring case and the order of first and last name.
Flutterwave::bvn()->matches(string $reference, string $firstName, string $lastName)Flutterwave::cards()Cards
Card BIN lookups, and charging saved cards with the token from an earlier payment. Get a token by verifying a card payment: it's in `data.card.token`. Tokens are tied to the email used for that payment and last a year. Repeat charges use 3-D Secure unless Flutterwave has enabled no-auth charges on your account, so a charge can stay pending until the customer approves it.
bin: arrayGet the issuer, card type and country for the first six digits of a card.
Flutterwave::cards()->bin(string $bin)charge: arrayCharge a saved card. $email must be the email used when the card was saved. Options: currency and country (default from config), tx_ref (generated), redirect_url (default FLW_REDIRECT_URL), narration, first_name, last_name, payment_plan, subaccounts.
Flutterwave::cards()->charge(string $token, string $email, int|float|string $amount, array $options = [])preauthorize: arrayHold $amount on a saved card without charging it. Capture, void or refund it with Pre-authorization has to be enabled on your account by Flutterwave.
Flutterwave::cards()->preauthorize(string $token, string $email, int|float|string $amount, array $options = [])Flutterwave::preauth() using the response's `data.flw_ref`. Holds are released after 7 days.chargeMany: arrayCharge many saved cards at once. Each charge needs token, email and amount; the other fields default as in charge(). Bulk charges need no-auth charges enabled. $retryStrategy: retry_interval (minutes), retry_amount_variable (percent of the amount to retry), retry_attempt_variable, last_retry_attempt.
Flutterwave::cards()->chargeMany(array $charges, array $retryStrategy = [], ?string $title = null)bulkStatus: array
Flutterwave::cards()->bulkStatus(int|string $bulkId)bulkTransactions: array
Flutterwave::cards()->bulkTransactions(int|string $bulkId)updateToken: arrayUpdate the customer details on a token, e.g. when they change their email address, so future charges with the new email still work.
Flutterwave::cards()->updateToken(string $token, string $email, string $phoneNumber, string $firstName, string $lastName)Flutterwave::chargebacks()Chargebacks
Chargebacks raised by customers' banks against your transactions. Respond before the due date (10 working hours for local transactions, 30 for international), or the chargeback is lost and the customer is refunded.
all: arrayFilters: page, status (initiated, accepted, declined, won, lost), from and to (YYYY-MM-DD), currency, flw_ref, id.
Flutterwave::chargebacks()->all(array $filters = [])find: arrayFetch a chargeback, including its history, by the transaction's flw_ref. Like all(), the response's `data` is a list.
Flutterwave::chargebacks()->find(string $flwRef)accept: arrayAccept the chargeback: the customer gets their money back.
Flutterwave::chargebacks()->accept(int|string $id, string $comment)decline: arrayDispute the chargeback with proof that the customer received value. Get the proof link from uploadProof(), or use declineWithProof() to do both.
Flutterwave::chargebacks()->decline(int|string $id, string $comment, string $proofLink)uploadProof: arrayUpload evidence for a dispute. Combine all your documents into one file. Accepts a file path, or a file object such as an UploadedFile from a form. The response's `data` is the proof link to pass to decline().
Flutterwave::chargebacks()->uploadProof(string|SplFileInfo $file)declineWithProof: arrayUpload the evidence and decline the chargeback in one call.
Flutterwave::chargebacks()->declineWithProof(int|string $id, string $comment, string|SplFileInfo $file)panel: arrayEverything the chargeback components need, as one array: e.g. an Inertia prop or the :panel of <x-flutterwave-chargebacks>. API errors come back in `error` instead of being thrown, so a failed lookup doesn't break the page.
Flutterwave::chargebacks()->panel(array $filters = [])Flutterwave::fx()Fx
Convert between currencies at a quoted rate: request a quote, wait for it to be READY, then trade it. FX must be enabled on your account, trades run on weekdays only, and the minimum is USD 1,000 or its equivalent. Quote updates arrive as `quote.completed` webhooks (the QuoteCompleted event) and trade results as `transfer.completed` (TransferCompleted).
quote: arrayAsk for a rate to sell $quantity of $baseCurrency for $targetCurrency, e.g. quote('NGN', 'USD', 2_000_000) to spend NGN 2,000,000 on dollars. The quote starts as NEW; fetch it with findQuote() or wait for the webhook.
Flutterwave::fx()->quote(string $baseCurrency, string $targetCurrency, int|float|string $quantity, ?string $reference = null)findQuote: arrayWhen READY, `data.quote` holds best_available_rate, approved_quantity (may be less than you asked for), total_value and expiry.
Flutterwave::fx()->findQuote(string $quoteId)trade: arrayExecute a READY quote. Each quote can only be traded once.
Flutterwave::fx()->trade(string $quoteId, string $narration, array $meta = [])findTrade: array
Flutterwave::fx()->findTrade(string $tradeId)tradeIfReady: arrayFetch the quote and trade it only if it is still READY, so an expired quote fails here with a clear message instead of at the API.
Flutterwave::fx()->tradeIfReady(string $quoteId, string $narration, array $meta = [])panel: arrayEverything the FX converter components need, as one array: e.g. an Inertia prop or the :panel of <x-flutterwave-fx>. Pass the ids from the fx_quote and fx_trade query parameters. API errors come back in `error` instead of being thrown.
Flutterwave::fx()->panel(?string $quoteId = null, ?string $tradeId = null)Flutterwave::use('modals')Modal
Builds inline checkout configs and hosted (standard) payment links.
render: stringRender Inline (JSON config for FlutterwaveCheckout) or Standard (hosted link).
Flutterwave::use('modals')->render(array $data, string $type = 'inline')displayInline: View
Modal::displayInline(array $data)prepare: arrayFill in defaults so callers only need an amount and an email.
Flutterwave::use('modals')->prepare(array $data)Flutterwave::plans()PaymentPlans
Recurring billing plans. Pass the plan id as `payment_plan` when starting a checkout to subscribe the customer.
create: array
Flutterwave::plans()->create(string $name, int|float $amount, string $interval, ?int $duration = null, ?string $currency = null)all: array
Flutterwave::plans()->all(array $filters = [])find: array
Flutterwave::plans()->find(int|string $id)update: arrayUpdate the name and/or status ("active") of a plan.
Flutterwave::plans()->update(int|string $id, array $data)cancel: array
Flutterwave::plans()->cancel(int|string $id)Flutterwave::payoutSubaccounts()PayoutSubaccounts
Wallets for your customers: each payout subaccount has its own balance and bank account number (nuban) that anyone can pay into. Identify one by its `account_reference`.
create: array
Flutterwave::payoutSubaccounts()->create(string $accountName, string $email, string $country = 'NG', ?string $mobileNumber = null)all: arrayFilters: email, account_reference, nuban, limit, next_cursor (from data.cursor.next).
Flutterwave::payoutSubaccounts()->all(array $filters = [])find: array
Flutterwave::payoutSubaccounts()->find(string $accountReference)update: arrayRequired keys: account_name, email, mobilenumber. Optional: country.
Flutterwave::payoutSubaccounts()->update(string $accountReference, array $data)balance: array
Flutterwave::payoutSubaccounts()->balance(string $accountReference, ?string $currency = null)transactions: arrayCredits and debits between two dates (YYYY-MM-DD). Filters: currency, page, fetch_limit.
Flutterwave::payoutSubaccounts()->transactions(string $accountReference, string $from, string $to, array $filters = [])staticAccount: arrayThe wallet's bank account details for funding it. Pass $all to include every static account, not just the primary one.
Flutterwave::payoutSubaccounts()->staticAccount(string $accountReference, bool $all = false)delete: arrayDeactivate the wallet. Flutterwave processes this in the background.
Flutterwave::payoutSubaccounts()->delete(string $accountReference)Flutterwave::preauth()Preauthorizations
Settle card holds made with cards()->preauthorize(), by the charge's `data.flw_ref`. A hold you don't capture within 7 days is released automatically.
capture: arrayCharge some or all of the held amount. You can capture several times, as long as the total stays within the amount held.
Flutterwave::preauth()->capture(string $flwRef, int|float|string $amount)void: arrayRelease the hold without charging the customer.
Flutterwave::preauth()->void(string $flwRef)refund: arrayGive back money you already captured.
Flutterwave::preauth()->refund(string $flwRef, int|float|string $amount)Flutterwave::refunds()Refunds
Look up refunds. Create one with Flutterwave::refund($transactionId, $amount).
all: arrayFilters: from, to (YYYY-MM-DD), status (successful, failed, completed), currency, flw_ref, id (the transaction id), page.
Flutterwave::refunds()->all(array $filters = [])find: arrayFetch one refund by its id (data.id in the refund response).
Flutterwave::refunds()->find(int|string $id)panel: arrayEverything the refunds components need. Pass the request's query: from, to, status, currency and page filter the list.
Flutterwave::refunds()->panel(array $query = [])Flutterwave::settlements()Settlements
Payouts of collected funds to your settlement account.
all: arrayFilters: from, to (YYYY-MM-DD), page, subaccount_id, disburse_ref.
Flutterwave::settlements()->all(array $filters = [])find: arrayOne settlement, with the transactions it paid out (`data.transactions`).
Flutterwave::settlements()->find(int|string $id, ?int $page = null)panel: arrayEverything the settlements components need. Pass the request's query: from, to and page filter the list; `settlement` adds that settlement's details and transactions.
Flutterwave::settlements()->panel(array $query = [])Flutterwave::stablecoins()Stablecoins
Send USDT, USDC and RLUSD to wallets, and fund stablecoin balances from fiat. Requires a live, production-approved account with whitelisted IPs.
send: arraySend stablecoins to a wallet address. The fee is deducted from $amount when paying from a stablecoin balance. Pass a fiat $debitCurrency (NGN, USD, GBP, EUR, GHS) to convert and pay in one step; the fee is then charged to that fiat balance.
Flutterwave::stablecoins()->send(string $network, string $address, int|float $amount, string $coin, ?string $debitCurrency = null, array $extra = [])fund: arrayConvert a fiat balance into your stablecoin wallet. $merchantId defaults to FLW_MERCHANT_ID (shown on your dashboard).
Flutterwave::stablecoins()->fund(int|float $amount, string $coin, string $fromCurrency, ?string $merchantId = null, array $extra = [])fee: arrayGet the fee for a stablecoin transfer. Pass a fiat $debitCurrency for conversion fees.
Flutterwave::stablecoins()->fee(int|float $amount, string $coin, ?string $debitCurrency = null)find: arrayFetch a stablecoin transfer to check its status.
Flutterwave::stablecoins()->find(int|string $id)balances: arrayYour stablecoin wallet balances, keyed by coin.
Flutterwave::stablecoins()->balances()Flutterwave::subaccounts()Subaccounts
Split payments between your account and vendor subaccounts.
create: arrayRequired keys: account_bank, account_number, business_name, business_mobile, country, split_value.
Flutterwave::subaccounts()->create(array $data)all: array
Flutterwave::subaccounts()->all(array $filters = [])find: array
Flutterwave::subaccounts()->find(int|string $id)update: array
Flutterwave::subaccounts()->update(int|string $id, array $data)delete: array
Flutterwave::subaccounts()->delete(int|string $id)Flutterwave::subscriptions()Subscriptions
Manage customers subscribed to payment plans.
all: arrayFilter by email, plan, status, transaction_id, from, to, page...
Flutterwave::subscriptions()->all(array $filters = [])activate: array
Flutterwave::subscriptions()->activate(int|string $id)cancel: array
Flutterwave::subscriptions()->cancel(int|string $id)Flutterwave::transactions()Transactions
Verify, list and refund collections. For backwards compatibility these methods return the Flutterwave error body (`status: error`) instead of throwing when the API rejects a call.
verify: arrayVerify a transaction with transactionId
Flutterwave::transactions()->verify(int|string $transactionId)verifyTransactionReference: arrayVerify a transaction with tx_ref
Flutterwave::transactions()->verifyTransactionReference(string $tx_ref)refund: arrayRefund a transaction in full, or partially when an amount is given. Options: comments (shown on the refund), callbackurl (Flutterwave posts the result there).
Flutterwave::transactions()->refund(int|string $transactionId, int|float|string|null $amount = null, array $options = [])all: arrayGet the transactions on your account. Filters: from and to (YYYY-MM-DD, default the last 30 days, as Flutterwave requires both), page, status, customer_email, customer_fullname, tx_ref, currency.
Flutterwave::transactions()->all(?array $data = null)fees: arrayGet transaction fee by supplying amount and currency
Flutterwave::transactions()->fees(array $data)fee: arrayWhat Flutterwave charges on a payment of $amount. $paymentType: card, debit_ng_account, mobilemoney, bank_transfer or ach_payment. Pass the card's first six digits to include international card fees.
Flutterwave::transactions()->fee(int|float|string $amount, string $currency, ?string $paymentType = null, ?string $cardFirst6 = null)resendFailedHooks: arrayAsk Flutterwave to send a transaction's webhook again. With $wait, it waits for your webhook route to answer and returns that answer.
Flutterwave::transactions()->resendFailedHooks(int|string $transactionId, int|bool $wait = false)panel: arrayEverything the transactions components need. Pass the request's query: from, to, page, status, customer_email, tx_ref and currency filter the list; `transaction` adds that transaction's timeline; fee_amount and fee_currency add a fee estimate.
Flutterwave::transactions()->panel(array $query = [])timeline: arrayGet the timeline of a transaction using transactionId
Flutterwave::transactions()->timeline(int|string $transactionId)generateTransactionReference: stringGenerates a Transaction Reference for Payment Request
Transactions::generateTransactionReference(string $prefix)Flutterwave::transfers()Transfers
Send money to bank accounts and mobile money wallets.
create: arrayInitiate a transfer. Required keys: account_bank, account_number, amount, currency. A unique `reference` is generated when not provided so retries can be de-duplicated. With test keys, sandbox transfers stay PENDING unless told how to end. Pass test_outcome ('success' or 'failure') and optionally test_resolve_after (minutes, default 10). Both are ignored with live keys.
Flutterwave::transfers()->create(array $data)bulk: arraySend many transfers at once. Each item follows the same shape as create().
Flutterwave::transfers()->bulk(array $transfers, ?string $title = null)find: array
Flutterwave::transfers()->find(int|string $id)all: array
Flutterwave::transfers()->all(array $filters = [])fee: array
Flutterwave::transfers()->fee(int|float $amount, string $currency = 'NGN', ?string $type = null)rates: arrayGet the exchange rate for a cross-currency transfer.
Flutterwave::transfers()->rates(int|float $amount, string $destinationCurrency, string $sourceCurrency)retry: array
Flutterwave::transfers()->retry(int|string $id)retries: array
Flutterwave::transfers()->retries(int|string $id)Flutterwave::virtualAccounts()VirtualAccounts
Dedicated bank account numbers your customers can pay into.
create: arrayRequired keys: email. Pass is_permanent=true with a bvn for a static account.
Flutterwave::virtualAccounts()->create(array $data)dynamic: arrayCreate a single-use NGN or GHS account for one payment. It expires after `expires` seconds (Flutterwave's default is one hour). Any other create() field (firstname, lastname, phonenumber, narration, bank_code, tx_ref) can go in $options.
Flutterwave::virtualAccounts()->dynamic(string $email, int|float|string $amount, array $options = [])dynamicFor: arrayGet a dynamic account ready to show a customer, e.g. as an Inertia prop. With a tx_ref, the account is cached until it expires, so reloading the checkout page shows the same account number. Returns Flutterwave's account fields plus currency, tx_ref, expires_at (ISO 8601) and expires_in (seconds left).
Flutterwave::virtualAccounts()->dynamicFor(string $email, int|float|string $amount, ?string $txRef, array $options = [])bulk: array
Flutterwave::virtualAccounts()->bulk(array $data)find: array
Flutterwave::virtualAccounts()->find(string $orderRef)findBulk: array
Flutterwave::virtualAccounts()->findBulk(string $batchId)updateBvn: array
Flutterwave::virtualAccounts()->updateBvn(string $orderRef, string $bvn)delete: array
Flutterwave::virtualAccounts()->delete(string $orderRef)Flutterwave::webhooks()Webhooks
getHook: array
Flutterwave::webhooks()->getHook()verifySignature: boolVerify the `verif-hash` header sent by Flutterwave.
Flutterwave::webhooks()->verifySignature(string $data, ?string $signature)isValid: boolVerify a webhook using whichever signature header Flutterwave sent.
Flutterwave::webhooks()->isValid(string $body, ?string $verifHash, ?string $hmacSignature = null)eventAfterHook: void
Flutterwave::webhooks()->eventAfterHook(callable $func)eventBeforeHook: void
Flutterwave::webhooks()->eventBeforeHook(callable $func)At a glance
| Accessor | Class | Methods |
|---|---|---|
Flutterwave::balances() | Balances | all, currency |
Flutterwave::banks() | Banks | all, options, branches, resolveAccount, resolveMerchant |
Flutterwave::beneficiaries() | Beneficiaries | create, all, find, delete, panel |
Flutterwave::bills() | Bills | categories, billers, items, validate, pay, payValidated, status, history |
Flutterwave::bvn() | Bvn | requestConsent, verification, matches |
Flutterwave::cards() | Cards | bin, charge, preauthorize, chargeMany, bulkStatus, bulkTransactions, updateToken |
Flutterwave::chargebacks() | Chargebacks | all, find, accept, decline, uploadProof, declineWithProof, panel |
Flutterwave::fx() | Fx | quote, findQuote, trade, findTrade, tradeIfReady, panel |
Flutterwave::use('modals') | Modal | render, displayInline, prepare |
Flutterwave::plans() | PaymentPlans | create, all, find, update, cancel |
Flutterwave::payoutSubaccounts() | PayoutSubaccounts | create, all, find, update, balance, transactions, staticAccount, delete |
Flutterwave::preauth() | Preauthorizations | capture, void, refund |
Flutterwave::refunds() | Refunds | all, find, panel |
Flutterwave::settlements() | Settlements | all, find, panel |
Flutterwave::stablecoins() | Stablecoins | send, fund, fee, find, balances |
Flutterwave::subaccounts() | Subaccounts | create, all, find, update, delete |
Flutterwave::subscriptions() | Subscriptions | all, activate, cancel |
Flutterwave::transactions() | Transactions | verify, verifyTransactionReference, refund, all, fees, fee, resendFailedHooks, panel, timeline, generateTransactionReference |
Flutterwave::transfers() | Transfers | create, bulk, find, all, fee, rates, retry, retries |
Flutterwave::virtualAccounts() | VirtualAccounts | create, dynamic, dynamicFor, bulk, find, findBulk, updateBvn, delete |
Flutterwave::webhooks() | Webhooks | getHook, verifySignature, isValid, eventAfterHook, eventBeforeHook |