Forem: Flutterwave Engineering

Financial Integration in Africa: What Developers Need To Build For

uma victor — Fri, 10 Apr 2026 14:28:16 +0000

You just shipped a payment integration in Nigeria. Nigeria Inter-Bank Payment (NIP) bank transfers work, your webhook handler is solid, and transactions are settling same-day. Then your product team says: "We're expanding to Kenya and Ghana next quarter."

Suddenly, your NIP-specific code is useless in Nairobi, where M-Pesa processes the majority of consumer payments through a completely different API model. Your KYC flow, built around Nigeria's BVN, doesn't map to Kenya's IPRS or Ghana's mandatory Ghana Card verification. And your single-currency ledger now needs to handle three currencies with different FX volatility profiles.

This is the structural challenge of building across African payment systems. The continent runs 36 instant payment systems across 31 countries, processes nearly $2 trillion in instant payments annually, and operates 42 distinct currencies. There is no single "African payment rail." There are dozens of parallel financial ecosystems shaped by regulation, telecom infrastructure, banking penetration, and currency policy.

This article gives you the concrete patterns to handle that complexity. By the end, you'll understand the five payment rail categories operating across the continent, know how to design a routing layer and adapter pattern that scales across markets, and have a clear picture of how compliance, settlement, and FX vary from country to country.

The Five Payment Rail Categories You Need To Support

Across Africa's major markets, payment infrastructure is not built on a single dominant rail. Most countries operate multiple parallel systems, and production-grade platforms must support several simultaneously.

Five rail categories carry the bulk of transaction volume across the continent. Here's what each one demands from your system.

1. Instant Payment Systems

Instant payment systems are interoperable rails that move funds between accounts in real time, whether those accounts sit in banks, mobile money wallets, or fintech platforms. Across Africa's largest markets, these systems carry the highest share of digital transaction volume, which means your integration will almost certainly touch one.

Africa now has 36 live instant payment systems spanning 31 countries, up from 31 systems a year earlier. These processed 64 billion transactions worth $1.98 trillion in 2024 (AfricaNenda SIIPS 2025). Nigeria Inter-Bank Payment System (NIP) alone handled over 11.2 billion transactions in 2024, making it one of the largest real-time payment systems globally.

Developer Considerations
Despite the "instant" label, confirmations are asynchronous. NIP uses deferred net settlement through the RTGS system. South Africa's PayShap enforces a 10-second maximum processing window but settles in batches through the SAMOS system multiple times per day.

When you're building against these rails, three things need to be in your integration from day one:

Idempotency keys on every request to prevent duplicate charges.
Adaptive timeout logic, because response times vary from near-instant to 30 seconds depending on the bank.
Provider-specific error handling, since error codes aren't standardized across banks.

2. Mobile Money

Mobile money lets users store, send, and receive funds through their phone, no bank account needed. Transactions happen via USSD codes, SIM toolkit menus, or provider apps, and agent networks handle cash-in and cash-out. In East and parts of West Africa, mobile money is the primary financial interface, which means if you skip this rail, you're locking out the majority of your potential users.

Sub-Saharan Africa has over 1.1 billion registered mobile money accounts, more than half of all registered accounts globally, processing $1.1 trillion annually (GSMA 2025). M-Pesa dominates Kenya with over 40 million monthly active users. MTN MoMo operates across 14 African countries with 69.5 million active users as of 2025. In East and parts of West Africa, mobile money is the primary financial interface.

Developer Considerations
Your integration architecture needs to account for how these providers work from the start. Mobile money APIs follow a webhook/callback pattern, you register confirmation URLs, and the provider POSTs results asynchronously. M-Pesa's Daraja API uses OAuth 2.0 authentication and is designed to handle high-volume payments at scale. MTN MoMo's Open API covers Collections, Disbursements, and Remittances, each with its own set of endpoints for initiating, confirming, and managing transactions. But the async nature creates three challenges you won't hit with instant bank rails:

Latency is unpredictable as a confirmation might take two seconds or 45 seconds.
Providers downtime is common and rarely announced in advance, so your system needs graceful degradation per provider.
Batch settlement means your reconciliation logic has to tolerate a gap between "transaction confirmed" and "funds actually settled."

3. Card Payments

In Nigeria, Interswitch's domestic scheme, Verve, dominates the card market with over 100 million cards issued across Africa and roughly 70% domestic market share, driven by Naira devaluation making FX-denominated card scheme fees uneconomical for most issuers.

Developer Considerations
When you're integrating card payments across these markets, your payment flow logic needs to handle scheme-level differences from the start. Pre-authorization versus capture flows work differently between Verve, Mastercard, and Visa, so you can't assume one flow fits all three.

Chargeback response windows are tight and vary by card scheme and transaction type. Flutterwave's dispute resolution flow requires rapid merchant responses, which means your dispute handling pipeline needs to be automated, not manual. And 3D Secure enforcement can significantly reduce payment success rates, particularly on cards issued by banks with poor 3DS infrastructure. Your system needs to distinguish between soft declines (retry-eligible) and hard declines (terminal) to avoid throwing away transactions you could have recovered.

4. USSD

USSD still accounts for 63.5% of total mobile money transaction volume in Africa (Market Data Forecast, 2024), rising to 89% in the WAEMU region. It works on any GSM phone without internet, making it the most reliable channel reaching populations where smartphone penetration stays extremely low.

Developer Considerations
If you're building a USSD payment flow, the constraints shape your UX from the first screen. Sessions typically timeout within 120 to 180 seconds, depending on the operator, with inactivity limits as short as 20 seconds on some networks. So every unnecessary step is a risk of losing the user. Messages are capped at around 160 characters, which means your prompts need to be short and unambiguous. Best practice is five steps or fewer per complete transaction. Dropped sessions are common, so your system needs fallback logic that can resume or safely cancel an incomplete transaction without double-charging.

5. Stablecoins

Stablecoins now represent 43% of all crypto transaction volume in Sub-Saharan Africa. Nigeria alone processed nearly $22 billion in stablecoin transactions between July 2023 and June 2024. Flutterwave's partnership with Polygon Labs (announced October 2025) makes Polygon the default blockchain for cross-border stablecoin payments across 30+ African markets.

Developer Considerations
Three architectural decisions need to be locked down before you write a line of stablecoin integration code. First, custody: Are you holding wallets on behalf of users, or are they connecting their own? This affects your licensing requirements in every market. Second, on-chain confirmation logic: You need to define how many block confirmations your system waits for before treating a transaction as final, and that threshold differs by chain. Third, reconciliation: Your internal ledger and the blockchain will drift, so you need a process that treats on-chain state as the source of truth and continuously reconciles against it.

The regulatory picture also changes your implementation per market. South Africa's FSCA has been processing CASP license applications since 2023. Nigeria passed the ISA 2025, classifying digital assets as securities. Kenya's VASP Act was signed into law in October 2025. Ghana enacted VASP Act 1154 in December 2025. Because these frameworks are still evolving, your stablecoin support should be modular, a feature flag you can toggle per country, not logic baked into your core payment flow.

For a deeper walkthrough on how to add stablecoin settlement without rewriting your existing architecture, see How Teams Integrate Stablecoin Rails Without Rewriting Their Platform.

Architectural Patterns For Multi-Market Systems

Knowing the different payment rails matters, but system design is what determines whether you rewrite your codebase every time you add a country. Two patterns do most of the heavy lifting: a routing layer that selects the right rail per market, and an adapter pattern that isolates each provider's requirements behind a shared interface.

Pattern 1: Payment Routing Layer
Your routing layer detects the market, selects valid payment methods, and routes to the right provider. Here's a simplified routing example in TypeScript:

interface PaymentRequest {
  amount: number;
  currency: string;
  country: string;
  preferredMethod?: string;
}

interface RouteResult {
  provider: string;
  method: string;
  endpoint: string;
}

