Skip to content

Services ​

Each Flutterwave API area is a service class, reached through the facade. Methods return Flutterwave's decoded JSON response as an array.

php
use Flutterwave\Payments\Facades\Flutterwave;

Flutterwave::transfers()->create([...]);
Flutterwave::use('transfers')->create([...]);   // same thing, by config key

Errors ​

When the API returns an error, methods throw Flutterwave\Payments\Exception\FlutterwaveException (or its NetworkConnection subclass when Flutterwave can't be reached):

php
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
php
Flutterwave::balances()->all()
currency: array
php
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.
php
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.
php
Flutterwave::banks()->options(string $country = 'NG')
branches: array
php
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).
php
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.
php
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.
php
Flutterwave::beneficiaries()->create(string $accountNumber, string $bankCode, ?string $name = null, ?string $currency = null, ?string $bankName = null)
all: array
php
Flutterwave::beneficiaries()->all(array $filters = [])
find: array
php
Flutterwave::beneficiaries()->find(int|string $id)
delete: array
php
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).
php
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
php
Flutterwave::bills()->categories(string $country = 'NG')
billers: array
php
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).
php
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.
php
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.
php
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.
php
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).
php
Flutterwave::bills()->status(string $reference)
history: arrayFilters: status (Successful, Failed, Reversed), from, to, page, limit, reference, category, country.
php
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).
php
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.
php
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.
php
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.
php
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.
php
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.
php
Flutterwave::cards()->preauthorize(string $token, string $email, int|float|string $amount, array $options = [])
php
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.
php
Flutterwave::cards()->chargeMany(array $charges, array $retryStrategy = [], ?string $title = null)
bulkStatus: array
php
Flutterwave::cards()->bulkStatus(int|string $bulkId)
bulkTransactions: array
php
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.
php
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.
php
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.
php
Flutterwave::chargebacks()->find(string $flwRef)
accept: arrayAccept the chargeback: the customer gets their money back.
php
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.
php
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().
php
Flutterwave::chargebacks()->uploadProof(string|SplFileInfo $file)
declineWithProof: arrayUpload the evidence and decline the chargeback in one call.
php
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.
php
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.
php
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.
php
Flutterwave::fx()->findQuote(string $quoteId)
trade: arrayExecute a READY quote. Each quote can only be traded once.
php
Flutterwave::fx()->trade(string $quoteId, string $narration, array $meta = [])
findTrade: array
php
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.
php
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.
php
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).
php
Flutterwave::use('modals')->render(array $data, string $type = 'inline')
displayInline: View
php
Modal::displayInline(array $data)
prepare: arrayFill in defaults so callers only need an amount and an email.
php
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
php
Flutterwave::plans()->create(string $name, int|float $amount, string $interval, ?int $duration = null, ?string $currency = null)
all: array
php
Flutterwave::plans()->all(array $filters = [])
find: array
php
Flutterwave::plans()->find(int|string $id)
update: arrayUpdate the name and/or status ("active") of a plan.
php
Flutterwave::plans()->update(int|string $id, array $data)
cancel: array
php
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
php
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).
php
Flutterwave::payoutSubaccounts()->all(array $filters = [])
find: array
php
Flutterwave::payoutSubaccounts()->find(string $accountReference)
update: arrayRequired keys: account_name, email, mobilenumber. Optional: country.
php
Flutterwave::payoutSubaccounts()->update(string $accountReference, array $data)
balance: array
php
Flutterwave::payoutSubaccounts()->balance(string $accountReference, ?string $currency = null)
transactions: arrayCredits and debits between two dates (YYYY-MM-DD). Filters: currency, page, fetch_limit.
php
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.
php
Flutterwave::payoutSubaccounts()->staticAccount(string $accountReference, bool $all = false)
delete: arrayDeactivate the wallet. Flutterwave processes this in the background.
php
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.
php
Flutterwave::preauth()->capture(string $flwRef, int|float|string $amount)
void: arrayRelease the hold without charging the customer.
php
Flutterwave::preauth()->void(string $flwRef)
refund: arrayGive back money you already captured.
php
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.
php
Flutterwave::refunds()->all(array $filters = [])
find: arrayFetch one refund by its id (data.id in the refund response).
php
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.
php
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.
php
Flutterwave::settlements()->all(array $filters = [])
find: arrayOne settlement, with the transactions it paid out (`data.transactions`).
php
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.
php
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.
php
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).
php
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.
php
Flutterwave::stablecoins()->fee(int|float $amount, string $coin, ?string $debitCurrency = null)
find: arrayFetch a stablecoin transfer to check its status.
php
Flutterwave::stablecoins()->find(int|string $id)
balances: arrayYour stablecoin wallet balances, keyed by coin.
php
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.
php
Flutterwave::subaccounts()->create(array $data)
all: array
php
Flutterwave::subaccounts()->all(array $filters = [])
find: array
php
Flutterwave::subaccounts()->find(int|string $id)
update: array
php
Flutterwave::subaccounts()->update(int|string $id, array $data)
delete: array
php
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...
php
Flutterwave::subscriptions()->all(array $filters = [])
activate: array
php
Flutterwave::subscriptions()->activate(int|string $id)
cancel: array
php
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
php
Flutterwave::transactions()->verify(int|string $transactionId)
verifyTransactionReference: arrayVerify a transaction with tx_ref
php
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).
php
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.
php
Flutterwave::transactions()->all(?array $data = null)
fees: arrayGet transaction fee by supplying amount and currency
php
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.
php
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.
php
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.
php
Flutterwave::transactions()->panel(array $query = [])
timeline: arrayGet the timeline of a transaction using transactionId
php
Flutterwave::transactions()->timeline(int|string $transactionId)
generateTransactionReference: stringGenerates a Transaction Reference for Payment Request
php
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.
php
Flutterwave::transfers()->create(array $data)
bulk: arraySend many transfers at once. Each item follows the same shape as create().
php
Flutterwave::transfers()->bulk(array $transfers, ?string $title = null)
find: array
php
Flutterwave::transfers()->find(int|string $id)
all: array
php
Flutterwave::transfers()->all(array $filters = [])
fee: array
php
Flutterwave::transfers()->fee(int|float $amount, string $currency = 'NGN', ?string $type = null)
rates: arrayGet the exchange rate for a cross-currency transfer.
php
Flutterwave::transfers()->rates(int|float $amount, string $destinationCurrency, string $sourceCurrency)
retry: array
php
Flutterwave::transfers()->retry(int|string $id)
retries: array
php
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.
php
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.
php
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).
php
Flutterwave::virtualAccounts()->dynamicFor(string $email, int|float|string $amount, ?string $txRef, array $options = [])
bulk: array
php
Flutterwave::virtualAccounts()->bulk(array $data)
find: array
php
Flutterwave::virtualAccounts()->find(string $orderRef)
findBulk: array
php
Flutterwave::virtualAccounts()->findBulk(string $batchId)
updateBvn: array
php
Flutterwave::virtualAccounts()->updateBvn(string $orderRef, string $bvn)
delete: array
php
Flutterwave::virtualAccounts()->delete(string $orderRef)

