DEV Community: Demola Malomo

How Does Payment Settlement Work?

Demola Malomo — Fri, 03 Apr 2026 09:19:17 +0000

You tap your card at checkout, hit “pay” in an app, or send money to a supplier, and the screen flashes “payment successful” in seconds. It feels like the money moved instantly, but the merchant informs you they haven’t received the funds yet. What you’ve actually received is confirmation that the payment process has started, not that the funds have moved.

That time gap sits at the heart of how payment settlement works. Understanding it helps developers and finance teams avoid reconciliation headaches, liquidity surprises, and unhappy customers.

This guide breaks down the full payment settlement process, explains how it differs across card payments, ACH, wire transfers, digital wallets, and cross-border transactions, and gives you a practical framework for building settlement-aware systems.

Before diving into how payment settlement works across different payment methods, let’s take a closer look at the key stages money moves through when transactions are initiated.

Key Stages of Payment Settlement

Every payment you initiate moves through three distinct phases before funds actually land where they should. From a user’s perspective, it feels like one seamless event. For you as a developer, it’s three coordinated stages involving issuers, acquirers, card networks, clearinghouses, and central banks.

Authorization

Authorization is the first checkpoint in the payment settlement process, and it’s where most developers mistakenly think the payment process ends. When a customer initiates a payment, your system sends an authorization request to the issuing bank. The bank checks if the account has available funds, runs fraud checks, and places a hold on the money. If everything looks good, you receive an approval code. This entire process typically takes two seconds or less.

The key thing to understand is that authorization is not final in the settlement process. The funds are held, but the money has not moved. That hold typically expires within five to seven days if the financial transaction does not move to the next phase. The issuer can reverse it. The customer can dispute it. Yet most payment APIs return a “success” status at this point, which is why developers often assume the money is theirs.

From a technical standpoint, this is where you integrate with payment gateways that handle the authorization request and response cycle. The “payment successful” response your API returns after integration almost always refers to authorization, not settlement. Releasing physical goods or triggering irreversible workflows at this stage introduces risk.

Clearing

After authorization, merchants submit batches of authorized transactions to the card network or ACH operator for processing, usually at the end of the business day. The payment processor takes these batches, reconciles them between banks, and determines who owes whom and the final confirmed amounts.

Clearing typically takes hours to days because it involves fraud review, amount adjustments, such as adding the final tip at a restaurant, and validation across multiple institutions. During clearing, your payment details status typically shows as pending in bank accounts and dashboards.

As a developer, this is where you start seeing the separation between your internal ledger and reality. Your API reported success yesterday, but the clearing file only went out this morning. The amount might also change slightly during this phase, which is another reason you cannot build your system assuming the authorized amount is final. That assumption can gradually throw off your accounting.

Settlement

Settlement is where money actually moves between financial institutions. The issuing bank transfers funds through the credit card payment network or ACH system to the acquiring bank, which then credits the merchant’s account.

This is the stage where you get payment finality, although what “final” means still depends on the payment rail. Settlement typically takes one to three business days for cards and standard ACH, even though faster options exist. Once the net settlement completes, the funds appear as available in the merchant account, and the transaction becomes mostly irrevocable.

As a developer, this is when you can safely trigger payouts, update available balances, and treat a payment as final for accounting purposes.

How Payment Settlement Process Works for Different Payment Types

Not all payment rails settle the same way. Choosing the right one for your use case and programming for its specific settlement behavior is a core architectural decision.

Card Payments (Visa/Mastercard)

Card networks optimize for speed at the point of sale, not at the settlement layer. When a customer pays with a credit or debit card, authorization happens in under two seconds, but settlement into the merchant account typically takes one to two business days (and can vary for both local and international payments).

A common scenario to understand is that authorization and capture can be separate API calls on most platforms. Authorization places the hold. Capture submits the transaction details for clearing. Some platforms combine them by default, while others use delayed capture flows, such as hotel incidentals or gas stations that authorize a small amount and capture the final amount later. As you integrate, make sure you understand how your API provider expects this flow to work.

Another important consideration is the finality of a card transaction. It is still disputable for 60 to 120 days after settlement. That means a payment that settled three months ago can still be reversed if the cardholder files a dispute. From a legal standpoint, the payment is final at settlement. From a practical business standpoint, you could still lose the money months later.

As a developer building card payments into a business workflow, you need to define acceptable thresholds between authorization, capture, settlement, and release of value. That might mean waiting out an initial chargeback risk period for high-value physical goods, or releasing digital products immediately where fraud exposure is lower.

ACH Payments

ACH works differently from cards. There is no upfront verification for sufficient funds. Instead, it uses a push or pull model where the Originating Depository Financial Institution (ODFI) submits a file to an ACH operator such as the Federal Reserve System or Electronic Payments Network (EPN), which then routes the transaction to the Receiving Depository Financial Institution (RDFI). For settlement, ACH offers:

Standard ACH, which settles in one to three business days
Next Day ACH, which settles in one business day
Same Day settlement ACH, which settles the same day for smaller amounts submitted before daily cutoffs

However, settlement speed does not equal finality. All ACH debits carry a 60-day return window for insufficient funds or unauthorized transactions. The money can leave your account and come back two months later with a return code like R01 (NSF) or R10 (unauthorized).

As a developer, this means you need to:

Build logic that handles return webhooks long after the initial success
Treat the transaction as still revocable while it falls within the 60-day return window
Maintain refund or reserve mechanisms to absorb potential returns

Wire Transfers

Wire transfers look straightforward from a finality standpoint but can be the most complex operationally. When a wire is initiated, there is no batching phase. Transfers move individually.

Domestic wires over Fedwire Funds Service or CHIPS typically use elements of Real-Time Gross Settlement (RTGS) to settle payments the same day if submitted before the cutoff time, usually early afternoon. International wires typically settle in one to five days. Once a wire is received by the beneficiary’s bank, it is effectively irrevocable. Recall is only possible with the recipient’s agreement, which they are under no obligation to give.

The trade-off is cost, often $15 to $35 per transaction, along with limited automatic reconciliation data. You get strong finality, but you pay for it.

Digital Wallets

Digital wallets like Apple Pay, Google Pay, PayPal, and Venmo are payment methods, not settlement rails. Under the hood, they route through existing card networks or ACH and follow the settlement behavior of those underlying systems.

Apple Pay and Google Pay tokenize card numbers by replacing the actual card number with a Device Account Number. This adds a security layer, but processing still happens through standard card network rails. Settlement usually takes one to two business days, just like a regular card transaction.

PayPal and Venmo introduce their own intermediate balance layer that is funded through ACH or a linked card. Wallet-to-wallet transfers appear instant to users, but when funds are withdrawn to a bank account, ACH timing still applies.

As a developer, you should treat wallet payments according to their funding source. Bank-funded wallet transactions behave like ACH, including the 60-day return window. The “instant” confirmation users see reflects the wallet provider absorbing settlement risk, not actual immediate fund movement.

Cross-Border Payments and SWIFT

SWIFT is often misunderstood as a settlement system, but it is not. It is a messaging network used to send payment instructions between banks. Actual settlement happens through correspondent banking relationships and domestic clearing systems.

When a user initiates a cross-border payment, it moves through a chain of correspondent banks, each deducting fees and forwarding the payment onward. This process may take one to five days before reaching the recipient.

The SWIFT Global Payments Innovation (GPI) tracker has significantly improved speed and transparency. Many GPI payments reach the beneficiary bank within minutes, and most complete within 24 hours. Even then, delays can still occur in the domestic “last mile” after the payment leaves the SWIFT network, when local clearing systems take over.

From a developer perspective, remember that SWIFT is only a messaging layer. The actual settlement happens through correspondent bank accounts. Fees are often opaque and deducted along the chain, and currency conversion adds further complexity. Modern messaging standards provide richer data for reconciliation, but you still need to track payments using the Unique End-to-End Transaction Reference (UETR), similar to a tracking number.

For more on handling multi-currency settlements, see “ Why Multi-Currency Settlements Matter for Global Businesses.”

The table below highlights the key differences between each payment type:

Payment Type	Settlement Timeline	Finality Window	Reversible?	Typical Cost	Best For
Card (Visa/MC)	1–2 business days	60–120 day chargeback window	Yes (chargebacks)	1.5–3.5% + fees	Consumer purchases
ACH	1–3 business days	60-day return window	Yes (returns)	<$1 per transaction	Payroll, subscriptions
Wire Transfer	Same day (domestic payments)	Irrevocable at receipt	No	$15–$35	Large B2B, time-sensitive
RTP/FedNow	Seconds	Irrevocable at confirmation	No	Varies	High-value, urgent
Digital Wallet	Follows underlying rail	Follows underlying rail	Follows underlying rail	Varies	Consumer UX
SWIFT (Cross-border)	1–3 business days	Irrevocable once credited	Limited recall only	$15–$50+	International B2B

After looking at how settlement works across different payment types, one thing becomes clear. Not all “successful” payments mean the same thing behind the scenes.

In many real-world transactions, a payment can appear complete to the customer, approved by the processor, and even reflected in account balances, yet the actual movement of funds may still be in progress. This is where settlement shifts from being purely technical to conceptual.

To fully understand how payment systems operate, we need to separate two ideas that are often treated as identical but are fundamentally different. When a payment is considered successful, and when it is truly final.

Payment Success vs. Payment Finality: What’s the Difference?

To truly understand payment settlement, we need to zoom out and clarify something more fundamental.

A payment can be successful without being truly final. Funds may still be moving between institutions, reversals may still be possible, and settlement may not yet be complete. This gap between what looks finished and what is legally and financially irreversible is one of the most important concepts in modern payment systems.

Legal finality is the point at which a payment becomes irrevocable under the governing payment system rules and applicable regulations, such as UCC Article 4A for wire transfers. Practical finality is different. It is the point where the risk of chargebacks or reversals drops to a level your business can tolerate. These two forms of finality often differ significantly.

Wire transfers and real-time payment rails like FedNow achieve both almost immediately. Once confirmed, they are effectively done. ACH transactions typically settle in one to three business days, but the practical finality window extends up to 60 days because of return rights. Card payments settle in one to two business days, yet chargeback risk can remain for months.

This distinction matters when designing your payment system. If you are selling digital goods with low fraud risk, you might choose to release value at authorization. For high-value physical products, you may wait for settlement and add a buffer period before release.

There are also edge cases you need to plan for. For example:

A bank failure during settlement can cause reconciliation mismatch.
Card payments can be disputed using specific reason codes, which is particularly common with international cards.
ACH disputes after months that you need to handle programmatically.

All of these can affect payments even after you think both forms of finality are covered. That is why it is important to build systems that track a payment from authorized to pending, then settled, and finally final, with timestamps at each stage. This audit trail becomes critical when something goes wrong.

Knowing how settlement works is only half the story. The real challenge lies in building systems that behave correctly at every stage of the payment lifecycle, not just at the moment of approval.

This is where settlement awareness becomes a design principle. Next, we’ll look at what it means to build systems that recognize the difference between payment activity and true financial finality.

How to Build a Settlement-Aware System

Below are key principles to consider when architecting systems that reflect the reality of asynchronous money movement.

Do Not Assume Payment Success Equals Funds Available

Separate authorization confirmation from settlement notifications. A payment moving from authorized to captured to settled represents different operational states, each with distinct implications for your business logic.

Build your system to follow a clear lifecycle:

Until you receive settlement confirmation, do not update your available ledger balance.

Design for Reconciliation

Your internal ledger will drift from your payment provider’s ledger because of settlement timelines and the different workflows each payment method follows.

Store authorization IDs, clearing IDs, settlement IDs, and other unique references separately, along with timestamps for every stage. This becomes essential when reconciling against bank statements.

You also need to account for settlement failures explicitly because they are expected to happen. ACH returns and card reversals are common scenarios, especially in consumer and fintech environments. Your system should be designed to handle them as normal operational events, not rare exceptions.

Choose the Right Payment Rail for the Job

The right rail depends on what your use case actually requires:

Use RTP or FedNow when you need instant, irrevocable finality.
Use ACH for predictable, lower-risk recurring payments such as payroll and subscriptions.
Use card payments when consumer experience and chargeback protection justify the trade-offs.
Use wire transfers for large B2B transactions where same-day finality justifies the cost.

Communicate Settlement Timing to Users

It may be tempting to promise instant payments in product messaging, but avoid that unless you are truly using real-time rails. Instead, display expected settlement dates in your UI. This sets proper expectations.

Users may not understand banking infrastructure, but they value transparency about when funds will actually arrive.

Monitor Settlement Metrics

Track authorization-to-settlement conversion rates to understand how each payment type behaves. If authorized transactions frequently fail to clear, you may have a fraud issue or an integration problem.

Alert on settlement failures that exceed your threshold and reconcile daily settled volume against authorized volume so you can detect drift early.

Even though these concepts may look straightforward, they introduce real operational complexity. Tracking payment states, handling reversals, managing reconciliation, and supporting different timelines across payment methods becomes difficult at scale.

Most teams need more than the right concepts. They need infrastructure that already understands these realities and helps manage them in a structured, reliable way.

This is where payment platforms play a critical role. Instead of building every layer of settlement logic from scratch, you can rely on tools designed to handle real-world money movement.

Let’s look at how Flutterwave helps businesses and developers handle settlement complexity in practice.

How Flutterwave Can Help You Handle Settlement Complexity

Managing settlement across different payment methods, currencies, and timelines can quickly become overwhelming, especially as transaction volume grows. What begins as simple payment tracking can evolve into layers of status updates, reconciliation checks, delayed settlements, and exception handling.

When a customer pays using their preferred payment method, Flutterwave collects the funds and holds them in your collection balance. This appears immediately on your dashboard, but the actual transfer to your bank account or Flutterwave for Business (F4B) wallet follows the timeline of the underlying payment method.

Reconciliation: Flutterwave's dashboard provides transaction-level settlement data so you can match collections against disbursements. You can export settlement reports and reconcile them against your internal ledger using settlement dates and transaction IDs.

Multi-currency settlements: For businesses operating across multiple currencies, Flutterwave handles currency conversion and settles in the currency configured for your account. This is especially important for cross-border flows, where currency exposure can increase financial risk when settlement takes multiple days. See the settlements documentation for currency-specific details.

Manual settlement: Flutterwave also supports manual settlement, allowing you to trigger payouts outside the automatic schedule. This is useful when managing cash flow around operational timelines.

Final Thoughts

Payment settlement is one of those topics where a surface-level understanding creates more problems than it solves. The developer who knows that "payments take a few days" but doesn't understand why, what it means legally, or how it differs by rail will build systems that look fine in staging and fail in production.

The mental model worth internalizing is to see authorization as a promise, clearing as accounting, and settlement as reality. Build your systems around settlement, design for failures within the return window, choose your payment rail based on finality requirements, and communicate honestly with your users about when their money actually moves.

Building an Agentic Commerce App with Flutterwave v4 APIs

Demola Malomo — Tue, 24 Mar 2026 09:41:38 +0000

Chat commerce is quietly reshaping how people buy things online. Instead of navigating through pages of product listings, clicking through checkout flows, and filling out forms, customers simply say what they want and get it. This means no app downloads, no account creation screens, or cart abandonment anxiety. Just a conversation.

For developers, this shift is equally interesting. You're no longer building complex frontends with product grids, shopping carts, and multi-step checkout forms. Instead, you're wiring together an AI agent, a messaging platform, and a payment provider. Then letting the conversation be the interface.

In this tutorial, I'll walk you through how I built Scent House of Aromas, an AI-powered perfume shop that lives entirely inside Telegram. Customers browse perfumes, ask questions, place orders, and pay without ever leaving a chat window. The AI handles the conversation, Flutterwave handles the money, and there's literally no frontend to build.

What Makes Chat Commerce Different?

If you've built a traditional e-commerce platform before, you know how complex it can get. You need a product catalog UI, search and filtering, a shopping cart, a checkout flow, payment integration with redirect pages, order confirmation screens, email notifications, and the list goes on. That's a lot of surface area for bugs, design decisions, and user drop-off.

Chat commerce flips this model and strips away majority of this complexity:

No UI Complexity: There's no frontend to design, build, or maintain. The messaging app is your UI. Telegram handles rendering, notifications, and cross-device sync for you.
Works Across Every Device: If a customer has Telegram on their phone, tablet, laptop, or even their smart TV, your store works. No responsive design headaches.
Users Already Know How to Use it: Nobody needs a tutorial for sending a text message. Your customers are already power users of the interface.
Payments Feel Natural: Instead of redirecting users to a payment page (and hoping they come back), you generate a virtual account right in the chat. The customer opens their banking app, makes a transfer, and gets a confirmation message; all without context-switching.
AI does the Heavy Lifting: An AI agent can understand natural language queries ("show me something fresh under 20k"), make product recommendations, and guide customers through checkout conversationally. It's like having a knowledgeable sales associate available 24/7.

For businesses, the conversion advantage is also massive. There's no cart to abandon or customers getting bored filling forms. The customer tells the bot what they want, the bot handles the rest, and payment is a simple bank transfer.

What we're Building

From a customer’s perspective, this is how Scent House of Aromas works:

A customer opens the Telegram bot and says something like "What perfumes do you have?"
The AI agent searches the product catalog and responds with options
The customer asks for more details or says "I'll take the Velvet Rose"
The agent creates an order and generates a virtual bank account via Flutterwave
The customer transfers the exact amount from their banking app
Flutterwave confirms the payment via webhook, the order is marked as paid, and the customer gets a confirmation message in the chat

The Tech Stack

TypeScript + Express: Our server and API layer
grammY: Telegram Bot framework for Node.js
OpenAI GPT-4o: The AI brain with tool-calling capabilities
Supabase: PostgreSQL database for users, products, and orders
Flutterwave: Payment processing via dynamic virtual accounts

Architecture Overview

The AI agent sits at the center of everything. It takes the user’s natural language input, decides which tools to call, whether that is searching products, creating an order, or generating a payment account, and then responds in a conversational way.

Thanks to the tool-calling loop, the agent can chain multiple actions within a single interaction. For example, it can create an order and generate payment details all in one go.

Prerequisites

Before we start building, make sure you have:

Node.js (v18 or later) installed
A Telegram Bot Token: created via @BotFather on Telegram
An OpenAI API key: from OpenAI or any other AI model provider like OpenRouter that supports OpenAI GPT-4o
A Supabase project: free tier at Supabase
A Flutterwave account: sign up at Flutterwave

Project Setup

Let's scaffold the project:

mkdir telegram_flw_agent_commerce
cd telegram_flw_agent_commerce
npm init -y

Install the dependencies:

npm install express cors dotenv grammy openai @supabase/supabase-js
npm install -D typescript tsx @types/node @types/express @types/cors

Initialize TypeScript:

npx tsc --init

Update your tsconfig.json:

{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "lib": ["ES2020"],
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "resolveJsonModule": true,
        "declaration": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "dist"]
}

Update the scripts section of package.json:

{
    "scripts": {
        "dev": "tsx watch src/server.ts",
        "build": "tsc",
        "start": "node dist/server.js"
    }
}

Create a .env file in the project root:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
OPENAI_API_KEY=your_openai_api_key
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_KEY=your_supabase_service_role_key
FLW_CLIENT_ID=your_flutterwave_client_id
FLW_CLIENT_SECRET=your_flutterwave_client_secret
FLW_WEBHOOK_SECRET_HASH=your_flutterwave_webhook_secret
FLW_BASE_URL=https://developersandbox-api.flutterwave.com

Note: The FLW_BASE_URL points to Flutterwave's sandbox environment for development. When you're ready for production, you'll switch this to the live API URL.

Now let's create the folder structure:

src/
├── agent/
│   ├── index.ts        # AI agent logic + tool-calling loop
│   ├── prompt.ts       # System prompt for the AI
│   └── tools.ts        # Tool definitions + execution
├── bot/
│   └── index.ts        # Telegram bot handlers
├── database/
│   ├── schema.sql      # Database schema
│   ├── seed.sql        # Sample product data
│   └── supabase.ts     # Supabase client
├── routes/
│   ├── orders.ts       # Order creation endpoint
│   ├── payments.ts     # Payment generation endpoint
│   ├── products.ts     # Product catalog endpoints
│   └── webhooks.ts     # Flutterwave webhook handler
├── services/
│   └── flutterwave.ts  # Flutterwave API wrapper
└── server.ts           # Express app entry point

Setting up the Database

Head over to your Supabase dashboard and run the following SQL in the SQL Editor. First, the schema:

CREATE TABLE IF NOT EXISTS users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  telegram_id BIGINT UNIQUE NOT NULL,
  first_name TEXT,
  username TEXT,
  flw_customer_id TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS products (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  brand TEXT NOT NULL,
  description TEXT,
  price NUMERIC(10,2) NOT NULL,
  inventory INTEGER DEFAULT 100,
  category TEXT,
  notes TEXT,
  image_url TEXT
);

CREATE TABLE IF NOT EXISTS orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  product_id TEXT REFERENCES products(id),
  amount NUMERIC(10,2) NOT NULL,
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'paid', 'failed')),
  flw_reference TEXT,
  virtual_account_number TEXT,
  virtual_account_bank TEXT,
  virtual_account_expiry TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Three tables, each with a clear purpose:

users: Tracks Telegram users and their linked Flutterwave customer IDs
products: The perfume catalog with names, prices, descriptions, and categories
orders: Purchase records that track payment status and virtual account details

Then seed it with some sample perfumes:

INSERT INTO products (id, name, brand, description, price, inventory, category, notes, image_url) VALUES
  ('p1', 'Bleu Classic', 'Maison Bleu', 'A refreshing everyday scent with citrus top notes and a warm woody base. Perfect for daytime wear.', 25000.00, 100, 'fresh', 'citrus, woody', 'https://images.unsplash.com/photo-1523293182086-7651a899d37f?w=400'),
  ('p2', 'Midnight Oud', 'Desert Essence', 'Rich and luxurious oud fragrance with deep amber undertones. A statement scent for evening occasions.', 45000.00, 50, 'luxury', 'oud, amber', 'https://images.unsplash.com/photo-1541643600914-78b084683601?w=400'),
  ('p3', 'Velvet Rose', 'Flora Atelier', 'Elegant rose perfume with a soft musk base. Romantic and timeless.', 22000.00, 80, 'floral', 'rose, musk', 'https://images.unsplash.com/photo-1588405748880-12d1d2a59f75?w=400'),
  ('p4', 'Ocean Mist', 'Coastal Labs', 'Light and breezy sea-inspired fragrance with citrus accents. Great for casual everyday use.', 18000.00, 120, 'fresh', 'sea salt, citrus', 'https://images.unsplash.com/photo-1592945403244-b3fbafd7f539?w=400'),
  ('p5', 'Noir Vanilla', 'Maison Noir', 'Warm and inviting vanilla perfume with subtle spice notes. Cozy and sophisticated.', 32000.00, 60, 'warm', 'vanilla, spice', 'https://images.unsplash.com/photo-1594035910387-fea081ccfcfa?w=400')
ON CONFLICT (id) DO NOTHING;

Now, create the Supabase client in src/database/supabase.ts:

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.SUPABASE_URL!;
const supabaseKey = process.env.SUPABASE_SERVICE_KEY!;

export const supabase = createClient(supabaseUrl, supabaseKey);

We're using the service role key here because this is a server-side application. The bot needs full access to read and write user, product, and order data.

Integrating Flutterwave