function routePayment(req: PaymentRequest): RouteResult {
  const routes: Record<string, Record<string, RouteResult>> = {
    NG: {
      bank_transfer: {
        provider: "flutterwave",
        method: "banktransfer",
        endpoint: "/v3/charges?type=bank_transfer",
      },
      card: {
        provider: "flutterwave",
        method: "card",
        endpoint: "/v3/charges",
      }, // Card charges require 3DES encryption;
      ussd: {
        provider: "flutterwave",
        method: "ussd",
        endpoint: "/v3/charges?type=ussd",
      },
    },
    KE: {
      mpesa: {
        provider: "flutterwave",
        method: "mpesa",
        endpoint: "/v3/charges?type=mpesa",
      },
      card: {
        provider: "flutterwave",
        method: "card",
        endpoint: "/v3/charges",
      },
    },
    GH: {
      mobile_money: {
        provider: "flutterwave",
        method: "mobile_money_ghana",
        endpoint: "/v3/charges?type=mobile_money_ghana",
      },
      card: {
        provider: "flutterwave",
        method: "card",
        endpoint: "/v3/charges",
      },
    },
  };

  const countryRoutes = routes[req.country];
  if (!countryRoutes) throw new Error(`Unsupported market: ${req.country}`);

  const method = req.preferredMethod ?? Object.keys(countryRoutes)[0];
  return countryRoutes[method];
}

The key insight here is that routing and orchestration are core layers, not extensions you bolt on later. When you add South Africa or Francophone West Africa, you add configuration, not code paths.

Pattern 2: Adapter Pattern For Provider Abstraction
Each rail has its own authentication model, request format, and callback structure. An adapter pattern gives you a shared interface with market-specific implementations. Here's the structure in TypeScript:

interface PaymentAdapter {
  charge(params: ChargeParams): Promise<ChargeResponse>;
  verify(reference: string): Promise<VerificationResponse>;
  handleWebhook(payload: unknown): Promise<WebhookResult>;
}

class MpesaAdapter implements PaymentAdapter {
  async charge(params: ChargeParams): Promise<ChargeResponse> {
    // M-Pesa charge via Flutterwave /v3/charges?type=mpesa
    // Flutterwave handles STK Push orchestration and callback routing
    // Settlement: batch, varies by transaction type
  }
  // ...
}

class NigeriaBankTransferAdapter implements PaymentAdapter {
  async charge(params: ChargeParams): Promise<ChargeResponse> {
    // NIP transfer via Flutterwave, immediate confirmation expected
  }
  // ...
}

class GhanaMobileMoneyAdapter implements PaymentAdapter {
  async charge(params: ChargeParams): Promise<ChargeResponse> {
    // Ghana mobile money charge via Flutterwave /v3/charges?type=mobile_money_ghana
    // Webhook-driven confirmation, Flutterwave handles provider routing
    // Settlement: batch, provider-dependent timing
  }
  // ...
}

This pattern prevents duplication across 36 different payment system APIs. When BCEAO's PI-SPI system goes live across eight WAEMU countries, you add one adapter. Your business logic stays untouched.

Compliance, Settlement, and Multi-Currency Operations

Getting the rails and routing right is half the problem. The other half is everything that wraps around the transaction: identity verification that varies by country, settlement timelines that don't behave the same way across rails, and currency conversion logic that can destroy your margins if you treat it as an afterthought. Each of these needs to be a first-class concern in your architecture. Here's what that looks like in practice for identity verification, settlement timing, and currency conversion.

KYC Is Different in Every Market
The identity verification your system requires changes completely between markets. Nigeria uses BVN and/or NIN, with a tiered system that governs what transaction limits each verification level unlocks. Kenya routes through the IPRS, and if you're integrating with Safaricom's ecosystem, identity checks tie into the Daraja API. Ghana has mandated the Ghana Card (Ghanacard) as the primary form of identification, with the National Identification Authority phasing out other ID types for official transactions. South Africa operates under FICA, with CASP classification adding a separate layer for crypto service providers.

The practical move is to build a compliance decision engine that routes to market-specific validation rules rather than hardcoding KYC flows into onboarding logic. Each market's identity provider becomes an adapter, just like your payment rails.

Settlement Timing Is Not Uniform
NIP settles through deferred net, but confirmation is near-instant. M-Pesa wallet-to-wallet is instant, but B2C disbursements may be delayed. Cards settle T+1 domestically, with chargeback exposure lasting months. Stablecoins confirm on-chain in seconds, but full on/off-ramp flows take longer.

Your internal ledger must model settlement states explicitly: pending, confirmed, final, and reversible. If your product logic assumes instant finality everywhere, it will break the moment you cross a market boundary.

Africa Runs On 42 Currencies
Africa operates forty-two distinct currencies across 54 countries, with two CFA franc zones (14 countries) and the Rand Monetary Area providing the only real shared-currency pockets. Most African currency pairs must route through USD or EUR as intermediaries, adding conversion layers and cost. Sending money to Sub-Saharan Africa remains the most expensive corridor globally, with average costs at 8.78% as of Q1 2025 according to the World Bank's Remittance Prices Worldwide database.

Build FX quoting, rate locking, and conversion timing into your core domain model from day one. This is not a feature to add later. Nigeria's Naira alone fell from roughly ₦460 to over ₦1,700 per US dollar in the months following the June 2023 FX unification. The rate has since partially recovered but remains volatile, trading around ₦1,384 as of early 2026.

Design Principles For Multi-Market Africa Payment Systems

Six principles that hold up no matter which market you add next.

Design for rail plurality, not rail preference: In Nigeria, instant bank transfers dominate. In Kenya, it's mobile money. In South Africa, cards. Your routing and orchestration layers must be core infrastructure, not add-ons.

Treat compliance as programmable infrastructure: BVN is not IPRS, is not Ghana Card, is not FICA. Build a rule-based compliance engine with extensible identity provider adapters.

Abstract settlement timing from product logic: Model pending, confirmed, final, and reversible states. Never assume uniform finality.

Keep rail-specific logic isolated: Market logic belongs in adapters, routing rules, and compliance modules, not in business logic. This is the difference between adding a country in a week versus rewriting your payment system every six months.

Plan for uneven infrastructure quality: Payment success rates vary widely across African markets, depending on method and provider. Build circuit breakers per market and provider. Use exponential backoff for retries. Always re-verify transactions through the verification endpoint rather than trusting a single webhook delivery.

Separate your ledger from provider state: Your internal ledger must be canonical and independent of any provider's API. Reconcile, don't depend. A single webhook is never the final truth.

Building Once, Scaling Across Markets

Africa's payment infrastructure keeps adding layers. PAPSS now connects 19 countries for cross-border clearing, half of all instant payment systems support cross-domain interoperability (AfricaNenda SIIPS 2025), and mobile money providers are pushing into cards, savings, and cross-border transfers. Stablecoins are emerging as corridor-specific rails for B2B and remittance flows. For your system, that means the surface area you need to cover is only growing.

The next time your product team says, "We're adding Kenya next quarter," your answer isn't a rewrite. It's a new adapter, a routing rule, and a compliance config.

Platforms like Flutterwave already abstract much of this complexity. A single API call handles M-Pesa in Kenya, bank transfers in Nigeria, and mobile money in Ghana, without separate integrations per rail. Whether you build direct integrations or work through a unified API, the architectural discipline is the same: route dynamically, abstract aggressively, isolate market logic, and never assume any two countries work the same way.

Africa payment systems reward builders who treat fragmentation as a design constraint, not a problem to solve.

Go Deeper

For a walkthrough on adding stablecoin settlement without rewriting your existing stack, read How Teams Integrate Stablecoin Rails Without Rewriting Their Platform.
To build cross-border payments across Nigeria, Kenya, and Ghana in a single codebase, see Setting Up Cross-Border Payments in a Single Codebase.
Explore the Flutterwave developer documentation to see how routing, settlement, and multi-currency work across 34+ countries.

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.

On-Chain vs. Off-Chain Payments: What's Best for Your System

uma victor — Fri, 27 Mar 2026 09:27:05 +0000

You're building a payment platform that needs to handle cross-border settlements for merchants in Lagos and Nairobi. A $10,000 B2B payment through traditional correspondent banking costs $25–$100+ in direct fees, plus FX markups that can add another 2–5% on African corridors. It takes three to five business days. Send that same payment on-chain as USDC, and it costs under $0.10 and confirms in seconds.

But here's the catch: That Layer-2 network processes roughly 1,000 transactions per second in practice. A single tuned PostgreSQL instance handles 70,000+. For high-volume payment processing, you can't put every transaction on-chain. Do you go on-chain, off-chain, or both?

If you've been wrestling with this question, you're asking the wrong one. The on-chain vs. off-chain debate misses the point. The better question is: Which parts of your payment flow benefit from blockchain finality, and which parts need database speed?