Flutterwave::webhooks()Webhooks

getHook: array
php
Flutterwave::webhooks()->getHook()
verifySignature: boolVerify the `verif-hash` header sent by Flutterwave.
php
Flutterwave::webhooks()->verifySignature(string $data, ?string $signature)
isValid: boolVerify a webhook using whichever signature header Flutterwave sent.
php
Flutterwave::webhooks()->isValid(string $body, ?string $verifHash, ?string $hmacSignature = null)
eventAfterHook: void
php
Flutterwave::webhooks()->eventAfterHook(callable $func)
eventBeforeHook: void
php
Flutterwave::webhooks()->eventBeforeHook(callable $func)

At a glance ​

AccessorClassMethods
Flutterwave::balances()Balancesall, currency
Flutterwave::banks()Banksall, options, branches, resolveAccount, resolveMerchant
Flutterwave::beneficiaries()Beneficiariescreate, all, find, delete, panel
Flutterwave::bills()Billscategories, billers, items, validate, pay, payValidated, status, history
Flutterwave::bvn()BvnrequestConsent, verification, matches
Flutterwave::cards()Cardsbin, charge, preauthorize, chargeMany, bulkStatus, bulkTransactions, updateToken
Flutterwave::chargebacks()Chargebacksall, find, accept, decline, uploadProof, declineWithProof, panel
Flutterwave::fx()Fxquote, findQuote, trade, findTrade, tradeIfReady, panel
Flutterwave::use('modals')Modalrender, displayInline, prepare
Flutterwave::plans()PaymentPlanscreate, all, find, update, cancel
Flutterwave::payoutSubaccounts()PayoutSubaccountscreate, all, find, update, balance, transactions, staticAccount, delete
Flutterwave::preauth()Preauthorizationscapture, void, refund
Flutterwave::refunds()Refundsall, find, panel
Flutterwave::settlements()Settlementsall, find, panel
Flutterwave::stablecoins()Stablecoinssend, fund, fee, find, balances
Flutterwave::subaccounts()Subaccountscreate, all, find, update, delete
Flutterwave::subscriptions()Subscriptionsall, activate, cancel
Flutterwave::transactions()Transactionsverify, verifyTransactionReference, refund, all, fees, fee, resendFailedHooks, panel, timeline, generateTransactionReference
Flutterwave::transfers()Transferscreate, bulk, find, all, fee, rates, retry, retries
Flutterwave::virtualAccounts()VirtualAccountscreate, dynamic, dynamicFor, bulk, find, findBulk, updateBvn, delete
Flutterwave::webhooks()WebhooksgetHook, verifySignature, isValid, eventAfterHook, eventBeforeHook

Released under the MIT License.