Beyond hosted checkouts, Flutterwave also offers flexible APIs you can plug into any application. For our agentic commerce, we’ll use the dynamic virtual account API. The customer gets account details right in the chat, transfers the money from their banking app, and Flutterwave notifies us when the payment lands.

Authentication

Flutterwave uses OAuth2 client credentials for API authentication. We'll manage token refresh automatically:
Create src/services/flutterwave.ts:

let accessToken: string | null = null;
let expiresIn = 0;
let lastRefreshTime = 0;

const TOKEN_URL =
    'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token';

function getBaseUrl(): string {
    return (
        process.env.FLW_BASE_URL ||
        'https://developersandbox-api.flutterwave.com'
    );
}

async function refreshToken(): Promise<void> {
    if (!process.env.FLW_CLIENT_ID || !process.env.FLW_CLIENT_SECRET) {
        throw new Error('Missing FLW_CLIENT_ID or FLW_CLIENT_SECRET in .env');
    }

    const response = await fetch(TOKEN_URL, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
            client_id: process.env.FLW_CLIENT_ID,
            client_secret: process.env.FLW_CLIENT_SECRET,
            grant_type: 'client_credentials',
        }),
    });

    const data = (await response.json()) as Record<string, unknown>;

    if (!data.access_token) {
        console.error('[FLW] Token refresh failed:', JSON.stringify(data));
        throw new Error('Failed to obtain Flutterwave access token');
    }

    accessToken = data.access_token as string;
    expiresIn = data.expires_in as number;
    lastRefreshTime = Date.now();
    console.log('[FLW] Token refreshed, expires in', expiresIn, 'seconds');
}

async function getAccessToken(): Promise<string> {
    const elapsed = (Date.now() - lastRefreshTime) / 1000;
    const remaining = expiresIn - elapsed;

    if (!accessToken || remaining < 60) {
        await refreshToken();
    }

    return accessToken!;
}

A few things to note here:

We cache the access token in memory and only refresh when it's about to expire (less than 60 seconds remaining).
The getBaseUrl() function lets us switch between sandbox and production environments via the FLW_BASE_URL environment variable.

Generic API Request Helper

Next, let's build a reusable request function that handles auth headers, idempotency keys, and scenario keys (used for sandbox testing):

interface FlwRequestOptions {
    method: string;
    path: string;
    body?: Record<string, unknown>;
    idempotencyKey?: string;
    scenarioKey?: string;
}

export async function flwRequest<T>(options: FlwRequestOptions): Promise<T> {
    const token = await getAccessToken();

    const headers: Record<string, string> = {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
        Accept: 'application/json',
    };

    if (options.idempotencyKey) {
        headers['X-Idempotency-Key'] = options.idempotencyKey;
    }

    if (options.scenarioKey) {
        headers['X-Scenario-Key'] = options.scenarioKey;
    }

    const url = `${getBaseUrl()}${options.path}`;
    const response = await fetch(url, {
        method: options.method,
        headers,
        body: options.body ? JSON.stringify(options.body) : undefined,
    });

    const result = (await response.json()) as T;

    if ((result as Record<string, unknown>).status !== 'success') {
        console.error(
            `[FLW] ${options.method} ${options.path} failed:`,
            JSON.stringify(result),
        );
    }

    return result;
}

The X-Idempotency-Key header is important becuase it prevents duplicate charges if a request is accidentally sent twice. We generate a unique UUID for each payment operation.

Creating Customers and Virtual Accounts

Now, the two core Flutterwave operations we need:

interface FlwCustomerResponse {
    status: string;
    data: { id: string; email: string };
}

export async function createFlwCustomer(
    firstName: string,
    lastName: string,
    email: string,
    idempotencyKey: string,
): Promise<FlwCustomerResponse> {
    return flwRequest<FlwCustomerResponse>({
        method: 'POST',
        path: '/customers',
        body: {
            name: { first: firstName, last: lastName },
            email,
        },
        idempotencyKey,
    });
}

interface VirtualAccountData {
    id: string;
    amount: number;
    account_number: string;
    reference: string;
    account_bank_name: string;
    account_type: string;
    status: string;
    account_expiration_datetime: string;
    note: string;
    customer_id: string;
}

interface FlwVirtualAccountResponse {
    status: string;
    data: VirtualAccountData;
}

export async function createDynamicVirtualAccount(
    reference: string,
    customerId: string,
    amount: number,
    currency: string,
    narration: string,
    expirySeconds: number = 3600,
    idempotencyKey: string,
    scenarioKey?: string,
): Promise<FlwVirtualAccountResponse> {
    return flwRequest<FlwVirtualAccountResponse>({
        method: 'POST',
        path: '/virtual-accounts',
        body: {
            reference,
            customer_id: customerId,
            amount,
            currency,
            account_type: 'dynamic',
            narration,
            expiry: expirySeconds,
        },
        idempotencyKey,
        scenarioKey,
    });
}

The flow works like this: first, we create a Flutterwave customer. This happens only once per user, and we store the flw_customer_id in our database. Next, we generate a dynamic virtual account for each order. The virtual account is temporary, expires after a set time (we use 3600 seconds, or 1 hour), and is locked to the exact order amount.

Lastly, we need a function to verify charges when we receive webhooks:

interface FlwChargeResponse {
    status: string;
    data: {
        id: string;
        amount: number;
        currency: string;
        reference: string;
        status: string;
    };
}

export async function verifyCharge(
    chargeId: string,
): Promise<FlwChargeResponse> {
    return flwRequest<FlwChargeResponse>({
        method: 'GET',
        path: `/charges/${chargeId}`,
    });
}

Building the AI Agent

This is the brain of the operation. We're using OpenAI's tool-calling feature, which lets the model decide when to call our functions and what arguments to pass. The agent doesn't just generate text, it takes actions.

The System Prompt

Create src/agent/prompt.ts:

export const SYSTEM_PROMPT = `You are Scent House of Aromas, a friendly and knowledgeable perfume shopping assistant for a boutique perfume store.

Your role:
- Help customers discover perfumes based on their preferences
- Provide details about specific perfumes when asked
- Guide customers through placing orders and completing payments
- Be warm, conversational, and use occasional perfume-related emojis

Rules:
- ALWAYS use the search_perfumes tool when a customer asks about perfumes. Never invent products.
- ALWAYS use the get_perfume tool to fetch details before describing a specific perfume.
- When a customer wants to buy, use create_order then create_payment to generate bank transfer details.
- When showing a single perfume's details, include the image using this exact format on its own line: [IMAGE:url] — the bot will render it as a photo.
- When showing multiple perfumes in a list, do NOT include images.
- Prices are in Nigerian Naira (₦). Format them with commas (e.g. ₦25,000).
- When showing payment details, clearly display the account number, bank name, amount, and expiry.
- Keep responses concise and formatted for Telegram (use Markdown).
- If you have no matching products, say so honestly and suggest broadening the search.
- When showing multiple perfumes, use a numbered list with name, brand, and price.
- After sharing payment details, remind the customer to transfer the exact amount and that they'll receive confirmation once payment is received.`;

The prompt is crucial. A few design decisions worth calling out:

We tell the agent to never invent products; it must always use the search tool. This prevents hallucinated product names and prices.
The [IMAGE:url] convention is a simple protocol between the agent and the bot code. The agent outputs this marker, and the bot code detects it and sends a photo message instead of plain text.
We explicitly tell the agent the order of operations for purchases: create_order → create_payment. The tool-calling loop handles this automatically.

Defining the Tools

Create src/agent/tools.ts. This file defines what tools the AI agent has access to and what happens when it calls them:

import { supabase } from '../database/supabase';
import {
    createFlwCustomer,
    createDynamicVirtualAccount,
} from '../services/flutterwave';
import crypto from 'crypto';

export const toolDefinitions = [
    {
        type: 'function' as const,
        function: {
            name: 'search_perfumes',
            description:
                'Search the perfume catalog by keyword. Matches against name, brand, category, notes, and description.',
            parameters: {
                type: 'object',
                properties: {
                    query: {
                        type: 'string',
                        description:
                            "Search query (e.g. 'fresh', 'under 20000', 'floral', 'oud')",
                    },
                },
                required: ['query'],
            },
        },
    },
    {
        type: 'function' as const,
        function: {
            name: 'get_perfume',
            description:
                'Get detailed information about a specific perfume by its product ID.',
            parameters: {
                type: 'object',
                properties: {
                    product_id: {
                        type: 'string',
                        description: "The product ID (e.g. 'p1', 'p2')",
                    },
                },
                required: ['product_id'],
            },
        },
    },
    {
        type: 'function' as const,
        function: {
            name: 'create_order',
            description:
                'Create a new order for a perfume. Use this when the customer confirms they want to purchase.',
            parameters: {
                type: 'object',
                properties: {
                    product_id: {
                        type: 'string',
                        description: 'The product ID to order',
                    },
                    user_id: {
                        type: 'string',
                        description: "The user's database UUID",
                    },
                },
                required: ['product_id', 'user_id'],
            },
        },
    },
    {
        type: 'function' as const,
        function: {
            name: 'create_payment',
            description:
                'Generate a virtual bank account for the customer to pay into. Use after create_order. Returns bank account details the customer should transfer to.',
            parameters: {
                type: 'object',
                properties: {
                    order_id: {
                        type: 'string',
                        description: 'The order UUID',
                    },
                },
                required: ['order_id'],
            },
        },
    },
];

These four tools give the agent everything it needs to run the full shopping experience. Notice how the descriptions guide the model on when to use each tool. For example, create_payment says "Use after create_order," which helps the agent sequence the calls correctly.

Now for the tool execution logic:

export async function executeTool(
    name: string,
    args: Record<string, string>,
): Promise<string> {
    switch (name) {
        case 'search_perfumes': {
            const query = args.query;
            const priceMatch = query.match(/under\s+[₦]?(\d[\d,]*)/i);

            let supabaseQuery = supabase.from('products').select('*');

            if (priceMatch) {
                const price = parseInt(priceMatch[1].replace(/,/g, ''));
                supabaseQuery = supabaseQuery.lte('price', price);
            }

            const textQuery = query.replace(/under\s+[₦]?\d[\d,]*/i, '').trim();
            if (textQuery) {
                supabaseQuery = supabaseQuery.or(
                    `name.ilike.%${textQuery}%,brand.ilike.%${textQuery}%,category.ilike.%${textQuery}%,notes.ilike.%${textQuery}%,description.ilike.%${textQuery}%`,
                );
            }

            const { data, error } = await supabaseQuery;
            if (error) return JSON.stringify({ error: error.message });
            if (!data || data.length === 0)
                return JSON.stringify({
                    message: 'No perfumes found matching your search.',
                });
            return JSON.stringify(data);
        }

        case 'get_perfume': {
            const { data, error } = await supabase
                .from('products')
                .select('*')
                .eq('id', args.product_id)
                .single();
            if (error) return JSON.stringify({ error: 'Perfume not found' });
            return JSON.stringify(data);
        }

        case 'create_order': {
            const { data: product } = await supabase
                .from('products')
                .select('price')
                .eq('id', args.product_id)
                .single();

            if (!product) return JSON.stringify({ error: 'Product not found' });

            const { data: order, error } = await supabase
                .from('orders')
                .insert({
                    product_id: args.product_id,
                    user_id: args.user_id,
                    amount: product.price,
                    status: 'pending',
                })
                .select()
                .single();

            if (error) return JSON.stringify({ error: error.message });
            return JSON.stringify(order);
        }

        case 'create_payment': {
            const { data: order } = await supabase
                .from('orders')
                .select('*, users(*), products(*)')
                .eq('id', args.order_id)
                .single();

            if (!order) return JSON.stringify({ error: 'Order not found' });

            let customerId = order.users.flw_customer_id;

            // Create a Flutterwave customer if this is the user's first purchase
            if (!customerId) {
                const customerRes = await createFlwCustomer(
                    order.users.first_name || 'Customer',
                    order.users.username || 'User',
                    `${order.users.telegram_id}@telegram.user`,
                    crypto.randomUUID(),
                );

                if (customerRes.status !== 'success')
                    return JSON.stringify({
                        error: 'Failed to create payment customer',
                    });

                customerId = customerRes.data.id;

                await supabase
                    .from('users')
                    .update({ flw_customer_id: customerId })
                    .eq('id', order.users.id);
            }

            // Generate a unique reference for this order
            const reference = `ord${Date.now().toString(36)}${crypto
                .randomUUID()
                .replace(/-/g, '')
                .slice(0, 8)}`;

            const vaRes = await createDynamicVirtualAccount(
                reference,
                customerId,
                order.amount,
                'NGN',
                `Payment for ${order.products.name}`,
                3600,
                crypto.randomUUID(),
            );

            if (vaRes.status !== 'success')
                return JSON.stringify({
                    error: 'Failed to generate payment account',
                });

            const va = vaRes.data;

            // Save virtual account details to the order
            await supabase
                .from('orders')
                .update({
                    flw_reference: reference,
                    virtual_account_number: va.account_number,
                    virtual_account_bank: va.account_bank_name,
                    virtual_account_expiry: va.account_expiration_datetime,
                })
                .eq('id', args.order_id);

            return JSON.stringify({
                account_number: va.account_number,
                bank_name: va.account_bank_name,
                amount: order.amount,
                reference,
                expires_at: va.account_expiration_datetime,
            });
        }

        default:
            return JSON.stringify({ error: `Unknown tool: ${name}` });
    }
}

The create_payment tool is where Flutterwave integration really comes together. Let's break down what happens:

We look up the order along with its associated user and product data
If the user doesn't have a Flutterwave customer ID yet, we create one (this only happens on their first purchase)
We generate a unique payment reference and request a dynamic virtual account from Flutterwave
We save the virtual account details back to the order record
We return the account number, bank name, amount, and expiry to the agent, which presents them conversationally to the user

The Agent Loop

Create src/agent/index.ts. This is where we wire the AI model to the tools:

import OpenAI from 'openai';
import { SYSTEM_PROMPT } from './prompt';
import { toolDefinitions, executeTool } from './tools';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

type Message = OpenAI.ChatCompletionMessageParam;

const conversationHistory = new Map<string, Message[]>();

export async function handleAgentMessage(
    userId: string,
    telegramId: string,
    userMessage: string,
): Promise<string> {
    const history = conversationHistory.get(telegramId) || [];

    history.push({ role: 'user', content: userMessage });

    const messages: Message[] = [
        {
            role: 'system',
            content: `${SYSTEM_PROMPT}\n\nCurrent user's database ID: ${userId}`,
        },
        ...history,
    ];

    let response = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages,
        tools: toolDefinitions,
    });

    let choice = response.choices[0];

    // Handle tool call loop — agent may chain multiple tools
    while (choice.finish_reason === 'tool_calls' && choice.message.tool_calls) {
        const assistantMessage = choice.message;
        history.push(assistantMessage);

        const toolCalls = assistantMessage.tool_calls!;
        for (const toolCall of toolCalls) {
            const fn = toolCall as {
                id: string;
                type: 'function';
                function: { name: string; arguments: string };
            };
            const args = JSON.parse(fn.function.arguments);
            const result = await executeTool(fn.function.name, args);

            history.push({
                role: 'tool',
                tool_call_id: toolCall.id,
                content: result,
            });
        }

        response = await openai.chat.completions.create({
            model: 'gpt-4o',
            messages: [
                {
                    role: 'system',
                    content: `${SYSTEM_PROMPT}\n\nCurrent user's database ID: ${userId}`,
                },
                ...history,
            ],
            tools: toolDefinitions,
        });

        choice = response.choices[0];
    }

    const reply =
        choice.message.content || "I couldn't process that. Please try again.";
    history.push({ role: 'assistant', content: reply });

    // Keep history manageable (last 20 messages)
    if (history.length > 20) {
        conversationHistory.set(telegramId, history.slice(-20));
    } else {
        conversationHistory.set(telegramId, history);
    }

    return reply;
}

The key pattern here is the tool-calling loop. Here's what's happening:

We send the conversation to OpenAI with our tool definitions
If the model decides to call a tool, the finish_reason will be "tool_calls" instead of "stop"
We execute each tool call and push the results back into the conversation history
We send the updated conversation back to OpenAI, which might call more tools or generate a final text response
This loop continues until the model responds with text (no more tool calls)

This is what makes the agent powerful. In a single user message like "I want to buy the Velvet Rose", the agent can chain get_perfume → create_order → create_payment across multiple loop iterations and respond with a complete message containing the product details and payment instructions.

We also keep the conversation history capped at 20 messages per user to keep token usage reasonable.

Building the Telegram Bot

Create src/bot/index.ts:

import { Bot } from 'grammy';
import { supabase } from '../database/supabase';
import { handleAgentMessage } from '../agent';

export const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);

bot.command('start', async (ctx) => {
    const telegramId = ctx.from?.id;
    if (!telegramId) return;

    await supabase.from('users').upsert(
        {
            telegram_id: telegramId,
            first_name: ctx.from?.first_name || null,
            username: ctx.from?.username || null,
        },
        { onConflict: 'telegram_id' },
    );

    await ctx.reply(
        'Welcome to *Scent House of Aromas*\n\n' +
            'I can help you discover perfumes and place orders.\n\n' +
            'Try asking:\n' +
            '- "Show me fresh perfumes"\n' +
            '- "What do you have under 20,000?"\n' +
            '- "Tell me about Velvet Rose"',
        { parse_mode: 'Markdown' },
    );
});

bot.on('message:text', async (ctx) => {
    const telegramId = ctx.from.id;
    const userMessage = ctx.message.text;

    let { data: user } = await supabase
        .from('users')
        .select('id')
        .eq('telegram_id', telegramId)
        .single();

    if (!user) {
        const { data: newUser } = await supabase
            .from('users')
            .insert({
                telegram_id: telegramId,
                first_name: ctx.from.first_name || null,
                username: ctx.from.username || null,
            })
            .select('id')
            .single();
        user = newUser;
    }

    if (!user) {
        await ctx.reply('Something went wrong. Please try /start again.');
        return;
    }

    const response = await handleAgentMessage(
        user.id,
        telegramId.toString(),
        userMessage,
    );

    // Check if the agent included an image marker
    const imageMatch = response.match(/\[IMAGE:(https?:\/\/[^\]]+)\]/);

    if (imageMatch) {
        const imageUrl = imageMatch[1];
        const textWithoutImage = response
            .replace(/\[IMAGE:https?:\/\/[^\]]+\]\n?/, '')
            .trim();

        await ctx.replyWithPhoto(imageUrl, {
            caption: textWithoutImage,
            parse_mode: 'Markdown',
        });
    } else {
        await ctx.reply(response, { parse_mode: 'Markdown' });
    }
});

bot.catch((err) => {
    console.error('Bot error:', err);
});

Two handlers, and the bot is complete:

/start: Creates or updates the user in the database and sends a welcome message with example queries
Text messages: Looks up the user, passes the message to the AI agent, and sends back the response. If the agent's response includes an [IMAGE:url] marker, we send it as a photo message with a caption instead of plain text

The image handling leans into how Telegram handles images. Since Telegram supports rich media but the AI only outputs text, we use a simple convention: the AI returns [IMAGE:url], and the bot code picks it up and switches to replyWithPhoto. The user sees a beautiful product image with description while the AI doesn't need to know anything about Telegram's API.

Setting up the REST API Routes

While the Telegram bot is the primary interface, we also expose REST endpoints. These are useful for admin tools, testing, or if you later want to add a web frontend.

Products Route

Create src/routes/products.ts:

import { Router } from 'express';
import { supabase } from '../database/supabase';

const router = Router();

router.get('/', async (_req, res) => {
    const { data, error } = await supabase.from('products').select('*');
    if (error) return res.status(500).json({ error: error.message });
    res.json(data);
});

router.get('/search', async (req, res) => {
    const query = (req.query.q as string) || '';
    const { data, error } = await supabase
        .from('products')
        .select('*')
        .or(
            `name.ilike.%${query}%,brand.ilike.%${query}%,category.ilike.%${query}%,notes.ilike.%${query}%,description.ilike.%${query}%`,
        );
    if (error) return res.status(500).json({ error: error.message });
    res.json(data);
});

router.get('/:id', async (req, res) => {
    const { data, error } = await supabase
        .from('products')
        .select('*')
        .eq('id', req.params.id)
        .single();
    if (error) return res.status(404).json({ error: 'Product not found' });
    res.json(data);
});

export default router;

Orders Route

Create src/routes/orders.ts:

import { Router } from 'express';
import { supabase } from '../database/supabase';

const router = Router();

router.post('/', async (req, res) => {
    const { product_id, user_id } = req.body;

    const { data: product, error: productError } = await supabase
        .from('products')
        .select('price')
        .eq('id', product_id)
        .single();

    if (productError || !product)
        return res.status(404).json({ error: 'Product not found' });

    const { data: order, error: orderError } = await supabase
        .from('orders')
        .insert({
            product_id,
            user_id,
            amount: product.price,
            status: 'pending',
        })
        .select()
        .single();

    if (orderError) return res.status(500).json({ error: orderError.message });
    res.json(order);
});

export default router;

Payments Route

Create src/routes/payments.ts:

import { Router } from 'express';
import { supabase } from '../database/supabase';
import {
    createFlwCustomer,
    createDynamicVirtualAccount,
} from '../services/flutterwave';
import crypto from 'crypto';

const router = Router();