This guide is for engineering leads and payment architects evaluating whether to add blockchain settlement to their payment stack. It covers cost and performance tradeoffs, when blockchain settlement adds value, hybrid architecture patterns, and a decision framework for your specific payment flows.

Why the On-Chain vs. Off-Chain Debate Misses the Point

Most content about on-chain vs. off-chain transactions falls into two camps. Crypto-native content claims everything should be on-chain for transparency and decentralization. Traditional fintech content dismisses blockchain entirely because databases are faster and cheaper. Both positions miss the point.

Here's what they get wrong: Traditional payments already use hybrid architecture. When you swipe a card at a store, Visa authorizes the transaction in real-time, in under one second. But actual settlement happens in daily batch cycles where net obligations between issuing and acquiring banks are calculated and transferred. Millions of off-chain transactions roll up into periodic settlements.

The practical question isn't on-chain vs. off-chain. It's which payment flows need public finality, counterparty trust, or cross-border settlement, and which need speed, privacy, or cost optimization.

You have three architecture patterns to choose from. Pure off-chain uses traditional database-based processing. Pure on-chain puts every transaction on the blockchain. Hybrid combines off-chain processing with periodic on-chain settlement. Most production payment systems that interact with blockchain use a hybrid approach.

If you're building cross-border payment infrastructure, understanding this distinction matters for every technical decision.

Understanding On-Chain Payments

When a payment happens on-chain, the transaction gets recorded on a public blockchain like Ethereum or Polygon. Network validators verify it. Once confirmed, the transaction becomes immutable.

On-chain transactions have four characteristics that matter for payment systems.

Finality: After confirmation, the transaction can't be reversed. Ethereum mainnet achieves finality in ~13–15 minutes (2 epochs under Proof-of-Stake). Layer-2 networks like Base or Arbitrum provide sequencer confirmation (block inclusion) in 2–5 seconds, though true finality depends on Ethereum L1 (~15+ minutes) and withdrawals to L1 carry a 7-day challenge window for optimistic rollups.

Transparency: Anyone can verify that a transaction occurred. This is useful for audits, dispute resolution, and regulatory reporting.

Counterparty trust elimination: The blockchain enforces settlement. No intermediary is required, and no party needs to trust the other's internal ledger.

Cost: Every on-chain transaction incurs gas fees. Ethereum mainnet typically runs $0.30–$0.50 for a token transfer during low-traffic periods, though fees are volatile and can spike significantly. Layer-2 networks charge $0.003–$0.09 for token transfers after the Dencun upgrade slashed data-posting costs by 90 percent or more.

On-chain settlement makes sense for high-value B2B transactions where finality justifies the cost, cross-border settlements where you want to eliminate correspondent banks, and situations where counterparties don't trust each other's internal systems.

Understanding Off-Chain Payments

Off-chain payments record transactions in application databases, APIs, or internal ledgers without involving the blockchain for each payment. This is how most payment processing works today.

Speed: Database write latency runs 10–50 milliseconds. Users see instant confirmation.

Cost: Per-transaction cost is negligible: just server and database expenses. No gas fees.

Privacy: Transaction details stay private to system participants. No public visibility.

Scalability: Hundreds of thousands of transactions per second are achievable with proper infrastructure. You're limited by database and server capacity, not blockchain throughput.

Trust requirement: Users must trust the platform operating the ledger. If Flutterwave processes your payment off-chain, you're trusting Flutterwave's systems.

Off-chain gives you speed and cost efficiency. On-chain gives you trustless finality. Most payment platforms combine both: off-chain for user-facing transactions where speed matters, with periodic on-chain settlement for finality.

So how do these tradeoffs look in practice?

The Cost and Performance Tradeoffs

Choosing between on-chain and off-chain comes down to three variables: cost per transaction, settlement speed, and throughput capacity. The tables below compare these across internal ledgers, traditional rails, and blockchain networks.

Note: Transaction costs and network throughput metrics are estimates as of Q1 2026 and are subject to network volatility and corridor-specific pricing.

Transaction Costs Across Different Approaches

Sources: Card network fees based on Visa and Mastercard published interchange fee schedules (updated semiannually). SWIFT costs per World Bank Remittance Prices Worldwide and Bankrate (2026). Mobile money fees per GSMA State of the Industry Report on Mobile Money 2025 (domestic P2P). On-chain gas fees based on Etherscan, PolygonScan, Arbiscan, and L2fees.info gas trackers (Q1 2026 snapshots). Internal ledger cost derived from AWS RDS and GCP Cloud SQL per-write pricing estimates.

Note: Internal ledger costs exclude compliance, fraud detection, and reconciliation overhead. Traditional rails include these costs. On-chain costs are gas fees for token transfers (e.g., USDC, USDT) and don't include custody or bridging infrastructure.

Settlement Speed

Approach	Confirmation	Settlement finality
Off-chain (internal ledger)	<100ms	T+1 to T+3 (depends on payout rails)
Layer-2 (sequencer confirmation)	2–5 seconds	~15+ min (L1 finality)
Ethereum mainnet	~12 seconds	~13–15 minutes
Polygon PoS	~2 seconds	~30 min (checkpoint to L1)
Traditional cross-border (SWIFT)	Minutes	1–5 business days

Note: "Confirmation" is when the user sees success. "Settlement finality" is when funds are irreversibly transferred.

Throughput

Approach	Transactions per second
PostgreSQL (tuned)	70,000+ (simple operations)
Solana	~1,000 effective (~3,500 including validator votes)
Polygon PoS	700–1,400
Base	~1,000
Ethereum mainnet	15–20

Note: These aren't equivalent workloads. A PostgreSQL write inserts a row. An Ethereum transaction involves consensus across thousands of nodes, cryptographic verification, and global state changes. The numbers show raw capacity, not like-for-like comparison.

The Visa TPS Myth
Visa's commonly cited "65,000 TPS" is a theoretical peak capacity from 2017. Their actual average throughput, calculated from 233.8 billion transactions in fiscal year 2024, runs approximately 7,400–9,300 TPS. Still higher than any blockchain, but not the gap marketing materials suggest.
But even before you hit throughput limits, the economics break down. Consider an e-commerce platform processing 50,000 transactions daily (barely 1 TPS):

Pure on-chain (mainnet): $15,000–$25,000 daily in fees. Uneconomical.
Pure on-chain (Layer-2): $150–$4,500 daily in fees. Expensive but possible.
Off-chain with daily batched settlement: $0.30–$0.50 daily per merchant (rolling up thousands of user payments into a single end-of-day settlement transaction). Highly economical.

The math points clearly toward hybrid architecture for high-volume use cases.

When On-Chain Settlement Makes Sense

On-chain settlement adds value in specific scenarios.

Cross-border B2B settlements: Traditional correspondent banking takes 1–5 days and costs $25–$100+ in fees, plus FX markups of 2–5 percent above mid-market rates. Stablecoin settlement on a Layer-2 network provides finality in seconds for under $0.10. For a remittance company settling with a partner bank in Nairobi, the economics favor on-chain settlement.

The infrastructure for cross-border stablecoin payouts is expanding fast. USDC has processed over $25 trillion in cumulative on-chain transaction volume since 2018, with Q3 2025 alone accounting for roughly $9.6 trillion. PayPal launched PYUSD stablecoin in 2023, Visa has run stablecoin settlement pilots since 2021, and Mastercard announced stablecoin payment capabilities in 2024.

High-value transactions requiring immediate finality: Off-chain ledgers can theoretically be reversed by the platform operator. On-chain settlement means the transaction becomes irreversible after confirmation. For property purchases, large B2B invoices above $100,000, or transactions where finality certainty justifies the cost, on-chain provides assurance.

Counterparty distrust scenarios: When international partners don't trust each other's internal ledgers, a neutral blockchain provides shared truth. Neither party can alter the record unilaterally.

Regulatory transparency requirements: Some jurisdictions require auditable transaction records. Public blockchains provide an immutable audit trail for regulatory reporting.

Regulatory Considerations
Compliance requirements vary by jurisdiction, but regulators generally focus on outcomes (transparency, auditability, consumer protection), not implementation specifics.

MiCA (EU): Fully enforced since December 2024, MiCA classifies stablecoins as E-Money Tokens or Asset-Referenced Tokens. It requires 1:1 liquid reserves, segregated custody, and regular audits. But it doesn't mandate that every payment transaction be on-chain. Off-chain processing is allowed as long as issuers can prove reserves. The practical impact: Several major EU exchanges restricted or delisted USDT for retail users under MiCA compliance requirements, while USDC remains available as the first MiCA-compliant global stablecoin.

Nigeria's ISA 2025: Signed in March 2025, this law expands the definition of securities to include digital assets, bringing them under SEC oversight. VASPs must meet capital adequacy requirements and comply with Travel Rule requirements per FATF guidance. On-chain isn’t mandated, but audit trails are.

Kenya's VASP Act 2025: Signed in October 2025, it introduces a licensing framework with the Central Bank of Kenya overseeing stablecoin issuers. Detailed regulations are still pending.

The pattern across jurisdictions: Regulators care about auditability and transparency, which can be achieved through off-chain audit logs. On-chain settlement is one way to achieve compliance, not the only way.

On-chain works for specific use cases. For many payment flows, off-chain is the better choice.

When Off-Chain Is Superior

Off-chain processing works better in several scenarios.

High-frequency, low-value transactions: When gas fees exceed a meaningful percentage of transaction value, off-chain is the only practical choice. Mobile money transfers of $5–$50, in-app purchases, subscription payments — these belong off-chain with batch settlement.

Privacy requirements: On-chain transactions are visible to anyone with blockchain access. For payroll, healthcare payments, or any scenario where transaction privacy matters, off-chain keeps details internal.

Instant user experience: Even fast blockchains add seconds of latency that users notice at checkout. For e-commerce, point-of-sale, and peer-to-peer transfers, off-chain processing gives instant feedback. Settle on-chain later.

Complex transaction logic: Multi-party splits, conditional payments, subscription billing with trials — these take more effort to implement and maintain in smart contracts than in application code. Off-chain gives you the full power of your application code.

Most production systems don't choose one or the other. They combine both.

Hybrid Architecture Patterns

Most production systems use a hybrid pattern. The blockchain handles the middle mile (settlement between counterparties) while traditional systems handle customer-facing processing, identity verification, and local currency conversion.

Pattern 1: Off-chain transactions with batch settlement: Process transactions in your internal ledger instantly, with no blockchain fees. At end of day (or week), aggregate and settle the net balance on-chain with a single transaction.

Picture 10,000 daily payments totaling $500,000. Settling each one individually on a Layer-2 network would cost $30–$900 in gas fees. Batch them into a single end-of-day settlement, and you pay a few cents.

Pattern 2: Threshold-based routing: Route transactions by value. Payments under a threshold (say, $1,000) batch-settle off-chain daily, while larger transactions settle immediately on-chain for the finality assurance that justifies the gas cost.

Pattern 3: On-chain settlement with off-chain metadata: Record the value transfer on-chain. Sender, receiver, and amount are publicly verifiable. Store everything else (customer info, order details, line items) in your database. You get blockchain proof of payment without exposing sensitive data or bloating transaction costs.

Pattern 4: Layer-2 with mainnet checkpoints: Process transactions on a Layer-2 for speed and low cost. The Layer-2 periodically posts batch proofs to Ethereum mainnet for ultimate security. You get Layer-2 economics with mainnet guarantees.

For most payment platforms, Pattern 1 (batch settlement) or Pattern 2 (threshold routing) makes the most sense. They're simpler to implement and provide the best balance of cost, speed, and finality.

Decision Framework: Questions to Determine Your Architecture

Work through these questions with your team to determine your approach.

1. What's Your Transaction Volume and Value Distribution?

Under 1,000 transactions daily, mostly under $100: Off-chain is sufficient. Batch-settle daily.
1,000–50,000 transactions daily with mixed values: Hybrid. Off-chain for smaller amounts, on-chain for larger ones.
Over 50,000 transactions daily, mostly under $100: Pure off-chain with daily batch settlement.
High-value transactions over $10,000, regardless of volume: Benefit from on-chain settlement for faster finality.

2. Do You Need Immediate Settlement Finality?

Yes, within seconds: On-chain via Layer-2.
Yes, but hours are acceptable: Off-chain with hourly batch settlement.
T+1 or T+3 acceptable: Off-chain with daily or weekly settlement.

3. Are You Processing Cross-Border Payments?

Yes, and settlement with international partners is critical: On-chain eliminates correspondent banks.
Yes, but only for accounting: Off-chain with periodic reconciliation.
Domestic only: Off-chain likely sufficient.

4. What's Your Privacy Requirement?

High (payroll, healthcare): Off-chain keeps details private.
Medium (e-commerce): Hybrid. On-chain value transfer, off-chain metadata.
Low (public transparency valuable): On-chain provides the audit trail.

5. Do Users Expect Instant Confirmation?

Yes, under 100 milliseconds required: Off-chain for UX, settle later.
2–5 seconds acceptable: Layer-2 on-chain is feasible.
Asynchronous (B2B invoices): Settlement timing is less critical; optimize for cost.

6. How Much Blockchain Complexity Can Your Team Handle?

Low (small team, product focus): Off-chain is simpler. Avoid blockchain complexity until you need it.
Medium: Consider Layer-2 for the best balance.
High (blockchain engineers on staff): Sophisticated hybrid patterns are possible.

7. What's Your Regulatory Exposure?

Heavy transparency requirements: On-chain provides built-in auditability that can simplify compliance.
Regulated but implementation-agnostic: Off-chain with strong audit trails is sufficient.
Minimal regulation: Optimize for cost and performance.

How Flutterwave Can Help With Hybrid Architecture

Building payment infrastructure that spans traditional rails and blockchain settlement is complex. It requires understanding both worlds and designing systems that move smoothly between them. Flutterwave processes billions of dollars annually across traditional payment rails (cards, bank transfers, mobile money) with coverage across 30+ African countries. That operational experience informs how we think about blockchain integration: pragmatically, not ideologically.

Blockchain settlement adds value for cross-border finality and cost reduction in specific corridors. Traditional infrastructure performs better for high-frequency domestic transactions.

For developers, this means APIs that abstract complexity. You shouldn't need to understand gas fees or bridge mechanics to process payments. Flutterwave handles the infrastructure decisions so you can focus on your product.

Each payment system should go off-chain, on-chain, or hybrid according to the team's specific needs. The decision framework in this guide helps you evaluate your options. When you're ready to implement, explore Flutterwave's payment APIs for traditional payment capabilities and StableRails for stablecoin settlement.

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.

How Teams Integrate Stablecoin Rails Without Rewriting Their Platform

uma victor — Fri, 06 Mar 2026 10:41:56 +0000

Adding a new settlement rail to an existing payment system raises the same question every time, whether you are an early-stage team or a platform processing millions of cross border transactions: How much of our current architecture do we need to change? With stablecoins, that question feels heavier because the underlying technology is different. But in practice, integrating stablecoin settlement usually means adding one more settlement path, not rebuilding what you already have.

If your system already handles pending states and delayed settlement, you are closer than you think.

This blog post covers where stablecoins fit in a typical payment stack, how to add them as a parallel settlement path, how to handle settlement finality safely, and how to roll the whole thing out without putting production at risk.

But before getting into architecture, there is a mental shift that changes how you approach the rest of the integration.

The Mental Shift Teams Get Wrong

The first mistake most engineering teams make is treating stablecoins like a new payment product. Stablecoins are settlement rails, digital assets pegged to fiat currency that move value between parties. That distinction changes everything about how you approach the integration.

Think about how your system handles cards versus bank transfers today. A customer pays through the same checkout, creates the same payment intent, triggers the same authorization logic. The only difference is what happens after authorization: One payment settles through a card network over T+2, and the other settles through ACH over T+1. The checkout stayed the same. The reporting stayed the same. Only the settlement path diverged.

Stablecoins work the same way. They are one more way to move money from point A to point B after a payment is initiated. Integration happens at the settlement layer. Your payment initiation and authorization logic stay untouched.

Think of it like adding a new courier service to an e-commerce platform. Your order system, inventory management, and checkout stay exactly the same. You just add a new fulfillment adapter that ships packages through a different carrier.

This is why the biggest payment companies are adding stablecoin rails without overhauling their platforms. Stripe treats stablecoins as just another payment method inside its existing payment methods. Visa runs USDC settlement on Solana between issuers and acquirers while the consumer card experience stays completely unchanged. Mastercard partnered with Thunes to route stablecoin payouts through the same Mastercard Move network that handles fiat. The pattern here is stablecoins slot in at the settlement layer while everything above it stays untouched.