const sanitizeName = (name: string | null) => {
    if (!name) return null;
    const clean = name.replace(/[^a-zA-Z\s,.'-]/g, '').trim();
    return clean.length >= 2 ? clean : null;
};

router.post('/', async (req, res) => {
    const { order_id } = req.body;

    const { data: order, error: orderError } = await supabase
        .from('orders')
        .select('*, users(*), products(*)')
        .eq('id', order_id)
        .single();

    if (orderError || !order)
        return res.status(404).json({ error: 'Order not found' });

    let customerId = order.users.flw_customer_id;

    if (!customerId) {
        const firstName = sanitizeName(order.users.first_name) || 'Customer';
        const lastName = sanitizeName(order.users.username) || 'User';

        const customerRes = await createFlwCustomer(
            firstName,
            lastName,
            `${order.users.telegram_id}@telegram.user`,
            crypto.randomUUID(),
        );

        if (customerRes.status !== 'success')
            return res
                .status(500)
                .json({ error: 'Failed to create Flutterwave customer' });

        customerId = customerRes.data.id;

        await supabase
            .from('users')
            .update({ flw_customer_id: customerId })
            .eq('id', order.users.id);
    }
    const reference = `ord${Date.now().toString(36)}${crypto.randomUUID().replace(/-/g, '').slice(0, 8)}`;

    const vaRes = await createDynamicVirtualAccount(
        reference,
        customerId,
        order.amount,
        'NGN',
        `Payment for ${order.products.name}`,
        3600,
        crypto.randomUUID(),
    );

    if (vaRes.status !== 'success')
        return res
            .status(500)
            .json({ error: 'Failed to create virtual account' });

    const va = vaRes.data;
    await supabase
        .from('orders')
        .update({
            flw_reference: reference,
            virtual_account_number: va.account_number,
            virtual_account_bank: va.account_bank_name,
            virtual_account_expiry: va.account_expiration_datetime,
        })
        .eq('id', order_id);

    res.json({
        account_number: va.account_number,
        bank_name: va.account_bank_name,
        amount: order.amount,
        reference,
        expires_at: va.account_expiration_datetime,
    });
});

export default router;

Handling Payment Webhooks

This is the final critical piece. When a customer transfers money to the virtual account, Flutterwave sends a webhook to our server. We need to verify the payment, update the order, and notify the customer.

Create src/routes/webhooks.ts:

import { Router, Request, Response } from 'express';
import { supabase } from '../database/supabase';
import { verifyCharge } from '../services/flutterwave';
import { bot } from '../bot';
import crypto from 'crypto';

const router = Router();

router.post('/flutterwave', async (req: Request, res: Response) => {
    const secretHash = process.env.FLW_WEBHOOK_SECRET_HASH;
    const signature = req.headers['flutterwave-signature'] as string;

    // Step 1: Verify the webhook signature
    if (secretHash) {
        if (!signature) {
            return res.status(401).json({ error: 'Missing signature' });
        }

        const payloadBuffer = (req as any).rawBody || '';
        const expectedHash = crypto
            .createHmac('sha256', secretHash)
            .update(payloadBuffer)
            .digest('base64');

        if (signature !== expectedHash) {
            return res.status(401).json({ error: 'Invalid signature' });
        }
    }

    const payload = req.body;

    // Step 2: Only process successful completed charges
    if (
        (payload?.event !== 'charge.completed' &&
            payload?.type !== 'charge.completed') ||
        payload?.data?.status !== 'succeeded'
    ) {
        return res.status(200).json({ status: 'ok' });
    }

    const { reference, id: chargeId } = payload.data;

    // Step 3: Verify the charge with Flutterwave's API (don't trust the webhook alone)
    try {
        const verification = await verifyCharge(chargeId);
        if (verification.data.status !== 'succeeded') {
            return res
                .status(400)
                .json({ error: 'Charge verification failed' });
        }
    } catch (err) {
        console.error('[WEBHOOK] Charge verification API error:', err);
    }

    // Step 4: Find the order and mark it as paid
    const { data: order, error: orderError } = await supabase
        .from('orders')
        .update({ status: 'paid' })
        .eq('flw_reference', reference)
        .select('*, users(*), products(*)')
        .single();

    if (orderError || !order) {
        console.error('[WEBHOOK] Order lookup failed:', orderError?.message);
        return res.status(200).json({ status: 'ok' });
    }

    // Step 5: Send confirmation to the customer on Telegram
    const amount = Number(order.amount).toLocaleString();
    const message =
        `*Payment received!*\n\n` +
        `Your order for *${order.products.name}* has been confirmed.\n` +
        `Order ID: \`${order.id}\`\n` +
        `Amount: ${amount}`;

    await bot.api.sendMessage(order.users.telegram_id, message, {
        parse_mode: 'Markdown',
    });

    return res.status(200).json({ status: 'ok' });
});

export default router;

A few important security practices here:

Signature Verification: We verify the webhook's HMAC signature against our secret hash. This ensures the webhook actually came from Flutterwave and wasn't spoofed.
Charge Verification: Even after verifying the signature, we make an API call to Flutterwave to confirm the charge status.

Notice how we capture the raw request body in the Express middleware (see the server setup below). This is needed because JSON parsing alters the body, and we need the original bytes for HMAC verification.

Wiring it all Together

Finally, create src/server.ts:

import 'dotenv/config';
import express from 'express';
import cors from 'cors';
import { bot } from './bot';
import productsRouter from './routes/products';
import ordersRouter from './routes/orders';
import paymentsRouter from './routes/payments';
import webhooksRouter from './routes/webhooks';

const app = express();
const PORT = process.env.PORT || 3000;

app.use(cors());
app.use(
    express.json({
        verify: (req: any, _res, buf) => {
            req.rawBody = buf.toString();
        },
    }),
);

app.use('/api/products', productsRouter);
app.use('/api/orders', ordersRouter);
app.use('/api/payments', paymentsRouter);
app.use('/webhooks', webhooksRouter);

app.get('/health', (_req, res) => {
    res.json({ status: 'ok' });
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
    bot.start();
    console.log('Telegram bot started (long polling)');
});

The verify callback in express.json() captures the raw request body before it gets parsed. This is important for webhook signature verification because you need the exact bytes that were sent, not a re-serialized version of the JSON.

Running the Project

Start the development server:

npm run dev

You should see:

Server running on port 3000
Telegram bot started (long polling)

Now open Telegram, find your bot, and send /start. Try asking it about perfumes, request details on a specific one, and go through the purchase flow. The AI will guide the conversation naturally while the tools handle the actual business logic behind the scenes.

Setting Up the Webhook for Production

For Flutterwave to notify you about payments, it needs to reach your webhook endpoint. During development, you can use a tool like ngrok to expose your local server:

ngrok http 3000

Then update the Flutterwave dashboard with the webhook URL ngrok returned and a secret hash of your choice:

https://your-ngrok-url.ngrok.io/webhooks/flutterwave

For production, deploy your server to a cloud provider and use the public URL.

What Makes this Approach Powerful

Looking back at what we built, a few things stand out:

Flutterwave’s virtual accounts are a game changer for chat commerce. The traditional payment flow, redirect to checkout, pay, then redirect back, breaks the conversation. Virtual accounts keep the customer right where they are. They receive an account number, open their banking app, transfer the money, and get a confirmation without leaving the chat.
The AI agent pattern is incredibly flexible. Want to add order tracking? Define a new tool. Want to handle returns? Add another one. Since the agent understands natural language, there is no need for complex command parsing or button-heavy menus. Customers just type what they want, and the agent figures out the next step.
The entire project comes in at around 400 lines of TypeScript. There is no frontend framework, no CSS, no state management library, and no client-side build pipeline. The messaging platform handles the interface, so you can focus purely on business logic.

Conclusion

Chat commerce is not just a trend. It is a different way to think about digital transactions. By combining an AI agent like OpenAI, a messaging platform like Telegram, and a flexible payment provider like Flutterwave, you can build an online store that feels more like a conversation than a website.

What makes this approach stand out is its simplicity. You focus on what matters, your products, your payment flow, and what happens after a purchase. The AI handles the conversation, the messaging platform handles the interface, and Flutterwave handles the payments.

If you are building for markets where mobile money and bank transfers are common, this pattern fits naturally. Flutterwave’s dynamic virtual accounts plug directly into the conversational flow, and webhook-based confirmations give customers instant feedback without the need to refresh or poll.

The full source code for this project is available on GitHub. Feel free to fork it, swap out the perfumes for your own products, and build your own chat commerce experience.

5 Step Guide To Keep Your Checkout Running During Peak Sales Periods

Demola Malomo — Fri, 20 Mar 2026 08:30:25 +0000

Two things can happen during big sales events. Your checkout either becomes your strongest revenue driver or your biggest risk. Think about Cyber Monday, Black Friday, Christmas sales, flash sales, or that viral campaign you and your team worked hard on. All of these bring thousands of users to your site within minutes.

A traffic surge sounds like a great problem to have, but anyone who has managed a fast-growing business knows the truth. Sudden surges create queues, APIs slow down, and then payment failures start to appear. These issues expose gaps in your system and can hurt both your revenue and your reputation.

Your checkout is the final step in the customer journey, so every second matters. When it slows or breaks, the financial impact is instant. The good news is that you can prepare ahead of time. With the right setup, your system stays stable and your customers stay happy even when traffic shoots through the roof.

Here is how you can get your checkout infrastructure ready for high traffic days with confidence.

Step 1: Pick the Right Checkout Mode for High Traffic Days

Not all checkout experiences are built the same, and the mode you choose has a direct impact on how your system behaves under pressure.

Think of checkout modes like grocery store lines. A redirect checkout is like being told to leave your checkout lane, walk across the store to pay at a separate counter, then return to finish your purchase. Every extra step slows the process and increases the chance that someone will abandon their cart. When the store gets busy, these detours turn into major delays.

An inline or embedded checkout keeps customers on your site from start to finish. It is faster, reduces friction, and gives you more control over the payment experience.

For high-traffic events like Black Friday or large promotional campaigns, use an inline or embedded checkout. A redirect checkout is better suited for smaller, controlled environments where traffic is predictable and you want to guide customers through a very specific flow that does not depend on high performance.

How Flutterwave Can Help

Flutterwave offers multiple checkout options tailored for different traffic scenarios:

Standard Checkout: A redirect option suitable for regular traffic days
Inline Checkout: Embeds the payment form directly on your page, keeping customers in your environment
HTML Checkout: Works similarly to Inline Checkout but built with simple HTML
Flutterwave Standard API: Gives you full control to build a custom checkout flow that fits your unique traffic patterns

Step 2: Enable Fast Rails and Wallets

During busy periods, every extra second at checkout increases the chance of abandonment. Traditional bank transfers that involve tellers and older card processing flows can slow down when hundreds of customers try to pay at the same time.

Fast payment rails keep transactions moving in real time. For example:

Instant bank transfers and mobile money process payments without long authentication steps that usually slow down traditional methods.
Digital wallets like Apple Pay, Google Pay, and local mobile money apps offer one-tap checkout experiences that handle high volumes without creating delays.
Tokenized cards speed things up because customers do not need to enter their card details again.

How Flutterwave Can Help

Flutterwave gives you access to multiple payment rails across Africa, so you can offer faster and more flexible ways for customers to pay:

Mobile money services (M-Pesa, MTN Mobile Money, Airtel Money, etc.) let customers pay instantly with their phones, which is familiar, convenient, and widely used across the continent.
Bank transfers (including instant transfers) allow customers to pay directly from their bank accounts without extra steps or redirects.
USSD payments give feature phone users a simple and reliable way to pay by dialing a short code, with no internet required.
Card payments support both local and international cards, giving customers the freedom to pay however they prefer.
Tokenization helps returning customers check out faster by securely storing their card details for future payments.

Step 3: Pre-Flight Your Checkout Settings

One of the most important steps you need to take before a big traffic day is a checkout health check. This is similar to doing a systems check before a flight takes off. You do not want the first payment attempt of the day to reveal a hidden configuration issue.

To make sure everything is ready, work through these checks:

Stress-test your checkout flow.
Create multiple test accounts.
Run simultaneous transactions to simulate heavy traffic.
Monitor your payment limits closely.
Ensure customers do not hit unexpected transaction caps when checking out.

You should also review your webhook configurations. Webhooks notify your system when payments are completed. If they are not prepared to handle concurrent requests, you may run into processing delays or missed notifications.

How Flutterwave Can Help

Flutterwave provides several tools to help you pre-flight your setup:

Test Mode Environment: Use load testing tools like JMeter or k6 to run unlimited test transactions without touching real funds. Flutterwave lets you switch between test and production environments directly from your dashboard.
Transaction Limit Configuration: Flutterwave allows you to increase or operate within the transaction limit for each currency. If you expect customers to exceed the default limit for a payment method, such as cards, reach out to the support team to raise it.
Webhooks: Use the Flutterwave dashboard to configure your webhook securely so you know each notification is coming from a trusted source. Simulate different scenarios such as successful payments, delays, and failures so your system responds in a stable and predictable way.

Step 4: Make Requests Idempotent

High-traffic moments often come with more retries than usual. A customer might refresh the page, double-click a button, or experience a short network disruption. Situations like these can cause your system to treat each retry as a brand new payment attempt if idempotency is not in place.

Idempotency is a safeguard that lets you retry or duplicate a request without creating multiple transactions. It works by attaching a unique identifier to each transaction attempt. If the same identifier appears more than once, the system knows it is the same request and avoids processing it again.

How Flutterwave Can Help

Flutterwave supports idempotency through the tx_ref (transaction reference) parameter. Every payment request you send should include a unique tx_ref value:

{
  "tx_ref": "ORDER_20241120_123456",
  "amount": "5000",
  "currency": "NGN",
  "customer": {...}
}

When you include a tx_ref, Flutterwave uses it to detect duplicate requests. If a customer retries a payment with the same reference, Flutterwave recognizes it as the same transaction and will not charge them twice.

Step 5: Prepare Your Backend to Handle Payment Volume

Before customers reach your checkout, they will visit your landing page, browse catalogues, and explore product pages. Each of these actions triggers callbacks, events, and database operations, and your backend needs to handle all of them smoothly. You do not want users stuck before checkout because a product page is taking too long to load.

Your backend preparation may include actions like these:

Caching frequently used data
Using queues for heavy background jobs
Auto-scaling your servers
Reducing synchronous operations during checkout
Confirming that your webhook endpoint can respond within seconds

How Flutterwave Can Help

While your backend infrastructure is primarily your responsibility, Flutterwave provides features that reduce the load on your systems:

Webhook Retry Logic: If your endpoint becomes overloaded, Flutterwave automatically retries webhook deliveries with exponential backoff. This gives your system room to recover.
Dashboard Verification: During peak periods, you can verify payment status directly from the Flutterwave dashboard, which provides a fallback if webhook delivery is delayed.
Transaction Verification API: Flutterwave offers an API that lets you programmatically verify transactions at any time.

Wrap Up

Traffic spikes can be stressful, but they do not have to disrupt your checkout. With the right preparation, peak traffic becomes peak revenue. Every step you take now reduces payment failures, protects your brand, and gives your customers the smooth experience they want.

Flutterwave provides the tools, rails, and infrastructure that help your checkout stay stable when interest rises faster than expected. Combine these recommendations with proper testing and you will be ready for any major sales moment, product drop, or viral campaign.

If your system stays steady when others struggle, you win big on the days that matter most. Ready to start building payment experiences that scale with demand? Create an account now.

What Are Payment Rails? A Guide for Developers

Demola Malomo — Fri, 13 Mar 2026 08:59:05 +0000

As a developer building payment systems, one of the most frustrating experiences is not knowing what “success” actually means. A transfer request goes through, the API responds fine, and your webhook fires. But the status says pending. Has the money moved or not? Should you show success to the user, retry the transaction, or wait? In payments, a successful API call does not always mean a successful transfer. That gap is where a lot of confusion begins.

The confusion grows once you realize there is no single way money moves. Card payments, bank transfers, mobile money, instant payments, stablecoins, and cross-border settlements all run on different rails. Each rail has its own protocol, status lifecycle, settlement timing, and failure modes. What looks like a delay on one rail may be normal processing on another. Without understanding which rail you are on, it becomes easy to misread statuses, handle retries incorrectly, or give users the wrong feedback.

This article breaks down what payment rails actually are, why they behave so differently, and how to handle those differences in your system.

What Are Payment Rails?

Payment rails are infrastructure networks that move money from one financial institution to another. They are like the highways that money travels on. Just like highways have speed limits, traffic rules, toll booths, lane restrictions, and occasional road closures, payment rails also operate with different processing speeds, access requirements, fees, and operating windows.

Technically, a payment rail defines:

How a payment instruction is transmitted through a payment message protocol
Which participants are allowed to send and receive messages
How financial transactions are validated
How clearing happens
How and when settlement occurs

Key Components of Payment Rails

The following are the core components that make up a payment rail when moving money from one point to another:

Networks and Protocols: These are the underlying technologies that dictate the rules allowing banks and financial institutions to communicate with each other. It could be a traditional system like Society of Worldwide Interbank Financial Telecommunication (SWIFT) for international transfers, or a modern blockchain used for stablecoin settlement. The network largely determines the speed, cost, and geographical reach of the payment.
Centralized or Decentralized Ledger: Every payment rail needs a source of truth that records who sent money, who received it, and whether intermediaries were involved before it reached its destination. This ledger can be:
- Centralized: A traditional bank or central bank maintains the records.
- Decentralized: A distributed ledger where multiple nodes validate and record transactions. This is common in crypto and some fintech systems.
Clearing and Settlement: Clearing is the process of verifying that funds exist and confirming obligations between financial institutions before settlement. Settlement is the actual transfer of funds that fulfills those obligations, typically using central bank money. Some rails clear and settle in real time, while others batch transactions and settle hours or even days later.
Participant Authorization: Not everyone can connect directly to a payment rail. Access usually requires a banking license, contractual agreements, and technical certification. Most developers interact with rails through licensed intermediaries such as payment gateways, processors, banking-as-a-service providers, or platforms that have already integrated with the rail.

All of these components come into play whenever you call a payment API. You are not interacting directly with the rail itself. Instead, you are communicating with a platform or processor that connects to the rail on your behalf. The platform translates your API request into the rail’s native protocol, submits it to the network, and then converts the rail’s response into webhook events that your system can understand and act on.

Payment Rails vs. Payment Platforms

As you build, understanding this distinction plays an important role in your business strategy, target audience, and how you design your system.

Payment rails like ACH, Visa, Mastercard, SEPA, and FedNow are the actual networks that move funds between banks. They define how transactions are formatted, routed, cleared, and settled.
Payment platforms like Flutterwave, Stripe, and PayPal are payment service providers that sit above the rails. They provide APIs, handle authentication, abstract rail differences, route transactions to the appropriate network, and translate rail events into developer-friendly webhooks.

Aspect	Payment Rails	Payment Platforms
Core role	The underlying networks that move money between financial institutions	The software layer that developers integrate with to access and manage one or more rails
Primary focus	Actual movement of funds and financial processing	Orchestration, abstraction, and developer experience
What they control	Authorization rules, clearing logic, and settlement	APIs, routing logic, and system coordination
Technical responsibility	Interbank communication and financial message exchange	API authentication, request handling, and system integration
Transaction lifecycle	Determines when and how funds are cleared and settled	Tracks, standardizes, and reports transaction status
Error handling	Returns, reversals, and network-level exceptions	Input validation, retries, and webhook notifications
Status model	Rail-specific and often inconsistent across networks	Unified status models across multiple rails
Routing	Typically fixed to a specific network (e.g., card network, ACH, RTP)	Can route transactions across multiple rails dynamically
Who uses it directly	Banks, financial institutions, and network operators	Developers, businesses, and fintech products

Now that we understand what payment rails are and their key components, the next question is what happens when money actually moves through them.

When a payment is initiated, systems start communicating, balances change, and settlement processes begin. Each rail follows its own rules and timelines, which is why payments behave differently depending on the network behind them.

Let’s break down how money travels across payment networks, from initiation to final settlement. Then we will look at some of the major rails in use today and how they compare.

How Money Moves on Rails

When money moves, it is not a single action but a pipeline with distinct stages, each with its own latency and failure modes. Understanding this pipeline helps you build systems that can properly handle payment processing network overhead. The payment process involves several key steps, including initiation, routing, settlement, and reconciliation.

Initiation vs. Authorization

Initiation happens when your system submits a payment instruction. It involves sending an API request with the amount, currency, sender, and recipient details. The platform validates the request, then either processes it immediately or queues it if the rail runs on schedules, batch cycles, or requires manual or compliance checks.

After initiation comes authorization. This is when the rail verifies that the sender has funds and permission to send them.

For example, in a card payment, the card network checks the cardholder’s available balance and either approves or declines in real time. For many bank transfers, authorization is implicit. The rail accepts the instruction and queues it for processing.

Authorization means “we will attempt to process this,” not “the money has moved.”

That is why a 200 OK response means “we received your request,” not “the funds have settled.” The platform confirmed that the rail accepted your instruction. Settlement happens later.
Messaging and Routing

Once authorized, the payment instruction becomes a structured message. Different rails use different message formats, for example:
- ISO 20022: Standard for modern bank transfers and instant payments
- Card network protocols: Proprietary formats used by Visa, Mastercard, etc.
- NACHA format: US ACH-specific fixed-width file format The rail’s network operator routes this message to the recipient’s financial institution. Routing involves lookups based on account identifiers such as routing numbers, IBANs, or card numbers. Cross-border payments may also involve intermediary banks.
As a developer, you do not see this routing directly. What you see are its effects, such as processing time, network fees, and possible delivery failures.
Clearing and Settlement Models

Clearing is the process of calculating who owes whom. Rails typically do this in one of two ways:
- Real-Time Clearing: This is when each transaction is processed individually as it arrives, through a pre-funded account or a real-time gross settlement system. Rails like FedNow and RTP use real-time clearing, so beneficiaries can receive funds within seconds.
- Batch Clearing: This is done by accumulating transactions over a window (often a day), then getting processed together. The rail nets out all the transfers between institutions and settles the net amounts. Even though your API call succeeds in a few seconds, the transaction doesn't clear until the evening batch runs. ACH and SEPA work this way.
Settlement is the actual movement of funds between financial institutions. Even after clearing, settlement can still be delayed. For example, a merchant might see a transaction approved immediately, but the actual transfer between banks may occur later in scheduled settlement cycles.
Reconciliation and Ledger Updates

Even after the settlement completes, you still need to reconcile the rail’s final status with your internal ledger. Your ledger should track:
- When the obligation is recorded (for example, when the API call succeeds)
- When the actual value transfer happens (settlement confirmation)
These rarely occur at the same time.

Rails communicate finality through different mechanisms:
- Immediate responses from real-time systems
- Batch settlement files
- Webhook events from your payment platform that translate rail messages If you work directly with a rail, ledger updates should occur only when settlement is confirmed, not when the API initially returns success.

While the steps above describe how money moves through a rail, one more concept matters just as much: who initiates the movement. This affects authorization flows, reversal behavior, settlement risk, and the overall user experience.

Some rails move funds because the sender pushes money out. Others move funds because the receiver pulls money in with prior authorization. This difference shapes how payments behave and how you design your flows.

Push vs. Pull Rails

Payment rails fall into push (credit) or pull (debit) categories. Push rails send money from the payer to the recipient. The payer’s financial institution actively transfers the funds. This is common for payouts, transfers, and refunds, where you control the outflow.

Pull rails allow the recipient to debit the payer’s account with prior permission. This is common in subscriptions, recurring billing, and e-commerce purchases.

In practice:

Push rails offer strong control but can be difficult to reverse once processed.
Pull rails are convenient for recurring payments but carry risks such as insufficient funds or chargebacks.

From a system design perspective, this affects how authorization works. Push flows often require account validation or prefunding. Pull flows typically involve credential storage, mandates, or tokenized payment authorization.

Types of Payment Rails

Payment rails come in different forms, each suited to specific use cases, settlement speeds, and risk models. Below are some of the most widely used payment rails around the world.

Automated Clearing House (ACH)

ACH is the dominant bank transfer rail in the United States. It processes both debits and credits between US bank accounts.

ACH transactions typically settle in one to two business days, or the same day when submitted before cutoff times, usually around 10:30 a.m., 2:45 p.m., and 4:45 p.m. ET. Costs generally range from $0.20 to $0.50 per transaction.
This makes ACH well-suited for:

Payroll
Bill payments
Business-to-business transfers
Recurring subscriptions

A major drawback is that unauthorized debits can be disputed long after the transaction. In many cases, reversals can take up to 60 days.

Single Euro Payment Area (SEPA)

SEPA is the European equivalent of ACH. It enables euro transfers between bank accounts across participating European countries.

Standard SEPA credit transfers typically settle within one business day.
SEPA Instant Credit Transfer settles in under 10 seconds.

Transfers are often free for consumers, while businesses usually pay per transaction.

Common failure scenarios include invalid IBAN details or the receiving bank not supporting the specific SEPA scheme. Once settled, reversals can be difficult.

Unified Payment Interface (UPI)

UPI is a real-time payment rail that links bank accounts through mobile apps, primarily in India. Transactions settle instantly and are typically free for consumers and many business use cases.
UPI is widely used for:

Peer-to-peer transfers
Merchant payments
Bill splitting

Failures usually occur when there are insufficient funds or invalid recipient account details.

Card Networks: Visa and Mastercard
Card networks connect issuing banks (which provide cards to consumers) with acquiring banks, which service merchants. This allows card-based transactions to occur globally.

Authorization typically happens within one to three seconds.
Settlement usually takes one to three business days.
Fees often range between 1.5 percent and 3 percent per transaction.

Cards are commonly used for:

E-commerce
Point-of-sale purchases
Recurring billing

Failures typically occur during authorization, such as insufficient funds, blocked debit card payments, or fraud detection.

Real-Time Rails: FedNow, Real-Time Payments (RTP), and SEPA Instant Credit Transfer

These systems settle transactions within seconds. Fees are generally higher than ACH but lower than card processing.
They are commonly used for:

Instant refunds
Person-to-person transfers
Economy payouts

Failures happen immediately if the recipient bank is unreachable or the account details are invalid.

Wire Transfers and SWIFT

Domestic wire systems like Fedwire support high value, same-day transfers between banks. They are expensive, often costing $15 to $30 per transaction, but they are fast and typically irrevocable once settled.

Failures usually occur due to incorrect account details. Once completed, reversals typically require the recipient’s consent.

SWIFT is not technically a payment rail but a messaging network. Banks use SWIFT to send payment instructions, then settle funds through correspondent banking relationships.

SWIFT transfers typically take one to five business days, depending on the currency corridor and number of intermediary banks. Costs are often between $15 and $30 per transfer.

Common use cases include:

International business payments
Foreign currency transfers
Large transactions such as real estate purchases
Time-sensitive global payments

Blockchain Rail

Blockchain payment rails use stablecoins such as USDC and USDT to transfer value digitally. These operate differently from traditional rails because they do not have built-in consumer protection mechanisms like chargebacks or ACH returns.

Settlement usually happens within seconds to minutes, depending on the blockchain network. Costs are typically limited to network transaction fees.

Transactions are irreversible once confirmed on-chain. Sending funds to the wrong address can result in permanent loss, and custody failures may be unrecoverable.

Despite this trade-off, blockchain rails are becoming increasingly popular for cross-border payments. They are widely used in fintech, crypto-native applications, and regions with volatile local currencies.

If you want to stay ahead of the curve and see how fintech companies are building with stablecoins, you can subscribe to the Flutterwave newsletter.

Understanding payment rails conceptually is useful, but real integrations happen through API calls, webhooks, and state transitions.

In the next section, we will look at how rails behave in real systems. You will see how transactions are initiated, when results actually become final, and how to design your integration around asynchronous settlement.

How Payment Rails Work in APIs (Developer Integration Guide)

Understanding payment rails conceptually is important. But when you build real systems, you do not interact with rails directly. You interact with APIs, events, and state changes that reflect what is happening underneath.

To build reliable payment flows, you need to understand how rail behavior maps to API behavior.

Initiating a Transaction

When you call a payment API, you are submitting a payment instruction. How the API behaves depends on whether the rail supports synchronous or asynchronous processing.

A synchronous rail, such as card payments or real-time systems, gives you an immediate answer during the API call.

const response = await paymentClient.charge({
  amount: 5000,
  currency: 'USD',
  payment_method: 'card',
  source: cardToken
});

// response.status might be 'success' or 'failed'
// This reflects the rail's auth decision

With card payments, the API waits for authorization from the network before responding. If status is success, the network approved the charge and will settle it later.

However, with asynchronous rails like bank transfers, the instruction is queued for later processing. The same API request usually returns pending or processing.

const response = await paymentClient.createTransfer({
  amount: 10000,
  currency: 'USD',
  destination: bankAccount,
  rail: 'ach'
});

// response.status is likely 'pending' or 'processing'
// The rail hasn't processed this yet

You don't know the final outcome until the rail finishes processing and sends an event back. A successful API response means that the request was accepted, not that funds have settled. The platform validated your input and submitted it to the rail. Settlement happens later and depends on the rail’s timeline.

Webhooks and Event Callbacks

Because most rails settle asynchronously, your system learns the final outcome through webhooks. The payment platform listens for updates from the rail and forwards them to your endpoint.

Your system must be prepared to:

Update internal transaction state based on event type
Trigger business actions only after final settlement
Handle duplicate webhook deliveries safely
Store event history for audit and reconciliation
Maintain idempotency when updating records
Retry processing if your system fails mid-handling
Alert operations teams for failed or disputed payments

In practice, this means your codebase should treat webhooks as the source of truth for final outcomes, not API responses.

app.post('/webhooks/payment-events', (req, res) => {
  const event = req.body;

  // Verify webhook signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }

  // Handle different event types
  switch (event.type) {
    case 'transfer.succeeded':
      // Rail confirmed settlement
      updateLedger(event.data.id, 'settled');
      notifyUser(event.data.recipient, 'Payment received');
      break;

    case 'transfer.failed':
      // Rail rejected or returned the transfer
      updateLedger(event.data.id, 'failed');
      logFailure(event.data.failure_code, event.data.failure_message);
      break;

    case 'charge.dispute.created':
      // Cardholder initiated a chargeback
      freezeFunds(event.data.id, event.data.amount);
      alertFraudTeam(event.data);
      break;
  }

  res.status(200).send('Received');
});

Your ledger should reflect settled only when the settlement webhook arrives, not when the API call succeeds. Also, delivery timing varies by rail, and it may take seconds for real-time systems or one to two days for batch rails.

Reconciliation Triggers

Rails communicate settlement in different ways. Relying only on webhooks creates gaps. A robust system also:

Polls for status updates to detect transactions stuck in pending states
Parses settlement files provided by banks for batch rails
Compares bank statements against internal ledger balances

Reconciliation is what confirms that recorded transactions match actual money movement.

Multi-Rail Routing Logic

If your platform supports multiple rails, you need logic to select the right one based on context. Routing decisions should consider cost, speed, reliability, and user preference.

Some users may want instant delivery regardless of cost. Others prefer cheaper transfers even if they take several days. Giving users this flexibility builds trust and transparency.

Your routing logic can look like this:

function selectRail(payment) {
  const { amount, urgency, destination, currency } = payment;

  // High-value urgent payments → wire
  if (amount > 100000 && urgency === 'same_day') {
    return 'wire';
  }

  // Low-value instant → real-time rail if available
  if (urgency === 'instant' && destination.supportsRTP) {
    return 'rtp';
  }

  // Cross-border → SWIFT
  if (currency !== 'USD' || destination.country !== 'US') {
    return 'swift';
  }

  // Default to ACH for cost efficiency
  return 'ach';
}

Use the table below to guide your decision on rail selection:

Rail	Speed	Cost (typical)	Reliability	Best For
ACH Standard	1-2 days	$0.20-0.50	High (batch reliability)	Payroll, recurring bills
ACH Same Day	Hours	$0.50-1.50	High	Same-day obligations
RTP/FedNow	Seconds	$0.50-2.00	Very High (real-time confirmation)	Emergency disbursements, just-in-time payments
Cards	200ms auth	1.5-3.5% + $0.10	High (fraud risk)	Consumer purchases, high trust
Wires	Minutes	$15-50	Very High	High-value, time-critical
SWIFT	1-5 days	$20-100	Medium (correspondent risk)	International, no local rail
Stablecoins	Seconds-minutes	$0.01-5.00 (variable)	Medium (blockchain risk)	Crypto-native, cross-border

To make this decision, you need to consider speed, cost, reliability, and reversibility of the rail. A strong user experience presents available rails, their timelines, costs, and risks clearly before the transaction starts.

This transparency benefits everyone.
For you, as the builder:

Fewer support disputes
Clearer liability boundaries
Better user trust
More predictable operations
Easier reconciliation and risk management

For users:

Informed decision making
Realistic expectations
Better control over cost vs. speed
Reduced confusion about delays or reversals

Ultimately, clear communication reduces friction across the entire payment lifecycle.

Retry and Error Logic

Rails fail in different ways. Your error handling system must account for both temporary and permanent failures.

A common error is a transient failure caused by network instability or rate limits. These should be retried using exponential backoff.

async function submitWithRetry(paymentRequest, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await paymentClient.createTransfer(paymentRequest);
    } catch (error) {
      if (error.type === 'network_error' && attempt < maxRetries) {
        await sleep(Math.pow(2, attempt) * 1000); // define sleep function
        continue;
      }
      throw error;
    }
  }
}