Once you see stablecoins as a settlement path rather than a product category, the integration points become obvious.

Where Stablecoin Infrastructure Fits Into a Typical Payment Stack

Most payment systems follow a similar flow regardless of the rails underneath. A payment intent is created, authorization checks run, settlement executes through the chosen rail, and a confirmation event closes the loop. Stablecoins primarily integrate at the settlement layer, without changing payment intent or authorization logic.

The flow before and after adding stablecoin rails:

Architecturally, nothing changes upstream of the settlement router. Your payment intent creation, fraud detection, KYC checks, and risk scoring are all settlement-agnostic and do not care whether the money ultimately moves through SWIFT, ACH, card networks, or a blockchain. The only new component is a settlement adapter that speaks the stablecoin protocol.

Your existing webhook and callback infrastructure already handles the patterns stablecoins need. If your system can process an asynchronous "payment completed" event from a bank, it can process one from a blockchain confirmation service. The event shape is nearly identical: a transaction identifier, a status, an amount, a timestamp.

For teams running payment orchestration layers, the orchestration layer already abstracts multiple payment service providers behind a unified API. Adding a stablecoin settlement adapter works the same way as adding a new PSP. Your routing engine evaluates the best rail per transaction based on corridor and cost, and the stablecoin adapter becomes one more option in that evaluation.

What about the differences? There are a few, and they matter. Stablecoins are push-based (the sender initiates the transfer), while cards are pull-based (the merchant requests funds). Stablecoins confirm asynchronously in seconds to minutes, while card authorizations return synchronously in milliseconds. And stablecoins do not have native chargeback mechanisms, so refund and dispute handling lives in your application layer.

But none of these differences require architectural changes to your payment system. Your system already handles asynchronous confirmation (ACH does the same thing). Your system already handles rails without chargebacks (wire transfers work this way).

The infrastructure you already have covers about 80% of what stablecoin integration requires. The remaining 20% is the settlement adapter itself and confirmation tracking.

Adding Stablecoins as a Parallel Payment Rail

Stablecoins should plug in after payment initiation. Treat them as an alternative settlement backend that produces finality events, exactly like your other rails do.

Identify the Boundary Where Settlement Diverges
In most payment systems, there is a clear boundary between "deciding to pay" and "executing the payment." The payment intent captures the decision. The settlement adapter executes it.

Cards, ACH, and instant rails already diverge at this boundary. A card adapter talks to a card processor, an ACH adapter formats NACHA files or calls a banking API, and an instant rail adapter connects to a real-time payment network. Despite the backend differences, they all receive the same input (a payment intent with amount, currency, and destination) and produce the same output (a settlement result with status and reference).

Stablecoins hook in at exactly the same seam. The stablecoin adapter takes a payment intent and executes settlement by broadcasting a token transfer to the appropriate blockchain. It then watches for confirmation and reports back with a settlement result.

That adapter interface in TypeScript:

interface SettlementAdapter {
  rail: string;
  initiate(intent: PaymentIntent): Promise<SettlementResult>;
  checkStatus(reference: string): Promise<SettlementStatus>;
  onFinality(reference: string, callback: FinalityHandler): void;
}

// Your stablecoin adapter implements the same interface
const stablecoinAdapter: SettlementAdapter = {
  rail: "stablecoin",

  async initiate(intent: PaymentIntent): Promise<SettlementResult> {
    const txHash = await broadcastTransfer({
      token: intent.stablecoin ?? "USDC",
      chain: intent.chain ?? "base",
      to: intent.destination.walletAddress,
      amount: toSmallestUnit(intent.amount, intent.currency),
    });

    return {
      reference: txHash,
      status: "PENDING",
      rail: "stablecoin",
      metadata: { chain: intent.chain, token: intent.stablecoin },
    };
  },

  async checkStatus(reference: string): Promise<SettlementStatus> {
    const confirmations = await getConfirmationCount(reference);
    const threshold = getThresholdForChain(reference);
    return confirmations >= threshold ? "SETTLED" : "PENDING";
  },

  onFinality(reference, callback) {
    confirmationTracker.subscribe(reference, callback);
  },
};

This adapter has the same shape as your card adapter and your ACH adapter. The rest of your system does not know or care which one is running.

Keep a Single Internal Payment State Machine
Do not introduce stablecoin-specific states. This is the fastest way to create branching logic everywhere in your codebase, from reporting to reconciliation to customer support tooling.

Instead, map stablecoin finality events into your existing state machine:

Your Existing State	Card Behavior	ACH Behavior	Stablecoin Behavior
`INITIATED`	Intent created	Intent created	Intent created
`PENDING`	Auth hold placed	Submitted to bank	Transaction broadcast
`SETTLED`	Capture completed (clearing initiated)	Bank confirms credit	Confirmation threshold met
`FAILED`	Decline or timeout	Return or rejection	Transaction reverted or timed out

The state machine is rail-agnostic. Only the settlement adapter knows which rail is running. Your finance dashboard and reconciliation jobs work against the same states regardless of the underlying rail.

Route Settlement Based on Context
Settlement routing should depend on corridor, region, volume, or counterparty preference. There is no reason to treat stablecoin payments as a separate product category at the routing layer.

A simplified routing function:

function selectSettlementAdapter(intent: PaymentIntent): SettlementAdapter {
  const { sourceCurrency, destinationCurrency, corridor, amount } = intent;

  // Cross-border treasury above threshold: use stablecoin rails
  if (corridor === "cross-border" && amount > 10_000) {
    return adapters.stablecoin;
  }

  // Domestic payments: use local bank rails
  if (corridor === "domestic") {
    return adapters.localBank;
  }

  // Default: card rails
  return adapters.card;
}

If you need to shift a corridor from bank rails to stablecoin rails, you update the routing config. You do not touch checkout, reporting, or reconciliation logic.

One factor that makes stablecoin routing different from traditional rail routing: Gas costs are flat per transaction. While a card payment costs the merchant 1.5–3.5% regardless of amount, stablecoin network fees are flat per transaction, typically just cents, whether you're moving $100 or $100,000. That flat fee structure makes stablecoins attractive for high-value transactions where percentage-based fees add up. Your routing logic can factor this in. Route payments above a certain threshold through stablecoin rails where the cost advantage is most pronounced, and keep smaller payments on card or instant rails where the user experience is more familiar.

Treat Stablecoin Settlement Like Instant Rails
Stablecoins settle quickly but asynchronously. They behave more like instant bank transfers than like card authorizations. A few differences to design around:

Stablecoins are push-based. The sender initiates and signs the transfer. There is no "authorization hold" followed by a "capture." The money moves when the transaction is broadcast.
Stablecoins are irreversible on-chain. There are no chargebacks. If you need to issue refunds, that is a separate transaction your application layer handles.
Stablecoins confirm in seconds to minutes. But "broadcast" is different from "settled." A transaction can be broadcast and visible on-chain before it reaches your finality threshold. Design for speed without assuming immediacy.

At this point, your system can route settlements through stablecoin rails. But there is a concern that trips up most teams: How do you know when a stablecoin payment is actually final?

Handling Settlement Finality Without Breaking Your Ledger

The most common failure in stablecoin integration is updating balances too early. A transaction appears on-chain, an event fires, your system credits the recipient. Then the block gets reorganized, the transaction disappears, and your ledger is wrong.

Define What "Final" Means for Your System
On traditional rails, finality is defined by the network. A card capture is final when the processor confirms it. An ACH credit is final after the settlement window closes. With stablecoins, you get to choose your finality threshold based on the blockchain network and your risk tolerance.

Each network has different finality characteristics:

Network	Time to Finality	Confirmation Approach
Ethereum L1	~13–19 minutes	Wait for 2 finalized epochs
Solana	~1–13 seconds	"confirmed" (⅔ stake voted) or "finalized" (32 slots)
Base / Arbitrum	Seconds (soft) to ~15 minutes (hard)	Sequencer provides instant soft finality; true finality inherits from Ethereum L1
Tron	~57 seconds	19 of 27 Super Representatives confirm
Polygon PoS	~5 seconds	Milestone-based finality post-Heimdall v2

For most payment use cases, waiting for the chain's "finalized" commitment level is the right default. For lower-value transactions on networks with strong probabilistic guarantees (like Solana's "confirmed" level, which has historically shown extremely low rollback risk), you can accept faster confirmation.

A practical approach is to scale your confirmation requirements with transaction value. For a $50 payment on Solana, "confirmed" commitment (about one to two seconds) is reasonable. For a $50,000 cross-border treasury movement on Ethereum L1, wait for full finality (two finalized epochs, roughly 13 minutes). This is the same risk-based approach you would use with any settlement rail. You would not wire $50,000 based on a pending ACH notification either.

On Layer 2 networks like Base and Arbitrum, there are two layers of finality worth understanding. The sequencer provides soft finality almost instantly (under a second), which means the L2 has ordered and committed to including your transaction. Hard finality happens when the batch is posted to Ethereum L1 and that L1 block is finalized, which takes 13–19 minutes. For most payment scenarios, sequencer confirmation is sufficient because reverting it would require the sequencer to act maliciously, which carries substantial economic and reputational penalties. For very high-value settlements, wait for L1 finality.

Pick a threshold, document it, and treat it as a contract between engineering and finance. Your finance team needs to know exactly when a stablecoin payment counts as settled in the books. If your threshold changes (say you move from Ethereum L1 to Base for a corridor), update the documentation and notify finance before the switch goes live. Surprises about when money is "real" erode trust fast.

Separate Confirmation Tracking from Balance Updates
Structure this as two distinct services:

A confirmation tracker watches the blockchain. It monitors transaction status, counts confirmations, and emits finality events when the threshold is reached. This service talks to RPC nodes or uses a webhook provider like Alchemy, QuickNode, or Tatum.
A ledger writer updates balances. It listens for finality events and applies balance changes. It never talks to the blockchain directly.

They communicate through events. This separation prevents race conditions and allows the confirmation tracker to handle retries and chain reorganizations without corrupting the ledger. If a reorganization happens and a previously confirmed transaction disappears, the confirmation tracker revokes the finality event. Depending on your system design, the ledger writer can reverse the balance update automatically, or flag it for manual review before reversal. Neither service needs to know how the other works internally, which makes each one easier to test and deploy independently.

Design for Idempotency and Retries
Webhook duplication and event replay are normal operating conditions with blockchain infrastructure. This is different from card processing, where you might see duplicates occasionally during edge cases. With blockchain webhooks, expect them. Your system needs to handle them gracefully.

Use the transaction hash as a natural idempotency key. It is globally unique and deterministic. Before processing any settlement event, check whether you have already processed that hash:

async function handleSettlementEvent(event: SettlementEvent): Promise<void> {
  const { txHash, status, amount, recipient } = event;

  // Idempotency check: skip if already processed
  const existing = await db.settlements.findByTxHash(txHash);
  if (existing && existing.status === "SETTLED") {
    logger.info(`Already processed settlement for tx: ${txHash}`);
    return;
  }

  // Verify confirmation threshold is met
  const confirmations = await chain.getConfirmationCount(txHash);
  const threshold = config.finalityThreshold[event.chain];

  if (confirmations < threshold) {
    logger.warn(`Insufficient confirmations for tx: ${txHash}`);
    await queue.scheduleRetry(event, { delayMs: 15_000 });
    return;
  }

  // Apply the balance update within a transaction
  await db.transaction(async (trx) => {
    await trx.settlements.upsert({
      txHash,
      status: "SETTLED",
      amount,
      recipient,
      settledAt: new Date(),
      confirmations,
    });

    await trx.balances.credit(recipient, amount);
  });
}

Handle partial failure states explicitly. A broadcast can succeed while confirmation stalls (network congestion, gas price spikes). A confirmation can happen while your webhook delivery fails (your server was down). Build for both.

Reconciliation as a First-Class Process
Real-time events are your primary settlement flow, but reconciliation catches everything that falls through the cracks. Treat it as a production process from day one.

Run scheduled reconciliation jobs that compare your internal ledger against on-chain state. For each stablecoin wallet your system manages, query the token's balanceOf on-chain and compare it against the sum of credits and debits in your database. Flag any mismatches for investigation.

Common causes of mismatches include missed webhook events, transactions that your system did not initiate (direct wallet transfers), failed transactions that consumed gas but did not transfer tokens, and events processed out of order during high-throughput periods.

Build reconciliation at two frequencies. Real-time reconciliation runs on your critical path: When a high-value settlement event comes in, verify it against on-chain state before crediting the balance. Batch reconciliation runs on a schedule (hourly or daily): Query all managed wallet balances on-chain, and compare against your ledger totals. The batch job is your safety net. In practice, you will find mismatches early on, mostly from edge cases you did not anticipate. Each mismatch you investigate and resolve makes the system more reliable.

If you are working with multiple stablecoin tokens (USDC and USDT, for example), be aware that they have different decimal precisions and transfer behaviors. USDC on Ethereum uses 6 decimals, while DAI uses 18. USDT's transfer() function does not return a boolean value, which violates the ERC-20 specification and can cause issues if your smart contracts expect a standard return. Use a safe transfer library (like OpenZeppelin's SafeERC20) if you are interacting with tokens at the contract level.

This process is what builds trust with finance teams and passes audits. When finance asks "how do we know the stablecoin balances are correct?", your answer is reconciliation reports.

That covers the technical patterns for settlement and finality. But shipping them to production is a different problem.

How to Safely Introduce Stablecoin Settlement

The patterns above work. But shipping them to production requires a controlled rollout strategy. Do not skip this step. The difference between a successful stablecoin rollout and a rollback is almost always the rollout plan itself.

Start with Internal or Low-Risk Flows
Pick a flow where you control both sides of the transaction. Treasury movements between your own wallets, intercompany transfers, or a limited cross-border corridor with a trusted counterparty.

Cross-border treasury is often the best starting point. The cost savings are immediately measurable; moving $100,000 between entities via correspondent banking might cost $3,000–$7,000 in fees and take three to five days, whereas a stablecoin transfer costs pennies and settles in minutes. Plus, the transaction volume is low enough to monitor manually during the early rollout. You also get real operational data on confirmation latency, gas costs, and reconciliation accuracy before any customer money is on the line.

If something breaks on an internal treasury movement, it is an operational issue you can fix quietly. If something breaks on a customer-facing payment, it is a support ticket and a trust problem.

Use Feature Flags and Volume Caps
Place feature flags at the routing layer so you can disable stablecoin settlement with a config change. Enforce volume caps before settlement execution to limit your exposure while you build confidence.

A practical rollout sequence: Start with 100% of internal treasury flows. Once stable, open to 1% of eligible cross-border payments. Ramp to 5%, then 25%, then 100% as your confidence in confirmation tracking and error handling grows.

Build a circuit breaker into the routing layer. If stablecoin settlements fail above a configured threshold (say, five consecutive failures or a 10% failure rate over five minutes), automatically route traffic back to bank rails and alert the on-call engineer. You can retry stablecoin rails after a cooldown period. This is the same pattern you would use for any external dependency in a payment flow, and it means network congestion, RPC failures, or degraded confirmation times don't turn into customer-facing outages for your platform.

Make Observability a Launch Requirement
If you cannot observe it, do not ship it. The metrics that matter most for stablecoin settlement:

Confirmation latency (p50 and p95): How long between broadcast and finality
Failed settlement rate: Percentage of broadcasts that do not reach finality
Reconciliation mismatch count: Discrepancies between your ledger and on-chain state
Gas cost per transaction: Actual network fees paid per settlement

Configure alerts for confirmation latency exceeding your defined threshold, settlement failure rates above your baseline, and any reconciliation drift detected during scheduled jobs.

A useful practice is to build a per-rail dashboard that shows acceptance rates, average confirmation times, costs per transaction, and reconciliation status side-by-side for each settlement rail. This gives your team a single view to compare stablecoin performance against bank and card rails.

Align with Finance Early
Your finance team does not care about blockchain technology. They care about when money is "really there," how they audit it, and what happens when something goes wrong.

Walk them through your state diagrams. Show them what INITIATED, PENDING, and SETTLED mean in practice. Explain your finality rules in their language: "We count a stablecoin payment as settled when the network has confirmed it to a point where reversal would require destroying billions of dollars in collateral." Show them reconciliation reports. Give them access to the same dashboard your engineering team uses so they can see settlement status in real time.