In some cases, the failure is permanent. This occurs when an invalid account is used, or the sending account doesn’t have sufficient funds. In such cases, don’t retry the transaction, but instead log it and alert the customer.

if (error.code === 'invalid_account_number') {
  await db.markTransferFailed(transferId, error.code);
  await notifyUser(userId, 'Invalid bank account');
  // Do not retry
}

Also, some failures can happen because of a timeout during submission. Before retrying, always check the transaction status to avoid duplicate submissions.

if (error.type === 'timeout') {
  // Check if the transfer was created before retrying
  const existing = await paymentClient.listTransfers({
    idempotency_key: paymentRequest.idempotency_key
  });

  if (existing.length > 0) {
    return existing[0]; // Already submitted
  }

  // Safe to retry
  return await paymentClient.createTransfer(paymentRequest);
}

Conclusion

Payment rails are the infrastructure networks that move money between financial institutions. They sit beneath payment platforms and define how fast, how reliably, and at what cost transactions settle.

Rails differ fundamentally in speed, cost, and settlement models. Understanding those differences helps you design systems that handle asynchronous settlement, reconcile ledgers correctly, and route transactions intelligently.

As a developer, you must map API interactions to how money actually moves. A 200 OK response does not mean money moved. It means the rail accepted your instruction. Settlement happens later, and your system learns the outcome through webhooks, status polling, and reconciliation.

Testing real rail behavior is not trivial. Experiments can be expensive, and you cannot use customer funds casually. Platforms like Flutterwave give you access to these rails through a single integration, while still exposing the signals you need to build efficient, resilient systems.

What PAPSS Means for Developers Building Cross-Border Payments in Africa

Demola Malomo — Fri, 27 Feb 2026 08:27:11 +0000

You’d think sending money from one African country to another would be straightforward, but it often takes a strange route. The funds move from a local bank to a correspondent bank, then offshore to clear in dollars (USD) or other foreign currencies, and only then find their way back into the destination African country. This is how most cross-border payments in Africa currently work.

The Pan-African Payment and Settlement System (PAPSS) steps in to change part of this journey for payments within the continent. While there is still room for improvement, it makes regional settlement smarter and more direct.

For developers working in fintech and building payment platforms across Africa, the key is understanding what PAPSS changes in practice. Specifically, where it sits in the payment stack and when other rails are the better choice.

In this guide, we will break down what PAPSS changes, what it leaves untouched, and how developers should think about it when designing systems for African cross-border payments.

Before diving in, let’s take a closer look at how cross-border transactions work in Africa.

How Cross-Border Payments in Africa Work

Payments across African borders are rarely a single, straightforward process. They rely on the correspondent banking model. This means that when a business in Lagos sends money to a supplier in Nairobi, the payment leaves Nigeria’s domestic rail, moves to a Nigerian correspondent bank, gets converted to USD or EUR, settles through an offshore clearing system, converts again to KES, passes through a Kenyan correspondent bank, and finally reaches the supplier’s account through Kenya’s domestic rail. These are examples of the cross-border transactions and cross-border trade that PAPSS aims to simplify.

This setup works, but it comes with overhead. Developers building on this framework deal with unpredictable timelines, complicated fees, and integration headaches from stitching together multiple APIs or legacy interfaces.

Why Funds Leave the Continent

The root issue is currency convertibility and trust. Most African currencies do not have a direct clearing relationship with each other or a shared settlement layer. Without this, banks rely on major currencies like USD or EUR as intermediaries. Most of these clearing systems sit offshore, which is why cross-border payments follow this route. This reliance on foreign currencies increases costs and complexity for African businesses and financial institutions.

This workflow is not inefficient by accident. It exists as a workaround for limited currency convertibility and the historical dominance of correspondent banking networks built around global reserve currencies. It is also simpler and less risky for banks to centralize foreign exchange and settlement through intermediaries that already handle USD and EUR clearing at scale.

Why Settlement Takes Days

Settlement delays stem from the need to move funds through multiple intermediaries operating in different time zones and regulatory environments. A payment sent from Kenya may be batched by the bank or payment service provider in the morning, since most banks wait until a threshold amount is reached. It might not clear through London until later in the day, then move onward to Ghana. The beneficiary may not see the funds until the next business day, or later if compliance checks fail.

The actual data transmission takes minutes or hours. The real delay comes from operational processes such as batching, validation checks, compliance reviews, and handoffs between intermediaries. Reconciliation issues and resolving discrepancies between what was sent and what was received can extend timelines even further.

Where Costs and Failures Occur

A typical correspondent banking flow introduces costs at every stage. The originating bank charges an outgoing wire fee, the correspondent bank charges a processing fee, and the receiving bank charges an incoming wire fee. In addition to that, banks apply an FX spread that varies by corridor, liquidity, and counterparty risk. This spread covers liquidity and minimizes risk costs. While this makes sense from the bank’s perspective, these charges compound quickly for customers.

Failures can also happen at multiple points. Insufficient correspondent account balances, compliance holds, rejected SWIFT messages, and FX rate disputes are common. Each of these usually requires manual intervention and can add days to resolution.

The end result is that intra-African payments often cost more than comparable transfers in other regions, and they take days instead of minutes.

What is PAPSS?

PAPSS is a regional clearing and settlement layer operated with participation from African central banks. It sits between domestic payment systems and handles cross-border settlement in local currencies. Operated by Afreximbank in partnership with the African Union and the African Continental Free Trade Area (AfCFTA), it connects sender and beneficiary central banks and financial institutions across participating countries. As of early 2026, it covers over 18 countries, including Morocco, Algeria, Nigeria, and Ghana, with over 150 commercial banks and 14 switches integrated.

At its core, PAPSS enables settlement for intra-African payments in local currencies without routing everything through foreign intermediaries. It acts as a bridge between the sending and receiving institutions by validating payment instructions, handling netting, and settling net positions among the involved central banks. One way to think about it is as a continental middleware layer. A local bank sends a payment in Naira, PAPSS processes it, and the recipient receives Cedis instantly or near-instantly, all without requiring USD as an intermediary settlement currency.

PAPSS doesn’t replace national rails like Nigeria's NIBSS or Kenya’s PESALINK. Instead, it creates new opportunities by providing an alternative settlement path for intra-African payments that supports local currency clearing.

How PAPSS Changes the Settlement Process

The biggest change PAPSS introduces is where and how settlement happens. Local currency settlement now takes place within Africa. Instead of converting to USD or EUR, sending funds offshore, and converting again on arrival, payments can be cleared and settled regionally without requiring an intermediary reserve currency.

This shift changes several practical aspects of how cross-border payments behave under the hood. It affects how currencies are handled, how liquidity is managed, and how much reliance there is on offshore intermediaries. In practice, this shows up in three key ways:

Local Currency Clearing: Participating institutions can clear obligations in local currencies through the regional transfer system without needing a foreign intermediary. This reduces FX steps for eligible corridors and simplifies treasury operations.
Net Settlement Across Participants: Instead of settling every transaction individually, PAPSS supports multilateral net settlement among participating institutions. This lowers liquidity pressure and reduces the amount of prefunding required.
Reduced Offshore Dependencies: By keeping settlement regional, PAPSS reduces reliance on offshore correspondent banks for intra-African payments. It doesn’t remove correspondent banking entirely, but it changes when and where it’s needed.

PAPSS also aims to support increased African trade under the AfCFTA by streamlining these processes.

While PAPSS brings these advantages, it also raises a common question. What is the actual difference now between local settlement and regional settlement?

What Moves Locally vs Regionally

Domestic payment rails haven’t changed. If money moves within Nigeria, it still goes through NIBSS. Global transactions, such as Nigeria to China, still rely on correspondent banks and dollar clearing.

Regional transactions, such as Nigeria to Kenya, Ghana to South Africa, or Egypt to Morocco, can now settle through this regional infrastructure. This is where PAPSS operates. Everything before settlement, like payment initiation and domestic processing, and everything after settlement, like final credit to the beneficiary, continues to run on existing domestic systems.

Now that we have walked through how PAPSS changes settlement behind the scenes, the next question is how this compares to the system developers have been building around for years.

For most cross-border payments in Africa today, correspondent banking still sits at the center of the flow because it is familiar, widely adopted, and deeply embedded in bank infrastructure. It’s also a major reason cross-border transfers feel slow, expensive, and unpredictable for both users and developers.

To understand the real impact of PAPSS, it helps to compare it directly with correspondent banking and see where the differences show up in daily payment flows, settlement timelines, and developer experience.

PAPSS vs Correspondent Banking for Cross-Border Payments

It’s tempting to see PAPSS as a full replacement for correspondent banking, but that assumption often leads to architectural mistakes. Understanding the differences between PAPSS and correspondent banking helps teams make better design decisions. They solve similar problems, but they operate very differently.

Feature	PAPSS	Correspondent Banking
Settlement Currency	Local African currencies	Typically USD, EUR, GBP
Intermediaries	Regional layer system coordinated through participating central banks	Multiple (originating bank → correspondent → clearing house → correspondent → beneficiary)
Speed	Hours to same day (depending on window)	1-5 business days
Cost Drivers	Central bank levies, single FX conversion	FX spreads, correspondent fees, lifting fees
Failure Modes	PAPSS system issues, domestic rail failures	Correspondent account problems, SWIFT rejections, compliance holds
Coverage	PAPSS member countries only	Global reach

The key point is that PAPSS reduces reliance on correspondent banking for intra-African corridors, but it does not remove correspondent banking in all cases.

At a technical level, the differences are straightforward: fewer intermediaries, faster settlement, and more predictable outcomes. The real impact, however, shows up in what developers can build on top of this infrastructure.

Once settlement becomes faster and more reliable, entirely new payment experiences become possible. This is where PAPSS moves from being background infrastructure to an actual enabler for cross-border products.

What PAPSS Enables for Developers

From a developer’s perspective, PAPSS is interesting because it opens up new options rather than forcing you to rewrite existing workflows. The benefits show up clearly in a few practical use cases.

Faster regional settlement allows you to offer same-day settlement for B2B payments between participating countries. For example, a payroll platform paying remote workers across West Africa can credibly promise that a payment sent on Thursday morning arrives Thursday afternoon, rather than the following week.

Lower FX complexity also matters for intra-African flows. Instead of quoting a naira-to-dollar rate and then a dollar-to-shilling rate, with spreads applied at each step, you can manage local currency pairs directly or rely on centralized regional liquidity. This simplifies pricing logic and reduces hedging complexity on your books.

New routing options make smarter payment orchestration possible. You can design routing logic that selects between correspondent rails for global reach and regional rails for speed and cost. A fintech facilitating merchant payouts can route Egyptian payments to Nigerian vendors through PAPSS, while still using SWIFT for payments to suppliers in Germany.

One important thing to note is that PAPSS improves settlement behind the scenes without changing the front-end payment experience. Your users still initiate payments the same way. What changes is how quickly and efficiently those payments settle after the transaction is submitted.

It may be tempting to see PAPSS as a silver-bullet solution that requires a full rewrite of your payments stack. That’s not how it should be approached. A better mental model is to treat it like an additional routing layer in your payment network that supports your existing system rather than replacing it.

Keep the following in mind when deciding how to use PAPSS:

Domestic Rails are Still Required: PAPSS handles the cross-border settlement leg. Final settlement still runs through NIBSS, KEPSS, or the relevant real-time gross settlement system in the destination country. This means you still need integrations with local banks and mobile money operators.
Global Corridors Still Rely on Correspondent Banks: Payments from Nigeria to the UK or Kenya to India do not use PAPSS. Those flows still go through traditional correspondent routes in London or New York. Still keep SWIFT handling as part of your stack.
Consumer Payment UX Remains Unchanged: PAPSS is a settlement layer, not a consumer-facing product. Your mobile app flows, QR codes, authentication, and checkout experience stay the same. The change happens after the user clicks “Pay.”

How to Design a System That Uses PAPSS

The next obvious question is how to design PAPSS into your existing architecture. If your system already supports asynchronous settlement, multiple corridors, and more than one payout rail, adding this regional layer becomes a routing decision rather than a rewrite. The key principle is to treat PAPSS as one settlement option among others, not as a special workflow with its own state machine.

Treat PAPSS as a Settlement Option, Not a Payment Type

PAPSS does not change your payment initiation flow. You do not need to expose an option like “Pay with PAPSS” at checkout. That usually creates confusion, since users should not have to care about the settlement rail behind the scenes.

Instead, users initiate payments the same way they always have. Your system decides how the payment settles based on corridor, currency, and availability.

Architecturally, this logic belongs in the settlement layer, not in the payment intent model. The payment intent captures what the user wants to do, such as sending 10,000 naira to Kenya. The settlement layer decides whether the intent routes through a correspondent bank in London or through the regional switch.

Route Settlement Based on Corridor and Currency

Eligibility depends on the specific corridor and the currencies involved. Not all African countries participate yet, and even among participants, not every currency pair is supported for direct settlement.

Your routing logic should rely on configuration, not hard-coded rules. Maintain a table that defines supported corridors, currencies, liquidity thresholds, and preferred rails. When a payment enters the system, query this configuration to select the optimal path. If the regional rail offers better speed and cost for Nigeria to Kenya, use it. If the corridor is Nigeria to China, fall back to correspondent banking.

Parallel Settlement Paths, Same State Machine

Avoid creating PAPSS-specific states in your payment state machine. A payment initiated through any rail should move through the same lifecycle states, such as pending, processing, settled, or failed.

Whether a payment settles via PAPSS or through correspondent banking, the state transitions remain the same. Only the settlement rail changes. This keeps the system simpler and easier to maintain over time.

Fallback Strategies When PAPSS Is Not Available
Like any infrastructure, PAPSS has dependencies. Whether it can be used at any given time depends on corridor participation, currency support, liquidity availability, and operational uptime.

Your system should handle these cases explicitly. If the regional rail returns a timeout or rejection, your orchestrator should automatically fall back to correspondent banking, where possible, or queue the transaction for manual review. These fallbacks should be observable so your operations team knows when the system is running on backup rails, since cost and settlement timelines change.

Reconciliation and Finality with PAPSS
PAPSS operates with settlement windows, which means settlement is not always immediate. The system may run multiple settlement cycles per day, and finality only arrives when participating central banks confirm the debit and credit entries.

Design your ledger to wait for settlement confirmation events. Update internal balances and notify beneficiaries only after you receive a confirmation webhook or a successful polled response. Avoid crediting accounts based solely on payment submission acknowledgments.

Account for idempotency as well. Retries caused by network timeouts should not result in double settlement or duplicate ledger entries.

Add Observability to Your Cross-Border System

Because PAPSS spans multiple countries, central banks, and institutions, visibility becomes even more important. Track settlement latency by rail, fallback frequency, and failure rates by corridor. These metrics help you understand where the system performs well and where it struggles.

Build dashboards that show this data in near real time so that when the regional rail slows down or becomes unavailable, you know before your support queue fills up.

Wrap Up

PAPSS is an infrastructure built to simplify regional settlement across eligible African corridors. When used correctly, it reduces reliance on offshore correspondent banks, speeds up settlement timeline for intra-African payments, and lowers FX complexity.

Developers who understand where this regional layer fits, treat it as one rail among many, and maintain strong observability can build more resilient cross-border payment systems for Africa. The goal is to keep and transfer money securely within the continent when possible, and still connect seamlessly to global rails when needed.