Finance cares about predictability. Lead with system behavior. If you can demonstrate that stablecoin settlement produces the same ledger entries, the same reconciliation reports, and the same audit trail as your existing rails, the conversation shifts from "should we do this?" to "which corridors should we roll this out to next?"

Wrapping Up

Stablecoin integration is a routing and settlement problem, and teams that treat it that way integrate faster and ship safer. The adapter pattern, unified state machine, and confirmation tracking covered here are the same patterns you would use to add any new settlement rail. Stablecoins just happen to settle faster and work around the clock.

If you are looking to integrate stablecoin settlement into your own platform, Flutterwave, has integrated Polygon-based stablecoin settlement into its platform, with a broader rollout planned across its merchant base throughout 2026.

Start with one corridor and one flow. Measure everything. The infrastructure patterns are proven, the architecture is familiar, and the only new thing is the settlement rail itself.

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.

What Are Stablecoins? Understand How They Work

uma victor — Fri, 20 Feb 2026 10:53:03 +0000

In 2025, stablecoins processed over $33 trillion USD in transaction volume. Names like USDT and USDC have become common across crypto exchanges, fintech apps, and cross-border payment platforms. Yet most explanations treat stablecoins like speculative digital assets rather than what they actually are: a new type of payment rail built on blockchain technology.

This article closes that gap. You will learn what stablecoins are, how they maintain price stability, and how they function as settlement rails in production systems. By the end, you will be able to reason about stablecoins the way you reason about ACH or SWIFT: as payment rails with specific characteristics, tradeoffs, and appropriate use cases.

What Are Stablecoins?

A stablecoin is a digital currency designed to maintain a stable value relative to a reference asset, typically a fiat currency like the US dollar. Unlike Bitcoin or Ethereum, which can swing 10% or more in a single day due to price fluctuations, stablecoins aim to hold a consistent 1:1 peg with their reference currency. A stablecoin pegged to the dollar, for example, targets a stable price of exactly $1.00.

Think of it like a digital representation of a bank deposit. When a company like Circle (the issuer behind USDC) receives a dollar deposit through a regulated financial institution, they mint a USDC token on the blockchain, similar to how a bank credits your account when you wire funds in. When someone redeems their USDC, Circle burns the token and wires the dollar back. This mint-and-burn cycle, backed by cash and US treasuries, is what keeps one USDC worth one dollar. The difference from traditional banking is that these balances live on a public ledger and can move 24/7 without waiting for bank processing windows.

For a developer, the distinction is operational. You cannot price a merchant invoice in Bitcoin because the value might fluctuate 5% between the time the invoice is generated and the time the transaction settles. A stablecoin solves this volatility problem while retaining the core benefits of blockchain infrastructure:

24/7 Availability: No banking holidays or downtime.
Programmability: Smart contracts can automate flows based on logic.
Global Reach: The network is agnostic to borders.

When we discuss stablecoins in the context of payments infrastructure, we are almost exclusively referring to tokens that tokenize fiat currency on a public ledger. They act as a bridge, importing the stability of national currencies into a public and verifiable blockchain.

Over 90% of stablecoin market capitalization today is fiat-backed, with nearly all of that pegged to the US dollar. The total stablecoin market exceeded $200 billion by early 2025, with Tether (USDT) holding the largest share at over $140 billion and Circle's USDC at approximately $44 billion.

But market size alone doesn't tell you whether you can rely on these tokens in production. For that, you need to understand how the $1.00 peg actually holds.

How Fiat-Backed Stablecoins Maintain a Stable Value

Sending a stablecoin and having it arrive is the easy part. The harder question is: Why does the price stay at $1.00, and what happens when it doesn't? For developers building payment systems, the answer directly affects how you handle settlement finality, operational risk, and failure modes. The stability of a stablecoin is the result of specific mechanisms involving reserves, issuers, and market incentives.

Understanding these mechanics affects how you handle settlement finality, operational risk, and failure modes in your application.

Fiat Reserves, Bank Deposits, and Custodians

The majority of the stablecoin market operates on a fiat-backed model. By market capitalization, over 90% of stablecoins fall into this category. This is the model most relevant to enterprise payments.

In this architecture, a centralized issuer (such as Circle for USDC or Tether for USDT) mints stablecoins only when equivalent fiat value is deposited into their reserve accounts.

The Reserve: The stablecoin issuer holds reserve assets, including cash, US Treasury bills (government debt instruments), money market funds, and other liquid assets in regulated financial institutions. These stable assets back every token in circulation.
The Claim: The stablecoin token represents a redemption right; the issuer is contractually obligated to exchange it back for dollars.

For developers building treasury or payment systems, this means you treat stablecoin balances as cash equivalents only if the redemption path is reliable. The risk here is not code risk from a smart contract bug. It is counterparty risk. If a custodian holding reserve assets fails, or if the issuer faces regulatory action, the 1:1 backing can be threatened.

Your system must treat stablecoin balances differently than native crypto assets. You are not just trusting the blockchain. You are trusting the off-chain bridge to real dollars. Say you're building a payroll platform that holds contractor funds in USDC before disbursement. A custodian failure means your contractors don't get paid. Your system needs to track issuer health the same way you'd monitor a banking partner.

Issuance and Redemption Cycles

The supply of a stablecoin is elastic. It expands and contracts based on liquidity needs through minting and burning.

Minting (fiat → stablecoin): An institutional customer wires USD to the issuer. The issuer verifies receipt and calls a mint function on the stablecoin smart contract, creating new tokens and sending them to the customer's wallet.
Burning (stablecoin → fiat): A customer sends stablecoins to the issuer's redemption address. The issuer calls a burn function to destroy the tokens on-chain and wires the equivalent USD back to the customer's bank account.

This elastic supply is what keeps the peg intact at scale. When demand rises, new tokens are minted to meet it. When holders want to exit, tokens are burned, and supply shrinks. The system self-corrects as long as the issuer can honor redemptions. When they can't, things break fast.

In March 2023, Silicon Valley Bank collapsed with $3.3 billion of Circle's USDC reserves inside. USDC de-pegged to below $0.88 before banking access was restored. Payment platforms with no monitoring for issuer-level events continued accepting USDC at face value, and their ledgers didn't match reality.

Your payment system should detect issuer-level incidents, not just blockchain network failures. If the issuer halts redemptions, your system might need to pause acceptance or adjust risk parameters.

Market Arbitrage Enforcing the Peg

The issuer does not constantly intervene in the market to fix the price at $1.00. Instead, they rely on a distributed network of arbitrageurs.

If price < $1.00: Arbitrageurs buy the stablecoin on exchanges for $0.99, redeem it with the issuer for $1.00, and pocket the difference. This buying pressure pushes the price back up.
If price > $1.00: Arbitrageurs mint new stablecoins from the issuer for $1.00 and sell them on exchanges for $1.01. This selling pressure pushes the price back down.

These two forces help maintain price alignment without anyone actively managing it. Whenever the price drifts from $1.00, traders step in because there's money to be made by correcting it. The peg holds not because someone is controlling it, but because it's profitable to fix it when it breaks.

But this mechanism depends on arbitrageurs having access to liquidity. During extreme market stress, if they can't access capital (for example, when banking rails are closed on weekends), the peg might temporarily wobble. Think about an invoicing platform where merchants generate USDC-denominated invoices. If the peg drops to $0.995 on a weekend and your system auto-accepts at $1.00, you're eating the difference on every transaction. A simple price feed check before accepting payment can prevent this.

Fiat-Backed vs Algorithmic Models

While fiat-backed stablecoins dominate, you may encounter algorithmic stablecoins. These attempt to maintain a peg through on-chain incentives and smart contracts that manipulate supply, often backed by volatile crypto assets rather than fiat.

The problem with this approach showed up clearly in May 2022 when TerraUST collapsed. Terra relied on its companion token LUNA to absorb price fluctuations, but when confidence dropped, both tokens entered a death spiral. Over $40 billion in value was wiped out in days. The peg wasn't backed by dollars in a vault. It was backed by market confidence, and once that broke, there was nothing underneath.

Payment infrastructure requires a deterministic value. You cannot build a reliable settlement rail on a token that relies on game theory to hold its value. Stick to fiat-backed stablecoins for production payment flows.

Transparency and Attestations

How do you know the reserves actually exist? Unlike public blockchains, where every transaction is visible, off-chain reserves are opaque. Issuers address this through attestations: periodic reports by third-party accounting firms verifying that assets exceed liabilities.

Circle publishes monthly attestation reports from Deloitte that detail exactly what assets back each USDC token in circulation. Tether publishes quarterly reports from BDO Italia with reserve breakdowns.

For compliance and finance teams, these attestations are the difference between an internal accounting nightmare and a compliant instrument. When integrating a stablecoin, your compliance team will likely require these reports before approving the asset for treasury operations. Build this into your vendor evaluation process.

Once you're confident in the token's backing, the next question is: How does a stablecoin transaction actually move from sender to receiver?

How Stablecoin Settlement Works

Stablecoin transactions settle on blockchain networks, which means understanding blockchain mechanics is necessary for building reliable payment systems.

Transaction Lifecycle

When you initiate a stablecoin transfer, the transaction follows a specific path. Your application broadcasts the signed transaction to the network. The transaction enters the mempool, where pending transactions wait until validators include them in a block. Once included, the transaction has its first confirmation.

But one confirmation is not settlement. As more blocks are added, the transaction becomes increasingly difficult to reverse. After enough confirmations, the exact number depends on the network and your risk tolerance, the transaction reaches finality. At that point, the balance update is irreversible.

Network Differences

Settlement speed varies across blockchain networks. On Ethereum, blocks are produced every 12 seconds, but true finality takes approximately 12–15 minutes. Faster networks like Solana achieve fast confirmation times, often under one second, with full finality around 12 seconds. Tron, which hosts significant USDT volume, produces blocks every three seconds with practical finality in around one minute.

Layer 2 networks like Base and Polygon offer faster confirmation times with lower fees, though they inherit security guarantees from their underlying Layer 1 chain. Flutterwave's stablecoin infrastructure runs on Polygon, which provides sub-second confirmations and transaction fees that typically stay under $0.01. Choose your network based on the tradeoffs that matter for your use case.

Irreversibility and Fees

Unlike card payments or ACH transfers, blockchain transactions cannot be reversed once finalized. There is no chargeback mechanism, no dispute process at the protocol level, and no way to claw back funds sent to the wrong address.

This irreversibility eliminates chargeback fraud risk almost entirely, which costs merchants billions annually on card networks. But it also means user errors are unrecoverable without the recipient's cooperation. Your application layer must handle refunds because the blockchain will not.

Transaction fees are paid in the network's native currency rather than as a percentage of the transfer amount. Fees vary based on network congestion, from under $1 on Layer 2 networks to $50 or more on Ethereum during high-demand periods.

Stablecoins vs Traditional Payment Rails

Stablecoins compete architecturally with ACH and SWIFT, not with Visa and Mastercard. Card networks handle authorization and routing, while final settlement occurs later through banking rails. Stablecoins handle settlement directly on-chain.

Understanding this distinction clarifies where integration makes sense.

Characteristic	Stablecoins	ACH	SWIFT	Cards
Settlement Speed	Seconds to minutes	1-3 business days	1-5 business days	1-3 business days
Operating Hours	24/7/365	Business days only	Business days only	24/7 authorization, batch settlement
Cost	$0.01-$5 network fee	$0.20-$1.50	$25-50+	1.5-3.5% of transaction
Finality	Irreversible	60-day return window	Reversible via investigation	120-day chargeback window
Geographic Reach	Global	US domestic	Global with correspondent banks	Global with network acceptance

The comparison reveals complementary strengths. Stablecoins excel at cross-border transfers where traditional correspondent banking adds days of delay and percentage-point fees. ACH remains superior for domestic US payments where low cost and established integration outweigh speed benefits. Cards provide consumer protection through chargebacks that stablecoins cannot match.

Choose based on your use case. A platform paying international contractors benefits from stablecoin rails. A consumer e-commerce checkout benefits from card acceptance with its buyer protections.

If stablecoin rails are the right fit for your use case, the next step is understanding what integration actually looks like at the system level.

Integrating Stablecoins in Your Payment Flows

Adding stablecoin support to a payment platform involves wallet management, transaction initiation, confirmation handling, and reconciliation. While detailed implementation guidance deserves its own treatment, understanding the high-level patterns helps you evaluate the engineering investment required.

Wallet Management

Your system needs a way to receive funds.

Segregated Wallets: You generate a unique blockchain address for every customer or deposit session. This makes reconciliation easy (Address A = Customer A), but gas costs are higher because you eventually have to "sweep" funds to a central treasury.
Omnibus Wallets: You use one central address for all inflows. Customers must include a "memo" or unique identifier in the transaction metadata. This is efficient but prone to user error (users forgetting the memo).

On-Chain Event Monitoring

You cannot rely on webhooks from a third party alone; robust systems run their own "listeners."

A typical flow:

Listen: Service watches the blockchain for Transfer events to your deposit address.
Filter: Check if the token contract matches the official stablecoin address (preventing fake token scams).
Count: Wait for X confirmations (e.g., 12 blocks).
Reconcile: Update the user's balance in your database.

Handling Failed or Stuck Transactions

Blockchain transactions can fail (e.g., out of gas) or remain pending if the offered gas fee is too low. Your UI must account for this pending state. Unlike a declined credit card which is instant, a pending blockchain transaction might time out after hours. Your system needs logic to detect these zombies and prompt the user to retry or speed up the transaction.

Risks and Limitations

Building with stablecoins requires clear-eyed assessment of the risks they introduce.

Custody Risk

Custody risk means that whoever holds the private keys controls the assets. Compromised keys mean lost funds with no recovery mechanism. Production systems require enterprise-grade security: hardware security modules, multi-signature schemes, and strict access controls.

Issuer Risk

Issuer risk acknowledges that stablecoins are only as reliable as their issuers. If an issuer mismanages reserves, faces regulatory action, or experiences operational failures, your stablecoin balances are affected. Diversifying across compliant issuers and monitoring issuer health reduces but does not eliminate this risk.

Regulatory Exposure

Regulatory exposure varies by jurisdiction and continues to change. Some regions have clear frameworks for stablecoin usage; others have ambiguous or restrictive rules. Your compliance team must evaluate the regulatory status of stablecoin operations in every market you serve.

Network Congestion

Network congestion can spike transaction fees and delay confirmations during high-demand periods. Your system should handle variable fees gracefully and set appropriate expectations for users about settlement timing.

Irreversibility

Irreversibility shifts all refund responsibility to your application layer. You cannot rely on the payment network to reverse fraudulent or erroneous transactions.

These risks do not disqualify stablecoins from serious payment infrastructure. They require the same thoughtful risk management you apply to any financial system dependency.

Where Stablecoins Fit in Modern Payment Architectures

Stablecoins are not a hammer for every nail. They fit best in specific architectural gaps where traditional rails struggle.

Cross-Border Treasury Movement

Moving funds between subsidiaries across Nigeria, the UK, and the US via SWIFT is slow and expensive, with fees exceeding 8% in some African countries and settlement taking days. Stablecoins allow for near-instant treasury rebalancing, freeing up working capital that would otherwise be stuck in transit. This is already happening at scale. Flutterwave, for example, built a stablecoin-powered cross-border payment network across 30 African countries, settling transactions in seconds instead of days.

Merchant Settlement

For merchants selling internationally, waiting as much as T+2 days for settlement ties up cash flow. With stablecoin settlement, merchants can receive funds in minutes. Flutterwave's recently launched stablecoin balances let merchants hold and transact in USDC and USDT alongside traditional currencies like USD and NGN, giving them the option to settle on whichever rail best fits the transaction.

Liquidity Bridging

Fintechs can use stablecoins to bridge liquidity between different fiat currencies. Rather than pre-funding accounts in every target currency, companies can hold liquidity in stablecoins and swap into local fiat only when a payment needs to be made.

Conclusion

For developers building payment systems, understanding stablecoins is now part of the job. You need to recognize that stablecoin rails offer specific advantages for specific use cases: faster cross-border settlement, lower fees for international transfers, and 24/7 operation without banking hour constraints.

The technology continues to mature. Regulatory frameworks are crystallizing in major jurisdictions. Enterprise adoption is accelerating. Platforms like Flutterwave are demonstrating how stablecoin infrastructure integrates with traditional payment methods to serve merchant needs across emerging markets.

Explore how stablecoin settlement fits into your payment architecture.

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.