Irrespective of the role you play in the payment flow, it is important to recognise that PAPSS introduces its own operational complexity and implementation overhead. Working across corridors still requires coordination around compliance, liquidity, and integration. This is where Flutterwave adds value. Operating across multiple African and international markets, they help reduce the overhead involved in meeting regulatory requirements, managing integrations, and running cross-border payments at scale.

How to Collect Payments Using the Payment Orchestrator Flow in v4

Demola Malomo — Fri, 13 Feb 2026 09:02:24 +0000

This guide walks you through the payment orchestrator flow and how to use it to process payments with cards, mobile money, and Unstructured Supplementary Service Data (USSD).

What is the Payment Orchestrator Flow?

The Payment O rchestrator flow lets you collect payments easily using multiple payment methods in a single charge. It features a robust endpoint where you can specify the payment method, the customer being charged, and any other required details in a single request.

This approach is useful when you need to process a one-time charge without storing customer payment details for future use. Some common use cases include:

E-commerce Checkout: An online store that lets customers buy items without creating an account.
Event Ticketing: A platform that sells tickets to multiple customers without saving payment details.
Non-Profit Donations: A charity accepting one-time donations.
Online Services: A fitness studio charging for drop-in classes on a per-session basis.

Collecting Payments with the Payment Orchestrator Flow

Before you start collecting payments with our APIs, you need to generate a token that lets you access the APIs for a specific period.

To do this, log into your dashboard to obtain your Client ID and Client Secret. These are needed to generate the token and refresh it once it expires.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

Check out the authentication process to learn more.

Once the token is generated, you can use it to create a charge, as shown below:

Initiate the Charge

To initiate a charge, select the appropriate option based on the customer's payment method.

For Card Payments, send a request to the charge with the orchestrator endpoint with the customer’s personal identifiable information (PII), amount, currency, and encrypted card details.

curl -X POST "https://developersandbox-api.flutterwave.com/orchestration/direct-charges" \
        -H "Content-Type: application/json" \
        -H "X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}" \
        -H "X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}" \
        -H "Authorization: Bearer {{YOUR_ACCESS_TOKEN}}" \
        -d '{
            "amount": 1234.56,
            "currency": "USD",
            "reference": "YOUR_EXAMPLE_REFERENCE",
            "payment_method": {
                "type": "card",
                "card": {
                    "nonce": "{{ENCRYPTED_NONCE}}",
                    "encrypted_expiry_month": "{{ENCRYPTED_EXPIRY_MONTH}}",
                    "encrypted_expiry_year": "{{ENCRYPTED_EXPIRY_YEAR}}",
                    "encrypted_card_number": "{{ENCRYPTED_CARD_NUMBER}}",
                    "encrypted_cvv": "{{ENCRYPTED_CVV}}"
                }
            },
            "redirect_url": "https://google.com",
            "customer": {
                "address": {
                    "country": "US",
                    "city": "Gotham",
                    "state": "Colorado",
                    "postal_code": "94105",
                    "line1": "221B Baker Street"
                },
                "phone": {
                    "country_code": "41",
                    "number": "7069423351"
                },
                "name": {
                    "first": "King",
                    "middle": "Leo",
                    "last": "James"
                },
                "email": "james@example.com"
            }
        }'

A key parameter in the request body is payment_method. It tells the orchestrator what type of payment to process. In this case, the payment method is set to card along with the corresponding card details.

"payment_method": {
    "type": "card",
    "card": {
        "nonce": "{{ENCRYPTED_NONCE}}",
        "encrypted_expiry_month": "{{ENCRYPTED_EXPIRY_MONTH}}",
        "encrypted_expiry_year": "{{ENCRYPTED_EXPIRY_YEAR}}",
        "encrypted_card_number": "{{ENCRYPTED_CARD_NUMBER}}",
        "encrypted_cvv": "{{ENCRYPTED_CVV}}"
    }
},

For Mobile Money, send a request to the same charge endpoint and set the payment method to mobile_money.

curl -X POST "https://developersandbox-api.flutterwave.com/orchestration/direct-charges" \
        -H "Content-Type: application/json" \
        -H "X-Trace-Id: {{UNIQUE_TRACE_ID}}" \
        -H "X-Idempotency-Key: {{UNIQUE_IDEMPOTENCY_KEY}}" \
        -H "Authorization: Bearer {{API_ACCESS_TOKEN}}" \
        -d '{
            "amount": 1234.56,
            "currency": "UGX",
            "reference": "YOUR_EXAMPLE_REFERENCE",
            "payment_method": {
                "type": "mobile_money",
                "mobile_money": {
                    "country_code": "233",
                    "network": "MTN",
                    "phone_number": "9012345678"
                }
            },
            "customer": {
                "address": {
                    "country": "US",
                    "city": "Gotham",
                    "state": "Colorado",
                    "postal_code": "94105",
                    "line1": "221B Baker Street"
                },
                "email": "james@example.com",
                "meta": {},
                "name": {
                    "first": "King",
                    "middle": "Leo",
                    "last": "James"
                },
                "phone": {
                    "country_code": "233",
                    "number": "9012345678"
                }
            }
        }'

For USSD, the process involves two steps. First, you need to retrieve the bank code, which is a unique identifier for each bank.

Note that bank codes are retrieved based on the specified country.

For Nigerian banks, send a request using the NG identifier.

curl -X GET "https://developersandbox-api.flutterwave.com/banks?country=NG" \
        -H "accept: application/json" \
        -H "X-Trace-Id: {{UNIQUE_TRACE_ID}}" \
        -H "authorization: Bearer {{API_ACCESS_TOKEN}}"

You’ll get a response with the list of banks.

{
    "status": "success",
    "message": "Bank list retrieved successfully",
    "data": [
    {
        "id": "bnk_cYjd92Qk",
        "code": "044",
        "name": "Access Bank"
    }
    .......
    ]
}

Then, use the bank code to make the same request to the charge endpoint and set the payment method to ussd.

curl -X POST "https://developersandbox-api.flutterwave.com/orchestration/direct-charges" \
        -H "Authorization: Bearer {{YOUR_ACCESS_TOKEN}}" \
        -H "Content-Type: application/json" \
        -H "X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}" \
        -H "X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}" \
        -d '{
            "reference": "YOUR_EXAMPLE_REFERENCE",
            "currency": "NGN",
            "amount": 1234.56,
            "payment_method": {
                "type": "ussd",
                "ussd": {
                    "account_bank": "044"
                }
            },
            "redirect_url": "http://www.google.com",
            "customer": {
                "address": {
                    "country": "US",
                    "city": "Gotham",
                    "state": "Colorado",
                    "postal_code": "94105",
                    "line1": "221B Baker Street"
                },
                "phone": {
                    "country_code": "1",
                    "number": "9069423351"
                },
                "name": {
                    "first": "King",
                    "middle": "Leo",
                    "last": "James"
                },
                "email": "james@example.com"
            }
        }'

In addition to the payment methods discussed above, the orchestrator flow also supports accepting payments with OPay.

Payment Method	Type
OPay	`opay`

Check the API reference for the complete list of supported parameters you can include in your request.

Authorize the Charge

After initiating the charge, you’ll get a response that contains a next_action object that informs you on how the customer should complete the transaction.

For example, if the next_action is of type redirect_url, you need to redirect the user to the provided URL so they can complete the transaction.

"next_action": {
    "type": "redirect_url",
    "redirect_url": {
    "url": "https://developer-sandbox-ui-sit.flutterwave.cloud/redirects?card&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6ImFjODMxOTNlLWFhMmItNDc2ZS1hZTNjLTMxYmVmMTc4NDUxZCIsImNoYXJnZUlkIjoiY2hnX1JDRHNDQkR5YVYiLCJzdWIiOiJhYzgzMTkzZS1hYTJiLTQ3NmUtYWUzYy0zMWJlZjE3ODQ1MWQiLCJpYXQiOjE3MzA5NjQ1MTIsImV4cCI6MTczMDk2NDgxMn0.tMv1VZ4WevvZ_dg37AzYnhj0Z1YtXK_tQIOJcErNscI"
    }
},

Possible responses you may receive include:

requires_pin: The customer needs to complete the transaction using their card PIN.
requires_otp: The customer must complete the transaction using the password sent to their mobile number.
redirect_url: The customer needs to visit the provided URL to complete the transaction.
requires_additional_fields: The customer must provide additional information, such as the billing address.
payment_Instructions: The customer must follow specific instructions to complete the charge. For example, a USSD transaction requires the customer to complete the process offline.

For authorization methods like redirect_url and payment_instruction, where users complete the charge externally by visiting a redirect URL or completing it on their mobile phone, you only need to verify the payment. You can do this using a webhook or by querying the charge endpoint at specific intervals. More details on the verification step are covered in the next section.

For authorization methods like requires_pin, requires_otp, and requires_additional_fields, where users complete the charge internally, you need to authorize the charge by sending a request to the update charge endpoint and specifying the authorization object.

In a card payment that requires the customer’s PIN, update the request by sending the encrypted card PIN.

curl -X PUT "https://developersandbox-api.flutterwave.com/charges/{id}" \
        -H "Authorization: Bearer {{YOUR_ACCESS_TOKEN}}" \
        -H "Content-Type: application/json" \
        -H "X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}" \
        -H "X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}" \
        -d '{
            "authorization": {
                "type": "pin",
                "pin": {
                    "nonce": "{{ENCRYPTED_NONCE}}",
                    "encrypted_pin": "{{ENCRYPTED_PIN}}"
                }
            }
        }'

Verify the Transaction

Finally, you need to verify the transaction details, such as status and amount, before providing value to the customer. You can verify the transaction using either of the following methods:

Webhook (Recommended): We'll send a webhook with the transaction status if you have webhooks enabled on your dashboard.

{
    "webhook_id": "wbk_yXvsB4LzWSwhUCpAPCBR",
    "timestamp": 1739456704200,
    "type": "charge.updated",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 1234.56,
        "currency": "USD",
        "customer": {
            "id": "cus_dc0FUyBpd0",
            "address": {
                "city": "Gotham",
                "country": "US",
                "line1": "221B Baker Street",
                "line2": "",
                "postal_code": "94105",
                "state": "Colorado"
            },
            "email": "james@example.com",
            "name": {
                "first": "King",
                "middle": "Leo",
                "last": "James"
            },
            "phone": {
                "country_code": "1",
                "number": "6313958745"
            },
            "meta": {},
            "created_datetime": "2024-12-25T20:16:38.246Z"
        },
        "description": null,
        "meta": {},
        "payment_method": {
            "type": "card",
            "card": {
                "expiry_month": 9,
                "expiry_year": 32,
                "first6": "553188",
                "last4": "2950",
                "network": "MASTERCARD",
                "billing_address": null,
                "cof": null,
                "card_holder_name": null
            },
            "id": "pmd_ujxuBcf4cJ",
            "customer_id": null,
            "meta": {},
            "device_fingerprint": null,
            "client_ip": null,
            "created_datetime": "2025-02-05T14:06:10.344Z"
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        },
        "created_datetime": "2025-02-13T14:24:43.133Z"
    }
}

Charge Endpoint: You can manually check the charge status by sending a request to retrieve a charge endpoint at a specific interval.

curl --request GET \
--url 'https://api-sit.flutterwave.cloud/developersandbox/charges/{id}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You’ll get a response similar to this:

{
    "status": "success",
    "message": "Charge updated",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 1234.56,
        "currency": "NGN",
        "customer": "cus_EFE4TQhBSf",
        "meta": {},
        "payment_method_details": {
            "type": "card",
            "card": {
                "expiry_month": 8,
                "expiry_year": 2024,
                "first6": "123412",
                "last4": "4444",
                "network": "mastercard"
            },
            "id": "pmd_NkWibrRJIy",
            "customer": "cus_dc0FUyBpd0",
            "meta": {}
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        }
    }
}

Wrapping Up

The payment orchestrator flow simplifies payment collection and supports multiple payment methods, including cards and mobile money. Its robust API makes it ideal for various payment-related use cases, such as one-time payments.

To get started:

Sign up for the new sandbox environment.
Check out the payment orchestrator documentation.
Use the Flutterwave AI Assistant to explore the API, generate sample requests, and troubleshoot common issues.

How to Collect Payments Using the v4 APIs

Demola Malomo — Fri, 06 Feb 2026 08:33:02 +0000

This guide covers everything you need to know about collecting payments with:

Cards
Mobile Money
Pay with Bank Transfers (PWBT)
Opay
USSD

By the end, you’ll understand how the v4 APIs work, the supported payment flows, authorization models, and how to charge using each payment method.

Before we dive in, let’s take a closer look at the v4 APIs, how they differ from v3, and why they’re a step up.

How v4 APIs Differ from v3

With the release of our v4 APIs, there are a few important changes to keep in mind. This applies whether you're integrating for the first time or coming from the v3 APIs. From updated authentication flows to more structured responses and better error handling, v4 introduces some meaningful improvements. Here are a few key upgrades to note:

OAuth2.0 Secure

Managing test and production API keys in your codebase is no longer necessary. Flutterwave now uses Open Authorization (OAuth 2.0), a secure authorization mechanism that connects your application to our servers without exposing static API keys. Unlike API keys, which can be easily exploited if leaked, OAuth 2.0 uses access tokens with expiration times, making it much harder for unauthorized users to maintain long-term access.

Dedicated Sandbox Environment

In v4, you can easily onboard as a developer, test our APIs, and simulate your payment gateway needs. The sandbox includes a redesigned UI, a consistent workflow, and a smoother experience as you build and test. Don’t have an account yet? Create one now.

Improved Workflow

Our v4 APIs follow true RESTful principles. Integration is predictable and scalable and follows industry best practices. For example, when initiating a card payment, you no longer need to encrypt the entire payload. Only the card information needs encryption. You also do not need to call the charge card endpoint multiple times to determine the appropriate authorization method.

Better Developer Experience

A major issue with the v3 API was its generic error messages, which did not clearly indicate what went wrong or how to resolve it. In v4, error responses are well-structured and provide clear insights:

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Invalid card number",
        "validation_errors": []
    }
}

v4 also supports more test cases via scenario keys. This mechanism allows you to simulate different payment scenarios with ease.

Scalability

API requests in v4 follow a consistent flow across all payment methods. This reduces technical overhead. You can create reusable helper functions across your codebase, making integrations more efficient and scalable.

Collecting Payments with the v4 API

To collect payments using the v4 APIs, you can choose between the General Flow and the Orchestrator Flow.

The General Flow breaks the payment process into distinct steps, like setting up payment methods, creating customer details, and handling authorization. This gives you more control and lets you customize the payment experience based on your needs.

The Orchestrator Flow simplifies everything by letting you collect payment through a single request. You specify the payment method, the customer, and any other required details in one go.

Use Cases of General Flow and Orchestrator Flow
When building your payment experience, the choice between these two flows depends on how you want to manage customer data and handle repeat transactions.

General Flow: Best suited for subscription-based or recurring billing models where you need more control over customer data and payment methods. You can create and manage customers, store payment methods, and use that data to bill users over time. This works well for services that charge periodically.

For example, think of platforms like Spotify or Notion. Once a customer signs up, you keep their details and bill them every month without asking again.
Orchestrator Flow: Great for one-time transactions where you don’t need to store customer or payment details. It’s quick, secure, and designed for fast payments, ideal for situations where speed matters more than long-term retention.

For example, customers pay and go when buying a concert ticket or ordering food as a guest: no saved info, no accounts, just a smooth one-off transaction.

Use Case Type	Recommended Flow	Key Benefits
Monthly Subscriptions	General Flow	Store customer/payment info for recurring billing
One-Time Ticket Sales	Orchestrator Flow	Fast, anonymous transactions without data persistence
SaaS Tools	General Flow	Full control of billing cycles and customer management
Flash Sales	Orchestrator Flow	Speed and simplicity for high-velocity checkouts
Food Delivery (Guest)	Orchestrator Flow	No account needed; frictionless payments
Utility Services	General Flow	Long-term customer profiles and scheduled payments

This guide uses the General Flow to collect payments. Check out the Orchestrator Flow to see how it works and how to use it to collect payments.

How to Collect Payment with the General Flow

Collecting payment with the General Flow involves five key steps:

Create a Customer
Create a Payment Method
Initiate a Charge
Authorize a Charge
Verify the Payment Status

Before you start, you need to generate a token. This token gives you access to the APIs for a limited period and is required for making authenticated requests.

To do this, log into your dashboard to obtain your Client ID and Client Secret. These are needed to generate the token and refresh it once it expires.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

Check out the authentication process to learn more.

As a rule of thumb, store sensitive information (like your Client ID) using environment variables or secrets management tools like AWS Secrets Manager.

Once the token is generated, you can use it to create a charge, as shown below:

Step 1: Create a Customer

To create a customer, send a request to the create customer endpoint with the customer’s details. Only the customer’s email is required; however, we recommend you collect as much information as you can.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/customers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "address":{
        "city":"Gotham",
        "country":"US",
        "line1":"221B Baker Street",
        "line2":"",
        "postal_code":"94105",
        "state":"Colorado"
    },
    "name":{
        "first":"King",
        "middle":"Leo",
        "last":"James"
    },
    "phone":{
        "country_code":"1",
        "number":"6313958745"
    },
    "email":"james@example.com"
}'

You'll receive a response containing the customer ID that you can use for future charges.

{
    "status": "success",
    "message": "Customer created",
    "data": {
        "id": "cus_X0yJv3ZMpL",
        "address": {
            "city": "Gotham",
            "country": "US",
            "line1": "221B Baker Street",
            "line2": "",
            "postal_code": "94105",
            "state": "Colorado"
        },
        "email": "james@example.com",
        "name": {
            "first": "King",
            "middle": "Leo",
            "last": "James"
        },
        "phone": {
            "country_code": "1",
            "number": "6313958745"
        },
        "meta": {},
        "created_datetime": "2025-01-29T12:44:53.049Z"
    }
}

Best Practices to Follow when Creating Customers

Add a unique X-Trace-Id to each request. This helps with observability and makes debugging easier.

Include a unique X-Idempotency-Key for every request. This prevents duplicate customer creation during retries or network issues.

Save the id returned in the response. You’ll need it to reference the customer in future transactions. This helps avoid duplicate profiles and makes it easier to track customer activity.

Validate all input on the client and server sides. For example, check for a valid email format or proper phone number structure.

Step 2: Create a Payment Method

Depending on the payment method your customer wants to use, follow the preferred approach below:

Cards

To collect payment with cards, send a request to the create a payment method endpoint. You must also encrypt card details before sending the requests.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/payment-methods' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "type": "card",
    "card": {
        "encrypted_card_number": "{{$encrypted_card_number}}",
        "encrypted_expiry_month": "{{$encrypted_expiry_month}}",
        "encrypted_expiry_year": "{{$encrypted_expiry_year}}",
        "encrypted_cvv": "{{$encrypted_cvv}}",
        "nonce": "{{$randomly_generated_nonce}}"
    }
}'

A key parameter to note in the request body is type. It tells the general flow endpoint the type of payment to process. In this case, the payment method is set to card along with the corresponding card details.

Similar to the customer creation step, you’ll get a payment method ID.

{
    "status": "success",
    "message": "Payment method created",
    "data": {
        "type": "card",
        "card": {
            "expiry_month": 8,
            "expiry_year": 32,
            "first6": "123412",
            "last4": "2222",
            "network": "mastercard"
        },
        "id": "pmd_wlVhaYmkl2",
        "meta": {},
        "created_datetime": "2024-12-03T14:29:26.650973145Z"
    }
}

Mobile Money

To use Mobile Money, send a request to the same create a payment method endpoint. Set the type as mobile_money and include the mobile number country code, network, and mobile number.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/payment-methods' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "type": "mobile_money",
    "mobile_money": {
        "country_code": "233",
        "network": "MTN",
        "phone_number": "9012345678"
    }
}'

You’ll also get a response with a payment method ID.

{
    "status": "success",
    "message": "Payment method created",
    "data": {
        "type": "mobile_money",
        "mobile_money": {
            "network": "MTN",
            "country_code": "233",
            "phone_number": "9012345678"
        },
        "id": "pmd_kwU1jeHpBC",
        "meta": {},
        "created_datetime": "2025-01-30T12:25:52.596970660Z"
    }
}

Pay with Bank Transfers (PWBT)

With PWBT, your customers pay into a generated bank account that’s linked to your Flutterwave settlement account. You can choose to generate either a static account or a dynamic one, depending on your use case.

Use a static account if you plan to reuse the same account for multiple transactions.
Use a dynamic account for one-off payments.

To create a payment method with PWBT, send a request to the create a virtual account endpoint. You’ll need to include a unique reference for the customer, the customer ID generated earlier, whether the account type is static or dynamic, and other important information, as shown below:

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/virtual-accounts' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--header 'Content-Type: application/json' \
--data '{
    "reference": "a4d5f6b8-a785-4d41-8932-50fd8288aec8",
    "customer_id": "cus_WWVaC0InrN",
    "amount": 1500,
    "currency": "NGN",
    "account_type": "dynamic",
    "narration": "John Doe"
}'

If you don’t set an expiry time for a dynamic bank account, it will expire after 3600 seconds (60 minutes) by default.

You’ll get a response with a payment method ID.

{
    "status": "success",
    "message": "Virtual account created",
    "data": {
        "id": "van_fRiLt0WNsj",
        "amount": 1500,
        "account_number": "4032866864",
        "reference": "9d961ebf-6e51-4970-a334-af6a39325930",
        "account_bank_name": "WEMA BANK",
        "account_type": "dynamic",
        "status": "active",
        "account_expiration_datetime": "2025-06-02T08:03:21.369640550Z",
        "note": "Please make a bank transfer to John Doe",
        "customer_id": "cus_WWVaC0InrN",
        "created_datetime": "2025-06-02T08:02:21.383710209Z",
        "meta": {}
    }
}

OPay

To use OPay, send a request to the same payment method endpoint and set the type to opay.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/payment-methods' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "type":"opay"
}'

You’ll get a response with a payment method ID.

{
    "status": "success",
    "message": "Payment method created",
    "data": {
        "type": "opay",
        "opay": {},
        "id": "pmd_uF9ADr9LvH",
        "meta": {},
        "created_datetime": "2024-12-26T14:38:25.179075400Z"
    }
}

USSD

To collect payments with USSD, start by sending a request to the get bank endpoint. Add the country as a query parameter to fetch a list of banks along with their unique bank codes.

curl --request GET \
--url 'https://developersandbox-api.flutterwave.com/banks?country=NG' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \

Bank codes are unique identifiers used to determine which bank will handle the USSD payment.

After the customer selects a bank, create a payment method using that bank’s code and set the type to ussd.

curl --location 'https://developersandbox-api.flutterwave.com/payment-methods' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "type": "ussd",
    "ussd": {
    "account_bank": "050"
    }
}'

Best Practices to Follow when Creating Payment Methods

Use the encryption utility to encrypt fields like card_number, expiry_month, expiry_year, and cvv.

Always match the type field with the correct nested object (card, mobile_money, etc.) in your request body.

Always call the /banks?country={<REPLACE WITH COUNTRY CODE>} endpoint to get the latest list of supported banks and their codes for USSD. Present this list to users to reduce friction and increase conversion.

Every successful request returns a unique id (e.g., pmd_wlVhaYmkl2) for that payment method. You’ll need this ID for initiating charges later, so store it securely in your system.

If your use case involves recurring or customer-linked payments via bank transfers, use static account instead of a dynamic one.

Step 3: Putting it Together — Initiate a Charge

To initiate the charge, use the customer and payment method IDs you got from the previous steps to send a request to the charge endpoint. You’ll need to pass in the amount, currency, and a unique reference.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "reference": "cedfa85a-a803-4a06-a586-0f81fb9b9f22",
    "currency": "USD",
    "customer_id": "cus_IpH7CKCUtD",
    "payment_method_id": "pmd_wlVhaYmkl2",
    "redirect_url":"https://google.com",
    "amount": 250,
    "meta":{
        "person_name": "King James",
        "role": "Developer"
    }
    }
'

Check out the API reference to see other supported parameters.

Note that for PWBT, you don’t need to initiate the charge as shown above, but instead display the account details generated for the customer to complete payment.

Step 4: Authorize the Charge

After initiating the charge, the customer needs to authenticate the transaction. Flutterwave returns a next_action object to inform you of the type of authentication required to complete the payment.

Cards

In cards, a sample next_action is the address verification (AVS) that requires the customer to provide their address information to authorize the charge.

"next_action": {
    "type": "requires_additional_fields",
    "requires_additional_fields":{
            "fields":[
                "authorization.avs.address.postal_code",
                "authorization.avs.address.line1",
                "authorization.avs.address.state",
                "authorization.avs.address.country",
                "authorization.avs.address.city"
            ]
            }
},

To authorize a charge using AVS, update the charge by sending a request to the update charge endpoint with the required address information and charge ID.

curl --request PUT 'https://developersandbox-api.flutterwave.com/charges/{id}' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "authorization": {
        "type": "avs",
        "avs": {
        "city":"Gotham",
        "country":"US",
        "line1":"221B Baker Street",
        "line2":"",
        "postal_code":"94105",
        "state":"Colorado"
    }
    }
}'

Possible next_actions you should cater to in v4 include:

Authorization Method	Response Type
3DS/VBVSECURECODE	`redirect_url`
External 3DS	`redirect_url`
AVS	`requires_additional_fields`
PIN	`requires_pin`
USSD	`payment_instructions`
Bank Transfer	`requires_bank_transfer`

Mobile Money

In Mobile Money, the next_action object contains a type of payment_instruction. This means the customer must complete the charge externally on their mobile phone. They’ll receive a push notification from their mobile money platform and authorize the payment by entering their PIN. Once the payment is completed and funds are received, Flutterwave sends you a webhook with the final transaction status. See the Verify the Payment Status section for more details.

PWBT

In PWBT, the next_action object contains a type of requires_bank_transfer. This means the customer must complete the charge by transferring funds to the generated bank account details. Once the payment is completed and funds are received, Flutterwave sends you a webhook with the final transaction status.

OPay

In OPay, the next_action object contains a type of redirect_url. Redirect the customer to the OPay interface to authorize and complete the payment. Once the payment is completed and funds are received, Flutterwave sends you a webhook with the final transaction status.

"next_action":{
        "type":"redirect_url",
        "redirect_url":{
        "url":"https://developer-sandbox-ui-sit.flutterwave.cloud/redirects?opay&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6ImNiYThhMTkwLTE2OGUtNGNmZS05NmY5LTE2NDZhYjFhOWNkYiIsImNoYXJnZUlkIjoiY2hnX25PTmdlQUdZOTciLCJzdWIiOiJjYmE4YTE5MC0xNjhlLTRjZmUtOTZmOS0xNjQ2YWIxYTljZGIiLCJpYXQiOjE3MzgzMTc3MTAsImV4cCI6MTczODMxODAxMH0.QgLoZYfNhHJOJJvOsLA9eLoxOjGF0qnuehPMgMP4zD4"
        }
},

USSD

In USSD, the next_action object contains a type of payment_instruction. This requires the customer to complete the charge externally on their mobile phone. They'll receive a push notification from their mobile money provider and authorize the payment by entering their PIN after dialing the USSD code. Once the payment is completed and funds are received, Flutterwave sends you a webhook with the final transaction status.

"next_action": {
        "type": "payment_instruction",
        "payment_instruction": {
            "note": "Please dial *1414# to complete this transaction"
        }
}

Best Practices to Follow when Authorizing a Charge

Build a flexible handler or router in your code to dynamically process next_action.type and validate values before use, especially if dynamically rendering fields or redirecting.

For sensitive information like addresses, PINs, or card details, never store or log full payment details, and sanitize user input before including it in payloads.

For better UX, pre-fill known user address data if available, especially when dealing with AVS requests.

For payment types with external steps like USSD, display instructions clearly and show a countdown timer or prompt to indicate that the payment is still pending.

Step 5: Verify the Payment Status

The last step is to verify transaction details like status and amount before providing value to the customer. You can verify the transaction using either of the following methods:

Webhook (Recommended): Flutterwave sends a webhook with the transaction status if you have webhooks enabled on your dashboard.

{
    "webhook_id": "wbk_yXvsB4LzWSwhUCpAPCBR",
    "timestamp": 1739456704200,
    "type": "charge.completed",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 2000,
        "currency": "NGN",
        "customer": {
            "id": "cus_dc0FUyBpd0",
            "address": {
                "city": "Gotham",
                "country": "US",
                "line1": "221B Baker Street",
                "line2": "",
                "postal_code": "94105",
                "state": "Colorado"
            },
            "email": "james@example.com",
            "name": {
                "first": "King",
                "middle": "Leo",
                "last": "James"
            },
            "phone": {
                "country_code": "1",
                "number": "6313958745"
            },
            "meta": {},
            "created_datetime": "2024-12-25T20:16:38.246Z"
        },
        "description": null,
        "meta": {},
        "payment_method": {
            "type": "card",
            "card": {
                "expiry_month": 9,
                "expiry_year": 32,
                "first6": "553188",
                "last4": "2950",
                "network": "MASTERCARD",
                "billing_address": null,
                "cof": null,
                "card_holder_name": null
            },
            "id": "pmd_ujxuBcf4cJ",
            "customer_id": null,
            "meta": {},
            "device_fingerprint": null,
            "client_ip": null,
            "created_datetime": "2025-02-05T14:06:10.344Z"
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        },
        "created_datetime": "2025-02-13T14:24:43.133Z"
    }
}

Charge Endpoint: You can manually check the charge status by sending a request to retrieve a charge endpoint at a specified interval.

curl --request GET \
--url 'https://api-sit.flutterwave.cloud/developersandbox/charges/{id}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You’ll get a response similar to this:

{
    "status": "success",
    "message": "Charge updated",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 2000,
        "currency": "NGN",
        "customer": "cus_EFE4TQhBSf",
        "meta": {},
        "payment_method_details": {
            "type": "card",
            "card": {
                "expiry_month": 8,
                "expiry_year": 2024,
                "first6": "123412",
                "last4": "4444",
                "network": "mastercard"
            },
            "id": "pmd_NkWibrRJIy",
            "customer": "cus_dc0FUyBpd0",
            "meta": {}
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        }
    }
}

Wrapping Up

The v4 API supports multiple payment methods, like cards, mobile money, and PWBT (Pay With Bank Transfer), making it easier to accept payments from your customers. It also works with the General and Orchestrator flows, so you can handle recurring or one-time payments based on what your use case needs.

To get started:

Sign up for the new sandbox environment.
Use the Flutterwave AI Assistant to explore the API, generate sample requests, and troubleshoot common issues.

A-Z of Card Payments with Flutterwave v4

Demola Malomo — Fri, 30 Jan 2026 08:28:26 +0000

We recently rolled out a new version of our payment APIs to make payments simpler for Flutterwave merchants and their customers. Our V4 APIs are built to help developers and businesses easily integrate secure, reliable payment solutions into their websites, products, and applications.

This guide covers key features like payment models, transaction handling, and flexible integration options. Whether you're building a new payment platform or improving an existing one, v4 provides the tools to streamline your workflow while maintaining top-tier security and reliability.

By the end of this guide, you'll understand what the v4 APIs are, their advantages, how to charge a card using them, the supported flows, and when to use each flow.

Before we dive into v4, let’s take a quick look at how card payments work in v3 and the common challenges users face. Understanding these pain points will highlight how v4 makes payment processing smoother and more efficient.

How Card Payments Work in v3

Below is an overview of how card payment works:

Customer Initiates Payment: The customer enters their card details on the merchant's platform.
Merchant Processes and Sends Data: The merchant encrypts the card details and transaction information and then sends them to Flutterwave.
Flutterwave Forwards the Transaction: Flutterwave securely sends the transaction details to the acquiring bank.
Transaction Passes Through Card Scheme: The acquiring bank forwards the transaction to the card scheme, which communicates with the issuing bank.
Issuing Bank Approves or Declines: The issuing bank verifies funds, checks for restrictions, authenticates the transaction, and approves or declines it.
Final Confirmation and Settlement: The approval flows back through the same channels to Flutterwave, the merchant is notified, and the transaction is settled.

To charge a card, you’ll do the following:

Initiate a Charge

First, you’ll need to collect the customer's details and card information and encrypt them as the payload. You’ll also need your encryption key from your dashboard.

// Sample of a helper function to encrypt payload

function encrypt(encryptionKey, payload) {
    const text = JSON.stringify(payload);
    const forge = require('node-forge');
    const cipher = forge.cipher.createCipher(
        '3DES-ECB',
        forge.util.createBuffer(encryptionKey),
    );
    cipher.start({ iv: '' });
    cipher.update(forge.util.createBuffer(text, 'utf-8'));
    cipher.finish();
    const encrypted = cipher.output;
    return forge.util.encode64(encrypted.getBytes());
}

Lastly, you’ll then charge your customer by passing the encrypted payload as a client parameter and sending a request to the card endpoint.

curl --request POST \
    --url https://api.flutterwave.com/v3/charges?type=card \
    --header 'Authorization: Bearer <FLW_SECRET_KEY>' \
    --header 'content-type: application/json' \
    --data '{ "client": "Of8p6iJUVUezgvjUkjjJsP8aPd6CjHR3f9ptHiH5Q0+2h/FzHA/X1zPlDmRmH5v+GoLWWB4TqEojrKhZI38MSjbGm3DC8UPf385zBYEHZdgvQDsacDYZtFEruJqEWXmbvw9sUz+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+fxFl4tauG9H4WBChF0agXtP4kjfhfYVD48N9Hrt"}'

However, if you use any of our SDKs, you don’t need to manually encrypt the payload before making a request. Just pass in the payload as you initiate the charge, and we’ll encrypt it.

// Installation: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(
    process.env.FLW_PUBLIC_KEY,
    process.env.FLW_SECRET_KEY,
);

const payload = {
    card_number: '5531886652142950',
    expiry_month: '09',
    expiry_year: '32',
    cvv: '564',
    currency: 'NGN',
    amount: '7500',
    email: 'developers@flutterwavego.com',
    fullname: 'Flutterwave Developers',
    phone_number: '+2349012345678',
    tx_ref: 'UNIQUE_TRANSACTION_REFERENCE',
    redirect_url: 'https://example_company.com/success',
    enckey: process.env.FLW_ENCRYPTION_KEY,
};

flw.Charge.card(payload).then((response) => console.log(response));

You’ll get a response similar to this:

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 288192886,
        "tx_ref": "LiveCardTest",
        "flw_ref": "YemiDesola/FLW275389391",
        "device_fingerprint": "N/A",
        "amount": 100,
        "charged_amount": 100,
        "app_fee": 1.4,
        "merchant_fee": 0,
        "processor_response": "Kindly enter the OTP sent to *******0328",
        "auth_model": "PIN",
        "currency": "NGN",
        "ip": "::ffff:10.7.214.204",
        "narration": "CARD Transaction ",
        "status": "pending",
        "auth_url": "N/A",
        "payment_type": "card",
        "fraud_status": "ok",
        "charge_type": "normal",
        "created_at": "2020-07-15T14:06:55.000Z",
        "account_id": 17321,
        "customer": {
            "id": 216517630,
            "phone_number": null,
            "name": "Yemi Desola",
            "email": "usef@gmail.com",
            "created_at": "2020-07-15T14:06:55.000Z"
        },
        "card": {
            "first_6digits": "123456",
            "last_4digits": "2343",
            "issuer": "MASTERCARD GUARANTY TRUST BANK Mastercard Naira Debit Card",
            "country": "NG",
            "type": "MASTERCARD",
            "expiry": "08/22"
        }
    },
    "meta": {
        "authorization": {
            "mode": "otp",
            "endpoint": "/v3/validate-charge"
        }
    }
}

Authorize the Payment

Depending on the type of card you’re charging, you’ll authorize the card using any of the following methods:

PIN: The customer enters the card PIN to authorize the payment.
AVS (Address Verification System): The customer enters details of the card's billing address. This is often used for international cards.
3DS (3D Secure): The customer needs to be redirected to a secure webpage to complete the payment.
None: In some cases, the card may not need any authorization steps.

The response you get from the initiate charge step determines the kind of authorization method you’ll use. For example, a PIN authorization will look like this:

{
    "status": "success",
    "message": "Charge authorization data required",
    "meta": {
        "authorization": {
            "mode": "pin",
            "fields": ["pin"]
        }
    }
}

The meta.authorization field tells you the required authorization.

To authorize the charge, you’ll call the card endpoint again by encrypting the previous payload and the required authorization method (PIN in this case).

// Installation: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);

const payload = {
    card_number: '5531886652142950',
    expiry_month: '09',
    expiry_year: '32',
    cvv: '564',
    currency: 'NGN',
    amount: '7500',
    email: 'developers@flutterwavego.com',
    fullname: 'Flutterwave Developers',
    phone_number: '+2349012345678',
    tx_ref: 'UNIQUE_TRANSACTION_REFERENCE',
    redirect_url: 'https://example_company.com/success',
    enckey: process.env.FLW_ENCRYPTION_KEY
    "authorization": {
    "mode": "pin",
    "pin": "3310"
    }
}

flw.Charge.card(payload)
.then(response => console.log(response));

Validate the Charge

After the encryption and sending the new payload, you'll get one of these responses:

OTP Required: This response tells you that the customer needs to complete the charge by inputting the OTP sent to their mobile number.

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 288192886,
        "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
        "flw_ref": "FLEG8147171639979534513071",
        "device_fingerprint": "N/A",
        "amount": 7500,
        "charged_amount": 7500,
        "app_fee": 105,
        "merchant_fee": 0,
        "processor_response": "Kindly enter the OTP sent to *******0328",
        "auth_model": "PIN",
        "currency": "NGN",
        "ip": "N/A",
        "narration": "CARD Transaction ",
        "status": "pending",
        "auth_url": "N/A",
        "payment_type": "card",
        "fraud_status": "ok",
        "charge_type": "normal",
        "created_at": "2021-07-15T14:06:55.000Z",
        "account_id": 17321,
        "customer": {
            "id": 370672,
            "phone_number": "2349012345678",
            "name": "Flutterwave Developers",
            "email": "developers@flutterwavego.com",
            "created_at": "2021-07-15T14:06:55.000Z"
        },
        "card": {
            "first_6digits": "553188",
            "last_4digits": "2950",
            "issuer": "MASTERCARD  CREDIT",
            "country": "NG",
            "type": "MASTERCARD",
            "expiry": "09/32"
        }
    },
    "meta": {
        "authorization": {
            "mode": "otp",
            "endpoint": "/v3/validate-charge"
        }
    }
}

You can validate the charge as shown below:

const response = await flw.Charge.validate({
    otp: req.body.otp,
    flw_ref: req.session.flw_ref,
});

Redirect Required: This response requires the customers to go to the redirected URL to complete the charge.

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 1254647,
        "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
        "flw_ref": "IUSE9942171639769110812191",
        "device_fingerprint": "N/A",
        "amount": 7500,
        "charged_amount": 7500,
        "app_fee": 105,
        "merchant_fee": 0,
        "processor_response": "Pending redirect to issuer's 3DS authentication page",
        "auth_model": "VBVSECURECODE",
        "currency": "NGN",
        "ip": "N/A",
        "narration": "CARD Transaction ",
        "status": "pending",
        "payment_type": "card",
        "fraud_status": "ok",
        "charge_type": "normal",
        "created_at": "2021-07-15T14:06:55.000Z",
        "account_id": 17321,
        "customer": {
            "id": 370672,
            "phone_number": "2349012345678",
            "name": "Flutterwave Developers",
            "email": "developers@flutterwavego.com",
            "created_at": "2021-07-15T14:06:55.000Z"
        },
        "card": {
            "first_6digits": "543889",
            "last_4digits": "0229",
            "issuer": "MASTERCARD MASHREQ BANK CREDITSTANDARD",
            "country": "EG",
            "type": "MASTERCARD",
            "expiry": "10/31"
        }
    },
    "meta": {
        "authorization": {
            "mode": "redirect",
            "redirect": "https://auth.coreflutterwaveprod.com/transaction?reference=IUSE9942171639769110812191"
        }
    }
}

Verify the Payment

The last step is to verify that the payment was successful before giving value to your customer by querying the verify endpoint.

curl --request GET \
    --url https://api.flutterwave.com/v3/transactions/{transaction_ID}/verify \
    --header 'Authorization: Bearer FLW_SECRET_KEY' \
    --header 'content-type: application/json'

Challenges with v3 Card Payment

While the v3 API was carefully designed to make card payments seamless, we’ve noticed challenges based on our conversations and the feedback we’ve gathered.

Like any product that serves users, it must evolve to meet their needs. We continuously test our product and collaborate with customers to identify areas for improvement. Here are the setbacks from v3:

Redundant Data Transmission and Encryption Overhead

Each time you call the charge endpoint, you have to send the full payload (including the card details), which must be encrypted. This increases computational overhead and introduces unnecessary complexity, especially when dealing with large transactions.

Security Implication

Even though encryption is in place, transmitting sensitive cardholder data multiple times (initiate and authorize charge step) increases the attack surface.

Higher Latency and Network Traffic

Resending the entire request rather than referencing a previously created charge increases network usage and processing time. If multiple users perform transactions simultaneously, it could slow down the system response times and reduce efficiency.

Developer Experience

You need additional logic to determine whether you're initiating or authorizing a charge. Since both actions use the same endpoint, you must check the response, modify the request, and resend it with authorization details while maintaining data integrity. This adds unnecessary complexity compared to a two-step process with separate endpoints.

Developer Onboarding

In v3, our API is only accessible to businesses. You can't create a dedicated developer sandbox environment to experiment with our APIs and simulate your development experience. Many potential customers found this challenging.

How v4 API Improves Card Payment

With v4, we've listened to our customers and redesigned our API to address these pain points. Here are some of the improvements:

OAuth2.0 Secure

Managing test and production API keys in your codebase is no longer necessary. Flutterwave now uses Open Authorization (OAuth2.0), a secure authorization mechanism that connects your application to our servers without exposing static API keys. Unlike API keys, which can be easily exploited if leaked, OAuth2.0 uses access tokens with expiration times, making it much harder for unauthorized users to maintain long-term access.

Dedicated Sandbox Environment

Improved Workflow

Better Developer Experience

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Invalid card number",
        "validation_errors": []
    }
}

v4 also supports more test cases via scenario keys. This mechanism allows you to simulate different payment scenarios with ease.

Scalability

Now that we understand the improvements that come with v4, let's see it in practice.

How to Charge Card Payments in v4

Before we dive into the implementation details, it's important to understand the key change in how to charge a card. You can now choose from the following methods:

General Flow: This approach breaks the payment process into separate steps, such as setting up the payment method, adding customer details, and handling charge authorization. It gives you more control and allows you to customize the payment experience to fit your needs.
Orchestrator Flow: A straightforward approach where you initiate a payment, handle the response, and set up the required entities, such as the payment method and customer, in a single flow.

How to Charge Card Payments with the General Flow

Our v4 APIs are secured with OAuth2.0 by default and require a token to access them for a specific period. To generate a token, log into your dashboard to obtain your Client ID and Client Secret. These are needed to generate the token and refresh it once it expires.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{CLIENT_ID}}' \
--data-urlencode 'client_secret={{CLIENT_SECRET}}' \
--data-urlencode 'grant_type=client_credentials'

Check out the authentication process to learn more.

Once the token is generated, you can use it to charge a card by following the steps below:

Step 1: Create a Customer

To create a customer, send a request to the create customer endpoint with the customer’s details. Only the customer’s email is required; however, we recommend collecting as much information as possible.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/customers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "address":{
        "city":"Gotham",
        "country":"US",
        "line1":"221B Baker Street",
        "line2":"",
        "postal_code":"94105",
        "state":"Colorado"
    },
    "name":{
        "first":"King",
        "middle":"Leo",
        "last":"James"
    },
    "phone":{
        "country_code":"1",
        "number":"6313958745"
    },
    "email":"james@example.com"
}'

You'll receive a response containing the customer ID, which you can use for future charges.

{
    "status": "success",
    "message": "Customer created",
    "data": {
        "id": "cus_X0yJv3ZMpL",
        "address": {
            "city": "Gotham",
            "country": "US",
            "line1": "221B Baker Street",
            "line2": "",
            "postal_code": "94105",
            "state": "Colorado"
        },
        "email": "james@example.com",
        "name": {
            "first": "King",
            "middle": "Leo",
            "last": "James"
        },
        "phone": {
            "country_code": "1",
            "number": "6313958745"
        },
        "meta": {},
        "created_datetime": "2025-01-29T12:44:53.049Z"
    }
}

Step 2: Create the Card Payment Method

Next, collect the customer’s card details and send a request to the create a payment method endpoint. You must also encrypt card details before sending the requests.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/payment-methods' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "type": "card",
    "card": {
        "encrypted_card_number": "{{$encrypted_card_number}}",
        "encrypted_expiry_month": "{{$encrypted_expiry_month}}",
        "encrypted_expiry_year": "{{$encrypted_expiry_year}}",
        "encrypted_cvv": "{{$encrypted_cvv}}",
        "nonce": "{{$randomly_generated_nonce}}"
    }
}'

Note that v4 reduces encryption overhead because you only need to encrypt specific parts of the payload, such as the card number, expiry month, expiry year, and CVV, rather than the entire request.

Similar to the customer creation step, you’ll get a payment method ID.

{
    "status": "success",
    "message": "Payment method created",
    "data": {
        "type": "card",
        "card": {
            "expiry_month": 8,
            "expiry_year": 32,
            "first6": "123412",
            "last4": "2222",
            "network": "mastercard"
        },
        "id": "pmd_wlVhaYmkl2",
        "meta": {},
        "created_datetime": "2024-12-03T14:29:26.650973145Z"
    }
}

Step 3: Putting it Together Create the Charge

To initiate the charge, use the customer and payment method IDs you got from the previous steps to send a request to the card charge endpoint. You’ll need to pass in the amount, currency, and a unique reference. Check out the API reference to see other supported parameters.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "reference": "cedfa85a-a803-4a06-a586-0f81fb9b9f22",
    "currency": "USD",
    "customer_id": "cus_IpH7CKCUtD",
    "payment_method_id": "pmd_wlVhaYmkl2",
    "redirect_url":"https://google.com",
    "amount": 250,
    "meta":{
        "person_name": "King James",
        "role": "Developer"
    }
    }
'

Step 4: Authorize the Charge

After initiating the charge, the customer needs to authenticate the transaction. Card authentication varies, but we send a next_action object in create the charge step to indicate the required authentication method.

Similar to v3, card authorization can be any of the following:

For example, AVS requires the customer to provide their address information to authorize the charge.

"next_action": {
    "type": "requires_additional_fields",
    "requires_additional_fields":{
            "fields":[
                "authorization.avs.address.postal_code",
                "authorization.avs.address.line1",
                "authorization.avs.address.state",
                "authorization.avs.address.country",
                "authorization.avs.address.city"
            ]
        }
},

Possible responses you should cater to include:

Authorization Method	Response Type
3DS/VBVSECURECODE	`redirect_url`
External 3DS	`redirect_url`
AVS	`requires_additional_fields`
PIN	`requires_pin`
USSD	`payment_instructions`

To authorize the charge using AVS, update the charge by sending a request to the update charge endpoint with the required address information and charge ID.

curl --request PUT 'https://developersandbox-api.flutterwave.com/charges/{id}' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "authorization": {
        "type": "avs",
        "avs": {
        "city":"Gotham",
        "country":"US",
        "line1":"221B Baker Street",
        "line2":"",
        "postal_code":"94105",
        "state":"Colorado"
    }
    }
}'

Step 5: Verify the Transaction

Finally, you need to verify the transaction details, such as status and amount, before providing value to the customer. You can verify the transaction using either of the following methods:

Webhook (Recommended): We'll send a webhook with the transaction status if you have webhooks enabled on your dashboard.

{
    "webhook_id": "wbk_yXvsB4LzWSwhUCpAPCBR",
    "timestamp": 1739456704200,
    "type": "charge.completed",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 2000,
        "currency": "NGN",
        "customer": {
            "id": "cus_dc0FUyBpd0",
            "address": {
                "city": "Gotham",
                "country": "US",
                "line1": "221B Baker Street",
                "line2": "",
                "postal_code": "94105",
                "state": "Colorado"
            },
            "email": "james@example.com",
            "name": {
                "first": "King",
                "middle": "Leo",
                "last": "James"
            },
            "phone": {
                "country_code": "1",
                "number": "6313958745"
            },
            "meta": {},
            "created_datetime": "2024-12-25T20:16:38.246Z"
        },
        "description": null,
        "meta": {},
        "payment_method": {
            "type": "card",
            "card": {
                "expiry_month": 9,
                "expiry_year": 32,
                "first6": "553188",
                "last4": "2950",
                "network": "MASTERCARD",
                "billing_address": null,
                "cof": null,
                "card_holder_name": null
            },
            "id": "pmd_ujxuBcf4cJ",
            "customer_id": null,
            "meta": {},
            "device_fingerprint": null,
            "client_ip": null,
            "created_datetime": "2025-02-05T14:06:10.344Z"
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        },
        "created_datetime": "2025-02-13T14:24:43.133Z"
    }
}

Charge Endpoint: You can manually check the charge status by sending a request to retrieve a charge endpoint at a specified interval.

curl --request GET \
--url 'https://developersandbox-api.flutterwave.com/charges/{id}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You’ll get a response similar to this:

{
    "status": "success",
    "message": "Charge updated",
    "data": {
        "id": "chg_zam88NgLb7",
        "amount": 2000,
        "currency": "NGN",
        "customer": "cus_EFE4TQhBSf",
        "meta": {},
        "payment_method_details": {
            "type": "card",
            "card": {
                "expiry_month": 8,
                "expiry_year": 2024,
                "first6": "123412",
                "last4": "4444",
                "network": "mastercard"
            },
            "id": "pmd_NkWibrRJIy",
            "customer": "cus_dc0FUyBpd0",
            "meta": {}
        },
        "redirect_url": null,
        "reference": "ex61m23ja3feykheoidho8ilrri",
        "status": "succeeded",
        "processor_response": {
            "type": "approved",
            "code": "00"
        }
    }
}

How to Charge Card Payments with the Orchestrator Flow

Charging with the Orchestrator Flow is similar to the General Flow when it comes to creating, authorizing, and verifying a charge. The key difference is that you can initiate the charge directly, without first breaking the process into separate steps for creating a customer and a payment method. To do this, send a request to the orchestrator endpoint.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/orchestration/direct-charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "amount": 1234.56,
    "currency": "USD",
    "reference": "YOUR_EXAMPLE_REFERENCE",
    "payment_method": {
        "type": "card",
        "card": {
            "encrypted_card_number": "{{$encrypted_card_number}}",
            "encrypted_expiry_month": "{{$encrypted_expiry_month}}",
            "encrypted_expiry_year": "{{$encrypted_expiry_year}}",
            "encrypted_cvv": "{{$encrypted_cvv}}",
            "nonce": "{{$randomly_generated_nonce}}"
        }
    },
    "redirect_url": "https://google.com",
    "customer": {
        "address": {
            "country": "US",
            "city": "Gotham",
            "state": "Colorado",
            "postal_code": "94105",
            "line1": "221B Baker Street"
        },
        "phone": {
            "country_code": "41",
            "number": "7069423351"
        },
        "name": {
            "first": "King",
            "middle": "Leo",
            "last": "James"
        },
        "email": "james@example.com"
    }
}'

A key parameter to note is the payment_method. This is where you specify the type of payment (in this case, card) and provide the required details that correspond to the selected payment type.

General Flow vs. Orchestrator Flow: Which One Should You Use?

Both flows allow you to charge a customer’s card. As a rule of thumb:

Use the General Flow for recurring payments, such as subscriptions, where you need to store customer details for future charges.
Use the Orchestrator Flow for one-time payments where storing customer details is not required.

Use Case: Subscription-Based Service

If you run an on-demand video streaming platform like Netflix that offers monthly or yearly subscriptions and requires recurring billing, the General Flow is the best option. You can securely create and store the customer and payment method during the first charge. For subsequent renewals, you only need the customer_id and payment_method_id to process the payment.

In v4, there are two ways to charge a customer’s card for subscription-based payments:

Tokenization: This involves replacing the customer’s sensitive card details with a unique token that can be referenced in the future.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/charges' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
    "reference": "cedfa85a-a803-4a06-a586-0f81fb9b9f22",
    "currency": "USD",
    "customer_id": "cus_IpH7CKCUtD",
    "payment_method_id": "pmd_TusjN23anB",
    "recurring":true,
    "redirect_url":"https://google.com",
    "amount": 250
    }
'

Key parameters to note in the requests are:
reference: A unique identifier that links to the card details.

customer_id: A reference to the customer.

payment_method_id: A reference to the payment method.

recurring: A flag that tells Flutterwave the charge is subscription-based.

Credential-on-File: This works similarly to tokenization but offers more flexibility. Instead of linking the token strictly to Flutterwave’s platform, this method generates a unique token that can be used across multiple platforms, even if Flutterwave didn’t process the original token creation.

Think of it like a national identity card that allows you to sign up for any banking application without needing to provide your details again.

Use Case: Online Event Ticket Purchase

If you sell tickets for concerts or sporting events like Ticketmaster or Eventbrite, where users make one-time payments, then Orchestrator Flow is the better fit. Since customer details don’t need to be stored for future transactions, this approach keeps the process simple and efficient.

Wrapping Up

The v4 API is a significant upgrade over v3, offering a better developer experience, OAuth 2.0 security, a dedicated sandbox environment, and more. Many of the workarounds required in v3 are no longer necessary, as v4 introduces a clear and concise flow that makes it easier to build scalable payment systems.

To get started:

Sign up for the new sandbox environment.
Use the Flutterwave AI Assistant to explore the API, generate sample requests, and troubleshoot common issues.

How to Scale Your Business Without Overspending: Five Payment Strategies

Demola Malomo — Mon, 26 Jan 2026 09:04:39 +0000

Growth is exciting, but it can also stretch your team thin as you try to expand your customer base. When these challenges start to build up, the first instinct is often to throw more money at the problem, usually by hiring more people for sales or engineering.

While that approach can help, it’s usually not enough without a clear support growth plan. In most cases, businesses want to scale by doing more with what they already have to achieve sustainable growth, without increasing costs or team size. The key lies in using the right systems to handle higher volumes efficiently.

In this guide, we’ll explore five proven strategies you can use to scale your business, reduce churn by keeping existing customers happy, and still attract new ones.

Before diving in, let’s take a closer look at what happens when a business scales the wrong way.

The Real Cost of Scaling the Wrong Way

Every business dreams of the moment when everything grows: more customers, more features, and more revenue. But scaling too soon or without the right systems in place can turn that dream into a nightmare.

According to McKinsey research, 78% of startups fail to make it through a full scale-up. This shows how tough and resource-intensive scaling can be. When your product isn’t ready to handle the load, bugs creep in, systems slow down, and customers lose trust. The usual quick fix is to hire more people, buy more tools, and add more layers of communication. Before long, you’re spending thousands each year just to keep things running, though you still might not meet market demands.

The real damage isn’t just in the money you burn; it’s in the momentum you lose. Your teams shift from building cool stuff to fixing problems that shouldn’t exist in the first place, which stalls innovation, decreases morale, and makes your “growth” strategy more about survival than real growth.

With that foundation set, let’s move on to the key factors that determine how scalable your business really is.

What Determines Scalability in Business?

Several factors influence whether a business can scale successfully. At the core, it comes down to keeping efficient operations, automating wherever possible, and building a team that moves quickly and adapts easily.

Below are key factors that determine a company’s ability to scale and grow:

Your Technology Stack: Your technology infrastructure forms the backbone of scalability. If your system can support more users, transactions, or data without slowing down, your customers will experience reliability and consistency even as market demands increase. The key to scaling your technology stack is to invest early in cloud-based servers, flexible storage, and APIs that make integration simple and efficient.
Operational Business Processes: The way your business runs day to day has a major impact on how well it scales. Tech companies that streamline workflows with automation of repetitive tasks, define clear decision paths, and document internal workflow can handle higher volumes without major disruptions.
Business Model: A scalable business model grows without constant reinvention. It should offer a clear, repeatable way to serve customers or enter new markets with minimal overhead. For example, a subscription-based model can support growing businesses’ increased demand without needing to expand resources dramatically.
Team and Culture: You can’t scale what your team doesn’t believe in. A scalable team embraces adaptability, accountability, and ownership. They evolve with the business by learning new tools, refining workflows, and staying open to change.
Financial Flexibility: Scaling requires thoughtful financial planning and access to capital. You need to understand your revenue sources, where to invest, and how to manage funds wisely to maintain momentum as growth accelerates.
Customer Experience: Growth should never come at the cost of customer satisfaction. It’s easy to focus on attracting new customers while neglecting existing ones. A true scalable business means maintaining or even improving response times, platform stability, and service quality as your business grows.
Payment Infrastructure: ****A scalable payment system lets customers pay easily regardless of their location. As your business expands into new markets, you need payment tools that support multiple currencies, regional regulations, and quick settlement. Offering a wide range of payment methods, such as cards, wallets, bank transfers, and mobile money, reduces friction and makes it easier to convert customers at higher volumes.

Understanding what drives business scalability is just the first step. Once you recognize these factors, the next question is how to leverage them to grow efficiently. The following strategies outline practical ways to expand your business while maintaining stability and maximizing your potential.

Strategy 1: Go Global with Cross-Border Payments

When your business is locked into a single market, your growth ceiling stays low. Expanding to international customers and reaching a broader target market often feels too expensive or complicated. You might worry about setting up entities in each country, navigating local regulations, or managing multiple banking relationships. Without cross-border payments, you remain stuck in one market while your competitors go global.

With cross-border payments in place, you can accept money from customers in different countries without building local infrastructure. You’re not just adding new markets; you’re testing them with little to no upfront cost.

For example, if you run a SaaS company in Nigeria, you can use cross-border payments to onboard clients in the UK or the US, allowing them to pay in their local currency. This eliminates the friction of manual transfers or wire fees, reduces customer acquisition cost, and increases revenue.

How To Set tt Up

Integrate a payment gateway that supports multi-currency transactions.
Enable automatic currency conversion so users can pay in their local currency while you still get settled in yours.
Set up compliance measures for international transactions, including KYC and AML checks.
Test a few transactions from international accounts before going live.

This setup helps your business handle global customers smoothly, without friction or compliance issues.

Strategy 2: Expand Payment Methods

Here’s a stat that might surprise you: cart abandonment rates have been rising since 2014, after hitting record highs in 2013. One major reason is that customers don’t see their preferred payment option at checkout. Many leave not because of price or second thoughts, but because you only accept cards while they use mobile money.

Each payment method you add (such as bank transfers, mobile money, USSD, QR codes) opens a new door to your store. What you consider “alternative payments” in one region might be the most common method in another. Supporting multiple options helps you convert more visitors without increasing your marketing spend.

How To Set it Up

Review your payment gateway dashboard to see all available local and global methods.
Activate popular options such as bank transfers, cards, mobile money, or digital wallets.
Customize your checkout flow so customers see the payment methods most relevant to their region.
Track which options deliver the highest conversion rates and focus on optimizing those.

The goal is to make paying feel effortless for every customer, whether they’re using a mobile wallet in Lagos or a debit card in London.

Strategy 3: Implement Tokenization and Recurring Payments to Automate Revenue

If you run a subscription business plan or handle repeated payments, you probably know this nightmare. The first week of every month arrives, and your support team gets flooded with tickets from customers whose cards were declined. Your finance team manually retries payments, which makes revenue unpredictable since you don’t know how many renewals will actually succeed.

Failed payments and manual follow-ups not only create churn but also add extra workload for your team.

Tokenization solves this by using a saved token (a secure, non-sensitive substitute for their actual card details). With the token, you move from chasing payments manually to collecting revenue automatically. It also improves your renewal rate because built-in retry logic handles temporary failures without bothering your customers or your staff.

How To Set it Up

Enable tokenization in your payment provider’s dashboard.
Use API endpoints to create and manage recurring billing profiles.
Notify customers when recurring payments are about to process (to maintain transparency).
Track failed payments automatically and send retry prompts.

Recurring billing not only stabilizes your revenue but also builds customer trust through consistent and reliable payment experiences.

Strategy 4: Speed Up Transactions with Virtual Accounts

Managing payments from individuals/business owners can be straightforward, but business-to-business (B2B) payments often expose operational inefficiencies. For example, when a B2B customer places an order, you issue an invoice, they initiate a bank transfer, and depending on several factors, it might take a few days for the payment to reflect. When it finally does, it often arrives with a vague reference number. Your finance team then spends hours trying to figure out who paid and which invoice it matches. Multiply that by a hundred customers per month, and you’re looking at a significant drain on time and resources.

Virtual accounts fix this by assigning each client or transaction a unique account number. When a customer pays, you instantly know who made the payment and what it was for. There’s no need for manual reconciliation. Even clients with automated payable systems can integrate these virtual account numbers easily. As a result, collection time drops from days to hours, and your finance team can focus on business strategy instead of matching transactions line by line.

How To Set it Up

Create virtual accounts for each client or project through your payment gateway.
Integrate webhook notifications to update your system automatically when payments arrive.
Use your accounting or ERP system to reconcile transactions in real time.
Train your finance or operations team to monitor the virtual account dashboard regularly.

Once configured, virtual accounts make receiving payments as simple as checking your inbox.

Strategy 5: Leverage Payment Analytics to Optimize What's Already Working

Most businesses treat payments like plumbing: as long as money is flowing, they don’t look deeper. But your payment data holds valuable insights about where you might be losing revenue. It can show you which checkout flows convert best, what time of day sees the highest success rates, and which payment methods cost more in processing fees than they generate in conversions.

Payment analytics turns this data into a roadmap for business growth. With the right insights, you can refine your checkout flow, reduce failed transactions, and improve the overall customer experience. Instead of guessing what to fix, the market data lets you know exactly where small tweaks create big results.

How To Set It Up

Use your payment dashboard to review key metrics such as transaction volume, success rate, refund trends, and customer payment preferences.
Integrate analytics tools like Google Data Studio, Metabase, or Power BI for deeper insights and visual tracking.
Monitor metrics like success rate per payment method, refund ratio, customer lifetime value, and average transaction time.
Test and iterate regularly to identify spikes in failed payments or drop-offs. Small optimizations such as adjusting your checkout form, adding new payment options, or switching gateways can make a big impact.
Share insights across teams so everyone stays aligned with the company’s growth potential strategy. ## How Flutterwave Can Help

If you’re looking to scale your business without the payment headaches, Flutterwave comes with built-in tools that make it possible. Here’s how it fits into each strategy:

Cross-border Payments Made Simple

Flutterwave lets you accept payments from customers around the world in multiple currencies. You can get paid in USD, GBP, EUR, NGN, KES, ZAR, and more, while receiving settlements in your preferred currency. This allows you to grow across regions without dealing with currency conversions or complex international transfers.

Multiple Payment Method Supports

Your customers shouldn’t have to think twice about how to pay. Flutterwave supports multiple payment methods, including cards, mobile money, bank transfers, USSD, and digital wallets, all from a single integration. That means more completed checkouts and fewer abandoned carts.

Tokenization and Recurring Payment Support

Flutterwave’s tokenization feature makes recurring payments secure and seamless. You can store a customer’s payment token (not their actual card details) and charge them automatically for subscriptions or repeat purchases. This takes care of PCI-DSS compliance and other security requirements, giving your business predictable revenue and lower churn.

Virtual Accounts

Virtual accounts make business payments easier to track and reconcile. With Flutterwave, you get both static accounts (for recurring payments like utility or subscription billing) and dynamic accounts (for one-time payments such as e-commerce checkouts). You can assign a unique virtual account to each client, invoice, or transaction. Once payments come in, they’re automatically matched to the correct customer or project with no need for manual reconciliation.

Payment Analytics

Flutterwave doesn’t just process your payments; it helps you understand them. The dashboard provides real-time insights into transaction performance, customer behavior, and success rates. These analytics help you identify opportunities, reduce friction, and make smarter decisions about scaling.

Wrapping Up

The companies that will win in the next decade aren’t the ones with the biggest funding rounds or the largest teams. They’re the industry leaders who build strong infrastructure that multiplies their team’s output instead of just adding more people to handle more work.

The smartest way to scale is to start small. Maybe that means adding mobile money if you have customers in East or West Africa, enabling cross-border payments if you’re getting interest from international buyers, or setting up virtual accounts if reconciliation has become a hassle. Pick one, implement it this month, measure the results, and then move on to the next. Consistent, focused improvements outperform scattered, one-time efforts every time.

Ready to scale your payment infrastructure? Explore Flutterwave's solutions or talk to a payments specialist about your company’s needs.

A Quick Guide to Developer Onboarding in v4

Demola Malomo — Fri, 23 Jan 2026 08:47:54 +0000

Getting started with a new platform should be smooth, quick, and friendly for developers. That’s what Flutterwave v4 is built to offer. In this guide, we’ll walk you through the updated onboarding flow using the v4 sandbox. Whether you're testing integrations or checking out key features, the sandbox gives you a safe space to build and try things out.

You’ll also see what the process looks like when you’re ready to move from testing to going live.

Let’s dive into the new experience, call out what’s changed, and help you get up and running on v4.

Creating an Account

Before v4, creating an account on Flutterwave meant filling in details like your business type, registration number, business name, and more. While this information is essential when you're ready to go live, it's usually easy to provide for businesses looking to integrate a payment gateway. However, it can be a roadblock for solo developers just trying to explore the product. Even developers working within organizations may find it a bit much when they’re only building a proof of concept.

To make things easier, we’ve separated the developer environment (sandbox) from the go-live setup. This change lets developers test features quickly without needing all the business details upfront.

To get started, head to the sandbox and sign up using your basic information.

Once you verify your email, a sandbox account will be created for you. It comes with your API credentials and webhook configurations, so you can jump right into building.

API Key Management

v4 uses OAuth 2.0, a more secure authorization mechanism that connects your application to our servers without exposing static API keys. Before accessing any of the v4 APIs, generate a token using the Client ID and Client Secret on your dashboard.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

You’ll get a response similar to this:

{
    "access_token": "eyJhbGciO...",
    "expires_in": 600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

In v3, you use API keys to access the APIs, which can be easily exploited if leaked. OAuth 2.0 uses access tokens with expiration times, making it much harder for unauthorized users to maintain long-term access.

Check out the authentication process to learn more about OAuth 2.0 best practices.

To get a glimpse of how the v4 API and sandbox can help you build a robust product, let’s explore the direct payout use case.

Sample v4 API Use Case: Transfer Orchestrator (Direct Transfer)

Consider this scenario: you’re building an internal finance tool for a growing logistics startup. At first, the finance team only needs to send payments occasionally. One salary here, a vendor payout there, maybe a refund to a partner.

Sending these payments in bulk would be overkill. What they really need is a simple, reliable way to send one payout at a time, without worrying about retries, duplicate payments, or manual bank transfers. This is where the Flutterwave’s Transfer Orchestrator comes in.

With Flutterwave’s Transfer Orchestrator, you can build an application that can intiate a single, direct payout to a bank account or wallet. Here’s how to use the Transfer Orchestrator for payment:

Create a Transfer Request

To initiate a transfer, use the orchestrator transfer endpoint to specify the recipients’ details and amounts to be transferred.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \
--data '{
    "action": "instant",
    "payment_instruction": {
    "source_currency": "NGN",
    "amount": {
        "applies_to": "destination_currency",
        "value": 50000
    },
    "recipient": {
        "bank": {
        "account_number": "0122333334",
        "code": "044"
        }
    },
    "destination_currency": "NGN"
    },
    "type": "bank",
    "reference": "574874568ufdgjhvbjhcdbchb"
    "narration": "internet installation payment"
}'

The key parameters to pay attention to when making a transfer are action and payment_instruction.

action controls when Flutterwave processes your transfer request. In the example above, it’s set to instant, which means the payment should be processed immediately. You can also choose to defer the transfer or schedule it for later.
payment_instruction tells Flutterwave how to handle your transfer. In the request above, it’s instructing Flutterwave to pay your recipient in NGN (destination_currency) from your NGN Flutterwave account (source_currency). You can also send international payments by specifying a different currency. Flutterwave will take care of the conversion and other operational details.

As a best practice, use Flutterwave’s Retrieve Bank and Bank Account Lookup endpoints to fetch the bank code and confirm account details before starting any payments.

You’ll get a response similar to this:

{
    "status": "success",
    "message": "transfer created successfully",
    "data": {
        "id": "btr_kz5sSNP8IrnRWQ",
        "type": "bank",
        "action": "instant",
        "status": "NEW",
        "created_datetime": "2026-01-24T11:09:44.193969884Z"
        "narration": "internet installation payment",
        "source_currency": "NGN",
        "destination_currency": "NGN",
        "amount": {
            "value": 50000,
            "applies_to": "destination_currency"
        },
    }
}

Monitor the Transfer Status

The last step is to check the transfer status to verify that the transaction has been completed successfully. You can use any of the following methods:

Webhook (Recommended): Flutterwave sends a webhook with the transaction status if you have webhooks enabled on your dashboard.

{
    "webhook_id":"wbk_yXvsB4LzWSwhUCpAPCBR",
    "timestamp":1739456704200,
    "type":"charge.completed",
    "data":{
        "id":"btr_kz5sSNP8IrnRWQ",
        .....
    }
}

Charge Endpoint: You can manually check the transfer status by sending a request to the retrieve a transfer endpoint at a specific interval.

curl --request GET \
--url 'https://developersandbox-api.flutterwave.com/transfers/{id}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You’ll get a response similar to this:

    {
    "status": "success",
    "message": "Charge updated",
    "data": {
        "id": "chg_zam88NgLb7",
        .....
    }
}

Moving to Live Mode

Once you're done testing your application and simulating transactions that match your use cases, you can follow the steps below to start accepting real payments:

1 Verify your Business

In v4, live mode is completely separate from the sandbox. To start accepting live transactions, you'll need to create an account and complete your Know Your Customer (KYC) verification process to access the live environment. This involves submitting required business documents such as a certificate of incorporation, proof of address, and valid identification. These documents are needed to meet regulatory and compliance requirements.

Depending on your region, you may also need to provide additional details like Nigeria’s Bank Verification Number (BVN) or local equivalents to show your business is legitimate.

2 Update your Credentials to Live Mode

Once your business is approved, you’ll receive production API credentials. Update your codebase to use the live Client ID and Client Secret. You need these credentials to generate an OAuth 2.0 token for accessing the API in production.

3 Activate Settlements and Webhook

Flutterwave needs an account to process and settle funds into when customers pay for your goods or services. You can choose to use your Flutterwave balance, which is a secure, built-in account linked to your profile, or you can use a business or personal bank account. If you choose to add a bank account, you’ll need to verify it to confirm ownership. Once verified, live transaction proceeds will be sent to the account automatically based on the settlement schedule.

We also recommend enabling and configuring webhooks from your Flutterwave dashboard. Webhooks help your application stay updated in real time by sending notifications whenever important events occur, such as a successful payment or failed transaction.

Other v4 API Improvements to Note

Beyond the dedicated sandbox and OAuth 2.0, we also shipped other meaningful improvements in v4. Here are a few key upgrades:

Improved Workflow

Better Developer Experience

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Invalid card number",
        "validation_errors": []
    }
}

v4 also supports more test cases via scenario keys. This mechanism allows you to simulate different payment scenarios with ease.

Scalability
API requests in v4 follow a consistent flow across all payment methods, which reduces technical overhead. You can create reusable helper functions across your codebase, making integrations more efficient and scalable.

Wrapping Up

You've walked through the essentials of setting up your Flutterwave v4 integration, from sandbox testing to going live. With your business verified, API keys configured, and webhooks secured, you’re all set to start accepting real payments with confidence.

Remember, the transition from sandbox to live mode is designed to be seamless. The API endpoints, request structures, and integration flows remain consistent, so there’s no need to rewrite your codebase when switching environments.

Before going live, double-check that:

Your business verification (KYC) is complete and approved.
Live API keys are correctly implemented in your environment.
Webhooks are secured with your secret hash, and signature validation is in place.
Settlement accounts are set up and verified.

If you encounter any issues, contact the support team for assistance.

Understanding Virtual Accounts with Flutterwave

Demola Malomo — Fri, 21 Nov 2025 09:13:31 +0000

If you’ve ever tried collecting payments from customers across different African countries, you know how tricky it can get, especially when dealing with local payments. Nigerians prefer bank transfers, Kenyans rely on M-Pesa, Ghanaians use Mobile Money, and South Africans lean toward cards or electronic fund transfers (EFTs). Even within a single country, customers still use different payment methods.

Africa’s complex payment ecosystem makes it hard for businesses to manage and reconcile incoming payments efficiently. That’s where virtual account management comes in. They simplify things by bringing all payment methods into one unified flow that’s easier to track and reconcile.

In this guide, you’ll learn what virtual accounts are, how they work, and how to integrate them into your application using Flutterwave.

What is a Virtual Account?

A virtual account is a unique bank account automatically generated for a specific customer or transaction. It allows businesses to send, receive, and hold money online, which makes the reconciliation process simple. Behind the scenes, all payments made to these generated accounts go into one primary account that you control. It’s like giving every customer their own unique bank account number, while all the funds still flow into your main account.

Once customers transfer money into their assigned virtual accounts, your system receives an instant webhook notification from Flutterwave. You can then automatically confirm the payment and process their order. No manual tracking is needed.

There are two main types of Flutterwave virtual accounts:

Static Virtual Accounts: These accounts are permanently tied to a specific customer. They are perfect for businesses that need to track payments per customer, such as wallet top-ups or recurring payments.
Dynamic Virtual Accounts: These are temporary accounts created for one-time transactions. They expire after a short period and work best for time-sensitive payments such as e-commerce checkouts or invoice payments.

Benefits of Virtual Accounts

Now that we’ve covered what virtual accounts are, let’s look at the value they bring to your payment operations:

Simplified Reconciliation: Unlike physical accounts, virtual accounts make it easy to track who made a payment. Each customer or order gets its own account, so when money comes in, you immediately know the source without manually matching transactions or dealing with confusing references.
Cost Efficiency: Instead of opening multiple bank accounts for different customers or regions, you can generate thousands of virtual accounts under one main account. It is cheaper, cleaner, and removes the hassle of managing traditional bank accounts.
Better Customer Experience: Customers get a unique virtual account number just for them, so they do not need to type reference codes or send payment screenshots. The payment is automatically confirmed, which builds trust and reduces confusion.
Manage Multiple Currencies: Virtual accounts support cash flows with multiple currencies, including NGN and GHS. This account structure allows customers to pay in their local currency, while you can choose to settle in your preferred currency.

How Do Virtual Accounts Work with Flutterwave?

The following overview explains the process behind how Flutterwave manages and operates virtual accounts:

Create a Virtual Account: The process starts with you creating a virtual account for a customer. This account is tied to their personal details such as name, email, and phone number.
Customer Makes a Payment: You display the generated account details (virtual bank account name and account number) at checkout or on any payment channel so the customer can transfer funds using their preferred payment method.
Payment Receipt: Once the transfer is complete, the payment is detected and credited to your Flutterwave balance.
Webhook Notification: Flutterwave sends a webhook notification to your server with complete payment details, including who paid, how much, when, and which virtual account received the payment.
Process the Payment: After confirming the payment, your system can automatically update the customer’s balance, mark an invoice as paid, or trigger delivery, depending on your workflow.

See how merchants like PiggyVest use Flutterwave to boost growth and customer adoption. Watch their story below:

How to Set Up Virtual Accounts with Flutterwave

Before you start implementing virtual accounts, make sure you have the following in place:

Verified Flutterwave Account: Complete your KYC verification. This usually involves providing your business registration documents and bank details so Flutterwave can process settlements.
API Credentials: You need your Flutterwave secret key for backend operations. Always keep your keys secure and never expose them in client-side code.
Webhook Endpoint: Set up a secure server endpoint to receive notifications from Flutterwave about transactions, failed charges, and other events.

To implement virtual accounts, follow the steps below:

Note: This implementation uses the Flutterwave v3 API.

Step 1: Create a Virtual Account

Depending on your use case, you can create either a dynamic or static virtual account.

To create a dynamic NGN virtual account, send a POST request to the create virtual account endpoint with the customer’s details and amount:

curl --request POST 'https://api.flutterwave.com/v3/virtual-account-numbers' \
  --header 'Authorization: Bearer FLW_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email":"john.doe@example.com",
    "amount": 1000,
    "currency": "NGN",
    "tx_ref": "apex_tx-002201",
    "is_permanent": false,
    "phonenumber":"08100000000",
    "firstname":"John",
    "lastname":"Doe",
    "narration":"virtual account test"
}'

For a static virtual account, the request is slightly different. You need to include the customer’s Bank Verification Number (BVN) or National Identification Number (NIN) and set the is_permanent flag to true.

curl --request POST 'https://api.flutterwave.com/v3/virtual-account-numbers' \
  --header 'Authorization: Bearer FLW_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email":"john.doe@example.com",
    "tx_ref":"apex_tx_ref-002201",
    "phonenumber":"08100000000",
    "is_permanent": true,
    "currency": "NGN",
    "firstname":"John",
    "lastname":"Doe",
    "narration":"virtual account test",
    "bvn": "1234567890"
}'

Check out the virtual accounts documentation to learn more about supported countries and available parameters for customizing the account.

Once the request is successful, you’ll receive a response containing a unique account number and the bank name where the customer can send funds.

{
    "status": "success",
    "message": "Virtual account created",
    "data": {
        "response_code": "02",
        "response_message": "Transaction in progress",
        "flw_ref": "FLW-211b4eea7b3d465d8797fa354c127f79",
        "order_ref": "URF_1726608838391_595235",
        "account_number": "8548497837",
        "frequency": "N/A",
        "bank_name": "WEMA BANK",
        "created_at": "2024-09-17 21:33:58",
        "expiry_date": "N/A",
        "note": "Please make a bank transfer to testing functions",
        "amount": "1000"
    }
}

For a dynamic virtual account, the response includes an expiry_date, which captures the time the virtual account expires. It is valid for one hour.

Step 2: Display the Virtual Account to the Customer

Once you receive the generated account details, update your user interface to show the bank name, account number, amount, and any other information the customer needs to complete the transfer.

Step 3: Handle Webhook Notifications

When a customer makes a payment to their virtual account, Flutterwave sends a webhook notification to the URL you configured. Always verify the event and payment status before providing value or updating the customer’s balance.

A sample webhook payload looks like this:

{
  "event": "charge.completed",
  "data": {
    "id": 1549596704,
    "tx_ref": "apex_tx_ref-002201",
    "flw_ref": "000030240917214228820592962026",
    "device_fingerprint": "N/A",
    "amount": 100,
    "currency": "NGN",
    "charged_amount": 101.4,
    "app_fee": 1.4,
    "merchant_fee": 0,
    "processor_response": "success",
    "auth_model": "AUTH",
    "ip": "::ffff:172.16.85.133",
    "narration": "Kids Foundation",
    "status": "successful",
    "payment_type": "bank_transfer",
    "created_at": "2024-09-17T20:47:20.000Z",
    "account_id": 47337,
    "customer": {
      "id": 980070204,
      "name": "Flutterwave Developers",
      "phone_number": "08100000000",
      "email": "abraham@flutterwavego.com",
      "created_at": "2024-09-17T20:38:43.000Z"
    }
  },
  "event.type": "BANK_TRANSFER_TRANSACTION"
}

With what virtual accounts are, their types, and how to implement them now covered, let’s look at a few key points to help you build a reliable system.

Best Practices for Virtual Accounts

When creating virtual accounts for your customers, it’s important to follow these best practices:

Give Each Customer a Unique Account: Avoid reusing virtual account numbers. Each customer should have a unique account number that stays permanently tied to them. This removes confusion and makes reconciliation straightforward.
Store Account Data Securely: Encrypt sensitive details before saving them to your database. Treat virtual account information with the same level of security as payment card data.
Use Webhooks Reliably: Always validate webhook payloads using your Flutterwave secret hash to prevent spoofing. Add idempotency so that if Flutterwave retries a webhook, your system does not double-credit a customer.
Handle Failed or Delayed Payments Gracefully: Network issues or user mistakes can happen. Include a fallback check that queries the Flutterwave transaction verification endpoint when webhooks fail.
Clean Up Temporary Accounts: If you use dynamic accounts, regularly deactivate or remove expired ones to keep your system organized. Keep logs of failed account creation attempts so you can spot patterns and work with Flutterwave support when needed.
Communicate Clearly with Customers: Do not assume customers already understand virtual accounts. When showing payment details, include simple, step-by-step instructions such as: “Transfer the exact amount to this account number using your bank’s mobile app, internet banking, or by visiting any bank branch.” Always show the bank name clearly since customers need it to complete their transfer.

Wrapping Up

Virtual accounts give businesses a scalable and automated way to collect payments across borders, especially in regions like Africa, where bank transfers are still the most common digital payment method. They remove the hassle of manual reconciliation while offering customers a familiar and seamless payment experience.

With Flutterwave, setting up virtual accounts is fully API-driven, which makes it ideal for developers who want a fast and reliable integration. The combination of permanent accounts for recurring payments and temporary accounts for one-time transactions gives you the flexibility to handle almost any payment scenario. Whether you’re building a subscription service, a marketplace, a wallet app, or an invoicing system, virtual accounts can streamline your entire payment process.

Ready to start building smarter payment experiences with Flutterwave virtual accounts? Create an account now.

Implementing Card on File for Your App: A Developer’s Guide

Demola Malomo — Fri, 14 Nov 2025 08:47:14 +0000

Think about the last time you subscribed to a cloud platform, ordered food, or booked a ride. Chances are, you didn’t pull out your wallet to pay with cash or enter your card details each time. Your card was probably already saved in the app, making the experience fast, smooth, and effortless. That’s the power of Card on File in streamlining payment processing.

Card on File is a game-changer for developers and product teams building consumer-facing products and services. It transforms the user experience by reducing checkout time, keeping customers engaged, and securely managing customer payment information for recurring payments with credit and debit cards.

In this guide, you’ll learn what Card on File really means, how it works, and how to implement it in your application using Flutterwave.

What Are Card on File Transactions?

Card on File transactions are payments where a user allows a merchant or service provider to securely store their card details for future use. Instead of entering the customer’s card details every single time, the user gives permission once, and future transactions can happen with just a click or even automatically.

In Card on File transactions, you don’t store the actual card details in your database (that could lead to serious compliance issues). The stored payment information is converted into a secure token that can be used for future payments.

Here are a few everyday use cases where Card on File shines:

Ride-sharing and delivery apps like Uber and GIG Logistics save payment information so customers can request rides or order food with a single tap.
Subscription services such as Netflix charge users monthly without asking them to re-enter their card details. Customers sign up once, and billing happens automatically in the background.
E-commerce platforms like Jumia and Konga offer a “Save my card for future purchases” option that makes checkout faster and smoother.
Utility and bill payment apps automatically charge users for recurring services like electricity, internet, or phone bills without requiring manual payment each billing cycle. ## How Does Card on File Work?

At its core, Card on File payments operate through a combination of user authorization, tokenization, and secure storage. These processes can be grouped into two main transaction types:

Customer-Initiated Transactions (CIT)

In a Customer-Initiated Transaction, the payment is triggered manually by the user. This could happen during the initial setup when a user adds their card details for the first time, or later when they choose to make a payment for a service using a saved card.

The workflow involves:

User Authorization: The process starts when a customer visits your checkout page and chooses to save their card payment details for future use. They enter their card details and may need to complete a 3D Secure authentication, depending on their bank’s requirements.
Tokenization: Instead of storing the raw card number, the payment provider generates a token that represents the card. This token is a random string that has no value outside your integration with the payment provider.
Token Storage: You store the token in your database alongside the user’s profile. You can also store non-sensitive metadata like the card’s last four digits, expiry date, and brand (Visa, Mastercard, etc.) to help users identify their saved credit and debit cards.
Future Transactions: When the user makes another purchase with a saved card, you send the token to the payment provider instead of collecting card details again. For high-value transactions, the user might still need to authenticate, but the overall friction is greatly reduced.

Merchant-Initiated Transactions (MIT)

In a Merchant-Initiated Transaction, you charge the customer without them actively triggering that specific payment. This model is common for recurring billing, subscriptions, and installment payments.

The workflow involves:

Initial Authorization: The process begins when a customer explicitly consents to future charges by saving their card during a transaction. This consent is both legally and technically required because you cannot charge a card without prior approval.
Tokenization and Storage: The process is identical to CIT. You receive and store a token representing the card.
Scheduled Charges: When a payment is due (for example, the first of every month for a subscription), your backend automatically sends a charge request to the payment gateway using the stored token that represents the customer’s credit card details. No user interaction is required.
Reduced Authentication: After the initial setup, MIT transactions bypass 3D Secure authentication because the user has already authorized recurring charges. This makes the process smooth but requires strict compliance with card network and payment regulations.

CIT vs. MIT: The Key Difference

In a CIT, the user starts the payment. For example, tapping “Buy Now” in an app using a saved card. In a MIT, the business starts the payment. For example, when a subscription renews automatically.

Both rely on the initial debit or credit Card on File setup but differ in who triggers the transaction. CIT keeps the user in control for each payment, while MIT allows you to handle billing automatically after getting the user’s initial consent.

How to Implement Card on File with Flutterwave

Before you start implementing Card on File, there are a few prerequisites to put in place:

Flutterwave Account with Card on File Access: Card on File is not available by default on all Flutterwave accounts. You need to request access because of the security requirements and sensitivity of the feature. Once approved, you will receive an agreement_id you can use to process Card on File transactions.
API Credentials: You need your Flutterwave secret key and encryption key for backend operations. Keep your keys secure and never expose them in client-side code.
Secure Backend Setup: Since you will store tokens alongside user profiles and manage sensitive payment flows, your backend must be secured with proper authentication and database protections.
Clear Customer Consent Flows: You cannot store a card without permission. Provide a clear interface where users explicitly agree to save their card details, for example, a checkbox at checkout with plain language explaining how their card will be stored and used.
Webhook Endpoint: Set up an endpoint to receive notifications from Flutterwave about transaction statuses, failed charges, or card updates.

To implement Card on File, follow the steps below.

Note: This implementation uses the Flutterwave v3 API.

Step 1: Collect and Tokenize the Card

When a user chooses to save their card, you’ll start a standard card payment but mark it for tokenization. On the frontend, display a checkout form where users can enter their card details and opt in to save the card.

On the backend, encrypt the payload using the 3DES algorithm before sending it to the charge endpoint:

const payload = {
    card_number: '340614670471041',
    cvv: '564',
    expiry_month: '10',
    expiry_year: '31',
    currency: 'NGN',
    amount: '2000',
    email: 'user@example.com',
    fullname: 'John Doe',
    phone_number: '0167578999',
    card_holder_name: 'John Doe',
    tx_ref: 'SAMPLE_UNIQUE_REFERENCE',
    redirect_url: 'https://webhook.site/88ba45d2-ae79-4a5b-ae07-48303a32a92e',
    is_unscheduled: true,
    agreement_id: 'YOUR_AGREEMENT_ID',
};

const encryptionKey = process.env.ENCRYPTION_KEY;

function encrypt(encryptionKey, payload) {
    const text = JSON.stringify(payload);
    const forge = require('node-forge');
    const cipher = forge.cipher.createCipher(
        '3DES-ECB',
        forge.util.createBuffer(encryptionKey)
    );
    cipher.start({ iv: '' });
    cipher.update(forge.util.createBuffer(text, 'utf-8'));
    cipher.finish();
    const encrypted = cipher.output;
    return forge.util.encode64(encrypted.getBytes());
}

Two parameters to note in the payload are is_unscheduled and agreement_id. Including these tells Flutterwave to process the charge as a Card on File transaction.

Next, wrap the encrypted payload in a client key and send it to the charge card endpoint.

curl --request POST \
  --url "https://api.flutterwave.com/v3/charges?type=card" \
  --header "Authorization: Bearer FLW_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "client": "Of8p6iJUVUezgvjUkjjJsP8aPd6CjHR3f9ptHiH5Q0+2h/FzHA/X1zPlDmRmH5v+GoLWWB4TqEojrKhZI38MSjbGm3DC8UPf385zBYEHZdgvQDsacDYZtFEruJqEWXmbvw9sUz+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+fxFl4tauG9H4WBChF0agXtP4kjfhfYVD48N9Hrt"
  }'

When the charge is successful, Card on File triggers a 3D Secure process. This step redirects the customer to their bank’s authentication page for verification. It adds an extra layer of protection to confirm the customer’s identity and reduce fraud.

After this step, Flutterwave responds with:

A card object containing the tokenized card
A customer object with user details
A meta object that includes a trace_id used for future charges

{
  card: {
      first_6digits: '543889',
      last_4digits: '0229',
      issuer: 'MASTERCARD GT BANK',
      country: 'NG',
      type: 'MASTERCARD',
      token: 'flw-t1nf-1dd5c21361bb85c64deb7ff57ec891b2-m03k',
      expiry: '10/31',
  },
  meta: {
      agreement_id: 'Agreement00w02W1',
      recurring_amount_variability: 'VARIABLE',
      trace_id: '123456789',
      agreement_type: 'UNSCHEDULED',
  },
  customer: {
      id: 370672,
      phone_number: '2349012345678',
      name: 'John Doe',
      email: 'john.doe@example.com',
      created_at: '2020-04-30T20:09:56.000Z',
  },
}

You should store these details securely in your backend and link them to the user’s profile. They can also be used to display card information such as type, last four digits, and expiry date within your app.

Step 2: Charge the Saved Card (Subsequent Charge)

When it's time to charge the saved card, whether the user initiates it or you're processing a scheduled payment, use the stored token and the trace_id alongside other required details to make the request.

curl --request POST \
  --url "https://api.flutterwave.com/v3/tokenized-charges" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer FLW_SECRET_KEY" \
  --data '{
    "token": "flw-t1nf-1dd5c21361bb85c64deb7ff57ec891b2-m03k",
    "currency": "NGN",
    "country": "NG",
    "amount": 2000,
    "email": "john.doe@example.com",
    "full_name": "Flutterwave Developers",
    "tx_ref": "UNIQUE_PAYMENT_REFERENCE",
    "redirect_url": "https://example_company.com/success",
    "trace_id": "123456789",
    "is_unscheduled": true
  }'

Note that for subscription billing, you would typically set up a cron job or scheduled task that runs at specific intervals to trigger these charges automatically.

Step 3: Manage the Card Lifecycle

Cards don’t last forever. They expire, get replaced, or users may want to remove them. Your implementation needs to handle these situations gracefully. Below are some scenarios to plan for:

Handling card updates: When a user’s card is updated (for example, a new expiry date or CVV), allow them to re-authenticate and generate a new token by following the same steps outlined earlier. You can keep the old token reference but mark it as superseded.
Handling card expiry: Before attempting to charge a card, check the expiry date stored in your database to confirm that it’s still valid.
Handling user revocation: Users should be able to remove their saved cards at any time. When they do, mark the token as revoked, but don’t delete the record immediately since you might need it for audit purposes.
Handling failed charges: When a Merchant-Initiated Transaction fails, have a clear retry and communication strategy. Notify users about the failed attempt and consider a backoff or scheduled retry mechanism. You can learn more about this in the guide on building a fault-tolerant microservice.

Step 4: Set Up Webhooks for Transaction Updates

Webhooks let Flutterwave notify your system about transaction events in real time. This is especially important for Merchant-Initiated Transactions since your system might not be actively polling for results.

Here’s an example implementation:

app.post('/webhooks/flutterwave', async (req, res) => {
  // Verify the webhook signature
  const signature = req.headers['verif-hash'];
  if (signature !== process.env.FLUTTERWAVE_WEBHOOK_SECRET) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  if (event.event === 'charge.completed') {
    const { status, tx_ref, customer } = event.data;

    // Update your records based on the transaction status
    if (status === 'successful') {
      await handleSuccessfulPayment(tx_ref, event.data);
    } else {
      await handleFailedPayment(tx_ref, event.data);
    }
  }

  res.status(200).send('Webhook received');
});

Once an event occurs on your account, Flutterwave will automatically send a webhook notification to your server so you can handle it accordingly.

Check out the webhook guide to learn more about building a robust and secure webhook service.

Wrap Up

Implementing Card on File is not just about reducing checkout friction. It’s about creating a modern, smooth payment experience that online retailers and customers expect. From recurring subscriptions to one-click checkouts, Card on File makes your app more user-friendly and can significantly improve conversion rates.

With Flutterwave, developers have a secure and reliable way to integrate Card on File without having to rebuild complex payment flows. The tokenization process protects sensitive data, while your backend handles customer relationships and card lifecycles.

If you’re ready to enhance your app’s payment experience, reach out to the Flutterwave team to activate Card on File and start building faster, more seamless payments today.