DEV Community: Afriex

Your Neobank Doesn't Need a Crypto Feature. It Needs Better Rails.

0xSonOfUri — Fri, 25 Sep 2026 10:35:13 +0000

How stablecoins are becoming part of the infrastructure behind the next generation of global neobanks.

A neobank can make banking feel incredibly simple.

Open an account.

Receive money.

Convert currencies.

Send money.

Spend.

The interface can be reduced to a few screens and a handful of buttons.

But behind that simplicity is a much harder problem.

Money still has to move.

It has to cross borders, settle between institutions, pass through liquidity providers, convert between currencies, reach local payment rails, and eventually arrive in the customer's account.

For a neobank operating across multiple markets, the complexity grows quickly.

This is where stablecoins become interesting.

Not because every neobank needs to become a crypto company.

Not because customers necessarily want to interact with blockchains.

But because stablecoins introduce another way to move and settle value across the financial system.

The question for neobanks is therefore not simply:

"Should we add crypto?"

A better question is:

"Can stablecoins become one of the rails underneath the financial experience we are already building?"

The Neobank UX Is Simple. The Money Movement Isn't

When a customer sends $1,000 internationally, they don't think about the infrastructure behind the transaction.

They think:

Send $1,000 → recipient receives money.

The neobank, however, may have to deal with:

Funding
FX conversion
Liquidity
Payment routing
Banking partners
Correspondent relationships
Local payment rails
Settlement
Reconciliation
Compliance
Transaction monitoring
Failed payments and retries

The customer sees a transfer.

The neobank operates a financial orchestration layer.

That difference is important.

The value of a neobank is not simply putting a nicer interface on top of banking.

It is abstracting a complicated financial system into a product that feels simple.

And as neobanks become more global, that abstraction becomes harder.

Neobanks Were Built to Hide Banking Infrastructure

Traditional banking infrastructure was not designed around the experience of a modern software product.

Moving money internationally can involve multiple institutions, currencies, settlement systems, and intermediaries.

A modern neobank wants something different.

It wants to give a developer or product team an abstraction like:

Send money
Receive money
Convert money
Hold money
Pay someone

The infrastructure underneath should handle the complexity.

This is the same reason modern software companies rely on APIs and cloud infrastructure rather than building every underlying system themselves.

The neobank becomes the experience layer.

The infrastructure provider becomes the execution layer.

And increasingly, stablecoins can become part of that execution layer.

Stablecoins Change the Settlement Conversation

Stablecoins are often introduced as a crypto product.

For financial infrastructure, their more interesting property is simpler:

They are digital representations of value that can move on blockchain networks.

That creates a potential settlement mechanism that operates differently from traditional banking rails.

A simplified cross-border flow could look like:

USD
 │
 ▼
Stablecoin
 │
 ▼
Blockchain Settlement
 │
 ▼
Stablecoin Liquidity
 │
 ▼
Local Currency
 │
 ▼
Local Payment Rail
 │
 ▼
Customer

The customer does not necessarily need to see any of this.

They may simply see:

$1,000 sent → local currency received.

The blockchain is infrastructure.

The neobank remains the product.

That distinction matters.

Stablecoins Don't Replace the Neobank

A common mistake is to think that adopting stablecoins means rebuilding the entire financial product around crypto.

It doesn't have to.

A neobank can continue to own the parts customers actually interact with:

Accounts
Balances
Cards
Transfers
Payments
Beneficiaries
Notifications
Customer support
Compliance and identity
Financial controls

Stablecoins can sit underneath some of these experiences.

For example, a neobank could potentially use stablecoin infrastructure for:

Cross-border settlement
Treasury transfers
Liquidity movement
International payouts
Internal value movement between markets

The customer doesn't necessarily need a wallet.

They don't necessarily need to know what chain was used.

They may not even know that a stablecoin was involved.

This is arguably where stablecoins become most interesting for mainstream financial products:

when the blockchain disappears behind the interface.

Three Places Stablecoins Matter to Neobanks

1. Cross-Border Settlement

Global neobanks eventually run into the same problem:

How do we move money efficiently between countries?

Traditional international payment infrastructure can involve multiple intermediaries and settlement processes.

Stablecoins introduce another path for transferring value between systems.

The architecture could look like:

Market A
USD
 │
 ▼
Stablecoin
 │
 ▼
Global Settlement
 │
 ▼
Stablecoin
 │
 ▼
Market B
Local Currency

The local customer experience can remain entirely fiat-based.

This creates an important architectural possibility:

Global settlement does not have to look like local banking.

A neobank can potentially use different rails for different parts of the transaction.

2. Treasury and Liquidity

A global neobank has another problem that customers rarely see:

Where should liquidity sit?

If a company operates across multiple markets, it has to manage money across different currencies and financial systems.

Treasury teams have to think about:

Currency exposure
Liquidity requirements
Settlement timing
Funding accounts
FX conversion
Capital movement

Stablecoins can become another instrument for moving liquidity between markets.

Instead of thinking only in terms of:

Bank A → Bank B

the infrastructure can potentially support:

Bank A
   ↓
Stablecoin
   ↓
Liquidity Layer
   ↓
Bank B

The goal isn't to make treasury "crypto."

The goal is to make treasury more programmable and flexible.

3. Global Payouts

Consider a neobank paying thousands of users, merchants, contractors, or suppliers across different countries.

The payout experience should be simple:

Recipient
Amount
Currency
Send

But the infrastructure needs to determine:

Which rail should be used?
Where should the funds come from?
Which currency should be converted?
What liquidity is available?
How should the transaction settle?
How should it be reconciled?

Stablecoins can become one component in that routing and settlement system.

The important concept is rail abstraction.

The customer asks for an outcome.

The infrastructure chooses the mechanism.

The Neobank of the Future May Be Rail-Agnostic

A neobank shouldn't necessarily be defined by the payment rail it uses.

It should be defined by the financial experience it provides.

Underneath the experience, there may be:

ACH
SEPA
SWIFT
Local bank transfers
Mobile money
Card networks
Stablecoins
Other emerging settlement networks

A customer should not have to care.

They should be able to say:

"Send $500 to this person."

The infrastructure determines how to execute it.

That means the modern payment stack starts to look less like a collection of individual payment products and more like an orchestration layer.

                     NEOBANK APP
                         │
          ┌──────────────┼──────────────┐
          │              │              │
       Accounts        Cards         Payments
          │              │              │
          └──────────────┼──────────────┘
                         │
                 PAYMENT ORCHESTRATION
                         │
          ┌──────────────┼──────────────┐
          │              │              │
      Bank Rails      Stablecoins      FX
          │              │              │
          └──────────────┼──────────────┘
                         │
                 LOCAL PAYMENT RAILS
                         │
                      CUSTOMER

The stablecoin is not necessarily the product.

It is a rail.

The New Neobank Stack

This leads to a broader way of thinking about financial infrastructure.

A modern neobank may have several layers:

┌──────────────────────────────────┐
│        CUSTOMER EXPERIENCE       │
├──────────────────────────────────┤
│          NEOBANK APP             │
├──────────────────────────────────┤
│     FINANCIAL ORCHESTRATION      │
├──────────────────────────────────┤
│ Banking │ Stablecoins │ FX │ API │
├──────────────────────────────────┤
│      GLOBAL PAYMENT RAILS        │
├──────────────────────────────────┤
│ Accounts │ Liquidity │ Settlement│
└──────────────────────────────────┘

The application layer is what customers see.

The infrastructure layer is what makes the experience possible.

Stablecoins increasingly belong in the conversation about that infrastructure layer.

What Neobanks Should Actually Ask

The strategic question shouldn't be:

"Should we add a crypto feature?"

That frames stablecoins as a consumer product decision.

A more useful set of questions is:

Can we settle cross-border transactions more efficiently?
Can we reduce dependency on unnecessary intermediaries?
Can we move liquidity between markets more easily?
Can we support more currencies and markets?
Can we make treasury operations more programmable?
Can we reconcile fiat and digital settlement flows?
Can we route transactions across multiple rails?
Can we hide infrastructure complexity from customers?

These questions are much closer to the real opportunity.

The objective isn't to make customers use crypto.

The objective is to make money movement better.

The Hard Part Isn't Stablecoins

There is a temptation to think that once a company has access to stablecoins, the infrastructure problem is solved.

It isn't.

Stablecoin movement is only one component of a much larger financial system.

A global neobank still needs:

Stablecoin Liquidity
        │
        ▼
      FX
        │
        ▼
Local Accounts
        │
        ▼
Local Payment Rails
        │
        ▼
Settlement
        │
        ▼
Reconciliation
        │
        ▼
Customer Balance

Every layer matters.

A fast settlement mechanism is not enough if the money cannot reach the customer's local bank account.

A great FX rate is not enough if liquidity is unavailable.

A local account is not enough if the business cannot reconcile thousands of transactions.

The infrastructure has to work as a system.

This is where payment infrastructure providers become important.

Infrastructure Is Becoming the Product

The next generation of financial companies may not build every component themselves.

They will compose infrastructure.

A neobank can focus on:

Customer experience
Product design
Distribution
Brand
Financial products
Customer relationships

While infrastructure providers handle increasingly complex capabilities such as:

Global collections
Local accounts
Payouts
FX
Treasury
Liquidity
Settlement

Afriex's AFX platform is positioned around this broader infrastructure problem, providing businesses with capabilities for global collections, programmable payouts, local bank accounts, and FX/treasury management through its platform and APIs.

For a neobank, the value of this model is not simply "having an API."

It is being able to connect the pieces required to operate a global money product without building every financial rail from scratch.

Stablecoins Are Part of a Larger Convergence

The interesting future is not necessarily:

Banks vs. crypto.

It may be:

Banking infrastructure + stablecoins + APIs + local payment rails.

The boundaries between these systems are becoming less important.

A customer may hold a dollar balance.

A business may fund that balance through a bank transfer.

The neobank may move value through a stablecoin.

A local partner may settle the final amount into a bank account.

The user simply sees:

Money arrived.

That is the abstraction financial infrastructure should provide.

The Global Neobank Needs Better Rails

Neobanks started by making banking software-first.

The next phase is making global money movement software-first.

That requires infrastructure that can operate across:

Currencies
Countries
Banking systems
Payment rails
Liquidity pools
Settlement networks

Stablecoins are not the answer to every financial infrastructure problem.

But they introduce a new primitive for moving and settling value.

And that primitive is increasingly relevant to companies building financial products for a world where money needs to move globally, instantly, and programmatically.

The neobank of the future doesn't necessarily need to look like a crypto company.

It may simply use crypto infrastructure where it makes the underlying financial system work better.

Your neobank doesn't need a crypto feature. It needs better rails.

And stablecoins may become one of those rails.

Afriex Integrations: Sandbox, Idempotency, and Webhook Simulation

Victory Lucky — Mon, 21 Sep 2026 19:50:13 +0000

Most payment integration bugs never show up in a manual test. You click through the happy path once, it works, you ship it. Then in production a network blip causes a retry, two webhook deliveries arrive out of order, or a duplicate request slips through — and now you're debugging a double payout at the worst possible time.

63% of async API failures stem from race conditions invisible to synchronous testing tools. Payment APIs are almost entirely asynchronous — a transaction returns PENDING, then changes state later via webhook — which means the bugs that matter most are exactly the ones a quick manual test will never catch.

This guide covers how to actually test an Afriex integration: sandbox setup, idempotency verification, and simulating webhook events without waiting for a real transaction to change state.

Set up your sandbox environment

Everything starts in the staging environment. No approval process, no waiting — sign up at business.afriex.com, grab your sandbox API key, and you have a fully working test environment immediately.

export const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY!,
  environment: "staging",
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
});

Keep a completely separate API key and webhook public key for staging versus production. Never test against production, even by accident — a hardcoded environment: "production" in a test file is a classic way to make a real transaction during a test run.

Testing idempotency: verify the effect, not just the response

A repeated 200 or 201 response is not enough evidence that idempotency works. An API can return a reassuring response while creating a duplicate record underneath. The test needs to check the actual downstream effect — was exactly one transaction created — not just what the response looked like.

Here's the pattern:

import { afriex } from "@/lib/afriex";

async function testIdempotency() {
  const reference = `test-idem-${Date.now()}`;
  const idempotencyKey = `idem-${reference}`;

  const payload = {
    type: "WITHDRAW" as const,
    customerId: "test-customer-id",
    destinationId: "test-payment-method-id",
    sourceAmount: "10",
    destinationAmount: "10",
    sourceCurrency: "USD",
    destinationCurrency: "NGN",
    meta: { reference, idempotencyKey },
  };

  // Fire the same request twice with the same idempotency key
  const first = await afriex.transactions.create(payload);
  const second = await afriex.transactions.create(payload);

  // The real assertion: both calls return the SAME transaction ID
  console.assert(
    first.transactionId === second.transactionId,
    "Idempotency failed — two different transaction IDs were created"
  );

  // Confirm only one transaction actually exists for this reference
  const allTransactions = await afriex.transactions.list({ type: "WITHDRAW" });
  const matching = allTransactions.data.filter(
    (t) => t.meta?.reference === reference
  );

  console.assert(
    matching.length === 1,
    `Expected exactly 1 transaction, found ${matching.length}`
  );
}

This test proves the actual invariant that matters: repeated delivery of one logical write produces no more than one committed effect. Checking transactionId equality across both calls, then confirming only one record exists in the list, is what separates a real idempotency test from one that just checks for a 200.

Also test the negative case — the same key with a genuinely different payload should be rejected, not silently accepted as a new request or silently merged with the original:

async function testIdempotencyKeyReuse() {
  const idempotencyKey = `idem-reuse-test-${Date.now()}`;

  await afriex.transactions.create({
    type: "WITHDRAW",
    customerId: "test-customer-id",
    destinationId: "test-payment-method-id",
    sourceAmount: "10",
    destinationAmount: "10",
    sourceCurrency: "USD",
    destinationCurrency: "NGN",
    meta: { reference: "ref-1", idempotencyKey },
  });

  // Same key, different amount — this should be rejected, not silently accepted
  try {
    await afriex.transactions.create({
      type: "WITHDRAW",
      customerId: "test-customer-id",
      destinationId: "test-payment-method-id",
      sourceAmount: "50", // different amount
      destinationAmount: "50",
      sourceCurrency: "USD",
      destinationCurrency: "NGN",
      meta: { reference: "ref-2", idempotencyKey }, // same key
    });
    throw new Error("Expected an error for key reuse with different payload");
  } catch (error) {
    // This is the expected path
  }
}

Run this in your CI pipeline against sandbox, not just once manually. A regression here is exactly the kind of bug that passes code review and fails in production three months later.

Simulating concurrent retries

The scenario that actually breaks systems in production: your disbursement worker calls transactions.create, the network times out before your code sees the response, your retry logic fires a second call with the same idempotency key — but what if both requests hit Afriex at nearly the same moment, not sequentially?

async function testConcurrentIdempotentRequests() {
  const idempotencyKey = `idem-concurrent-${Date.now()}`;
  const payload = {
    type: "WITHDRAW" as const,
    customerId: "test-customer-id",
    destinationId: "test-payment-method-id",
    sourceAmount: "20",
    destinationAmount: "20",
    sourceCurrency: "USD",
    destinationCurrency: "NGN",
    meta: { reference: `concurrent-${Date.now()}`, idempotencyKey },
  };

  // Fire both requests at the same time, not sequentially
  const [resultA, resultB] = await Promise.all([
    afriex.transactions.create(payload),
    afriex.transactions.create(payload),
  ]);

  console.assert(
    resultA.transactionId === resultB.transactionId,
    "Concurrent requests with the same idempotency key produced different transactions"
  );
}

This is the test most teams skip because it requires deliberately racing two requests against each other, rather than just calling an endpoint twice in sequence. It is also the test that catches the bug a sequential test cannot — a race condition only shows up in reality when requests actually overlap.

Simulating webhooks without waiting for real transactions

Waiting for a real transaction to move through PENDING → PROCESSING → COMPLETED in sandbox to test your webhook handler is slow and unreliable. Afriex's SDK gives you a way to fire a real, signed webhook on demand against an existing sandbox entity.

// Trigger a real signed webhook event for an existing sandbox transaction
await afriex.webhooks.triggerTestWebhook({
  event: "TRANSACTION.UPDATED",
  entityId: "existing-sandbox-transaction-id",
});

Because this fires a genuinely signed payload to your configured webhook URL, your signature verification code runs exactly as it would with a real event — this is not a mocked payload, it is the same delivery mechanism Afriex uses in production. To receive it locally, expose your dev server with a tunnel:

npx ngrok http 3000

Register the ngrok HTTPS URL as your webhook URL in the sandbox dashboard, then trigger events for every status your handler needs to process:

const statusesToTest = [
  "TRANSACTION.CREATED",
  "TRANSACTION.UPDATED", // fire this with different underlying statuses
];

for (const event of statusesToTest) {
  await afriex.webhooks.triggerTestWebhook({
    event,
    entityId: "existing-sandbox-transaction-id",
  });
}

Test the handler against COMPLETED, FAILED, IN_REVIEW, and RETRY specifically. These four are the ones most often mishandled — IN_REVIEW and RETRY are not failures and should never trigger a failure notification, but a handler that has only been tested against the happy path will often get this wrong.

Testing webhook idempotency (not just transaction idempotency)

Afriex retries webhook delivery up to 12 times with exponential backoff. Your handler will receive the same event more than once by design. Test this explicitly:

async function testWebhookIdempotency(payload: WebhookPayload) {
  // Process the same webhook payload twice
  await processWebhookEvent(payload);
  await processWebhookEvent(payload); // simulate a redelivery

  // Assert the side effect only happened once
  const notificationCount = await countNotificationsSent(payload.data.transactionId);
  console.assert(
    notificationCount === 1,
    `Expected 1 notification, sent ${notificationCount}`
  );
}

If your webhook handler sends an email or updates a balance on every delivery without checking whether it already processed that event, a retried webhook will double the side effect even though the underlying transaction only happened once.

What a full test suite for an Afriex integration should cover

Test	What it proves
Same idempotency key, same payload, called twice	Returns the same transaction, no duplicate created
Same idempotency key, different payload	Rejected, not silently accepted
Same idempotency key, concurrent calls	Race condition does not produce two transactions
Webhook signature verification	Invalid signature is rejected before any processing
Webhook redelivery	Side effects (emails, balance updates) happen exactly once
Each terminal status (`COMPLETED`, `FAILED`, `REJECTED`)	Handler takes the correct action for each
Non-terminal statuses (`IN_REVIEW`, `RETRY`, `PROCESSING`)	Handler does not treat these as failures
Rate fetch before transaction creation	Displayed rate matches what the transaction actually uses

Build this as an actual test file that runs in CI against sandbox, not a manual checklist you run once before a release. The bugs this catches are exactly the ones that are invisible until a specific, rare sequence of events happens in production — which is precisely when you don't want to be debugging them for the first time.

When Money Becomes Infrastructure

0xSonOfUri — Sat, 12 Sep 2026 06:45:51 +0000

Part II of a two-part series on the infrastructure behind global money movement.

In Part I, we explored a simple question:

Why is sending money across borders still so much harder than sending a message?

The answer was that money does not simply move.

Behind every international transfer are institutions, networks, currencies, compliance systems, liquidity providers, settlement processes, and technical infrastructure.

But something important is changing.

For decades, accessing this infrastructure required becoming part of the financial system itself. A company that wanted to move money needed relationships with banks, payment processors, settlement partners, and regulatory institutions.

Today, a growing number of those capabilities are becoming accessible as infrastructure.

Through APIs.

Through programmable accounts.

Through wallet systems.

Through stablecoin rails.

Through embedded financial services.

This changes the question for builders.

The question is no longer only:

How does money move?

Increasingly, the question is:

What can we build when money movement becomes programmable infrastructure?

That shift has implications far beyond payments.

It changes how companies think about financial products.

It changes what developers can build.

And it may fundamentally change who gets to participate in the global financial system.

This is where the story continues.

From Financial Institutions to Financial Infrastructure

Historically, financial capabilities were tightly coupled with financial institutions.

If you wanted to provide banking services, you needed to be a bank.

If you wanted to issue payment cards, you needed deep relationships with card networks and issuing banks.

If you wanted to move money internationally, you needed access to correspondent banking networks and settlement relationships.

The infrastructure was largely inaccessible to ordinary builders.

That model made sense.

Financial systems are complicated.

They involve trust, regulation, risk management, liquidity, identity verification, fraud prevention, and settlement.

But the internet has repeatedly shown what happens when complex infrastructure becomes accessible through abstractions.

Consider computing.

A company once needed to purchase physical servers, build data centers, maintain hardware, and employ teams responsible for infrastructure.

Today, a developer can deploy an application in minutes.

They do not need to own a data center.

They use infrastructure.

Cloud computing separated:

the people building products

from

the people operating the underlying infrastructure.

A similar transformation is happening in financial technology.

Companies increasingly do not need to build every financial capability themselves.

They can integrate infrastructure.

The API Changed What Software Could Become

An API is, at its simplest, a way for one software system to communicate with another.

But APIs have done something much bigger than enable communication.

They have turned infrastructure into building blocks.

A developer does not need to understand how an entire cloud provider operates to deploy an application.

They use an API.

A developer does not need to build a mapping network to display a map.

They use an API.

A developer does not need to build a messaging network to send a notification.

They use an API.

The same abstraction is increasingly appearing in finance.

Instead of building:

account provisioning systems
payment routing infrastructure
wallet technology
currency conversion systems
payout networks
transaction monitoring tools

companies can integrate specialized infrastructure.

This does not mean the complexity disappears.

It means the complexity can be handled at a different layer.

And that distinction matters.

The company building the customer experience can focus on the product.

The infrastructure provider can focus on the rails.

Financial Services Are Becoming Composable

One of the most important ideas in modern software is composability.

Instead of building everything from scratch, developers combine specialized services.

A modern software product might use:

cloud infrastructure from one provider
authentication from another
messaging from another
analytics from another
payment processing from another

The final product feels like one application.

But behind the scenes, it is composed from multiple infrastructure layers.

Finance is increasingly moving in the same direction.

A financial product can combine capabilities such as:

customer onboarding
identity verification
virtual accounts
wallet infrastructure
foreign exchange
stablecoin settlement
collections
payouts
transaction monitoring

Each capability can be provided by specialized infrastructure.

The result is something powerful.

Financial products no longer need to be built as entirely self-contained financial institutions.

They can be assembled.

The Difference Between Building Rails and Building Products

This distinction is easy to miss.

There is a major difference between building financial infrastructure and building a financial product.

Financial infrastructure might include:

settlement networks
banking connections
custody systems
liquidity infrastructure
payment rails
ledger systems

A financial product might include:

a freelancer payment platform
a global payroll tool
a marketplace
a remittance application
a creator economy product
a treasury management dashboard

The product does not necessarily need to own the rails.

It needs to solve a customer problem.

That creates an important shift in how founders and developers think.

Imagine a company building a marketplace for international businesses.

Its customers need to:

receive payments
hold balances
convert currencies
pay suppliers
track transactions

The company could attempt to build all the underlying infrastructure itself.

Or it could focus on the experience that connects those capabilities.

The second approach allows the company to spend more time solving its actual problem.

This is one of the biggest opportunities created by financial infrastructure.

Builders can focus on:

What should happen for the customer?

rather than starting with:

How do we rebuild the entire financial system?

Embedded Finance Changes the Product Surface

Financial services are no longer limited to traditional financial applications.

A company does not have to call itself a bank to include financial capabilities in its product.

A marketplace can offer payouts.

A logistics platform can offer payment collection.

A freelancer platform can help users receive international payments.

A software company can provide wallets.

A business platform can provide expense management.

A commerce platform can facilitate settlement.

This is commonly described as embedded finance.

The financial capability is embedded inside another product.

The user may not even think of the product as a financial application.

They simply see a feature that helps them complete a task.

For example:

A creator uses a platform.

The platform helps them receive money.

The creator does not necessarily care which settlement partner is involved.

They care that the money arrives.

A business owner uses a dashboard.

The dashboard helps them pay a supplier.

The business owner does not necessarily want to understand the infrastructure behind the transaction.

They want the payment to work.

This is an important principle.

The best infrastructure often becomes invisible to the end user.

Money Is Becoming Programmable

The next major shift is programmability.

Traditional money movement often follows predefined processes.

A person initiates a payment.

The payment moves through a network.

The receiving party receives the funds.

But programmable financial infrastructure makes it possible for software to participate more deeply in financial workflows.

Software can potentially determine:

when a payment should happen
where funds should be routed
which currency should be used
which account should receive funds
how transactions should be categorized
when balances should trigger an action

This turns money movement into something applications can orchestrate.

Consider payroll.

A company might traditionally perform payroll through a series of manual processes.

With programmable infrastructure, a system could potentially:

calculate payments
initiate transfers
route funds
notify recipients
reconcile transactions
generate reports

The financial transaction becomes part of a larger software workflow.

This is the important shift.

The payment is no longer an isolated event.

It becomes a component.

APIs Turn Financial Actions Into Software Primitives

Developers think in primitives.

A database provides a way to store information.

An authentication service provides a way to identify users.

A cloud provider provides a way to deploy applications.

Financial infrastructure is increasingly exposing similar primitives.

For example:

Create an account.

Create a wallet.

Receive funds.

Convert currency.

Send a payout.

Check a balance.

Retrieve a transaction.

These actions can become building blocks inside applications.

Once that happens, financial capabilities can be integrated into workflows that were previously impossible or extremely expensive to build.

Imagine a business management platform.

The product already knows:

who the customer is
what they purchased
how much they owe
when payment is due

Adding financial infrastructure allows the same platform to participate in the movement of money associated with those activities.

The software does not just record the business.

It can potentially help execute the business.

The Rise of Financial Operating Systems

As more financial capabilities become programmable, companies are beginning to build something larger than payment products.

They are building financial operating systems.

These products bring multiple activities into one environment.

A business might be able to:

collect payments
manage balances
make payouts
monitor transactions
manage currencies
automate workflows
reconcile financial activity

The value is not necessarily any individual feature.

The value comes from coordination.

Financial activity is often fragmented.

A business may use:

one platform for receiving money
another for sending payments
another for accounting
another for foreign exchange
another for treasury

Every additional system creates friction.

More logins.

More reconciliation.

More operational processes.

More data moving between platforms.

Infrastructure can make it possible to bring some of these capabilities closer together.

That does not mean one company will replace the entire financial ecosystem.

But it does mean products can create more unified experiences.

Stablecoins Introduce a New Infrastructure Layer

Stablecoins are becoming an important part of this conversation.

Not because every user wants to interact with crypto.

Most users do not want to think about:

blockchains
gas fees
private keys
smart contracts

They want to move money.

The significance of stablecoins is therefore often not the user interface.

It is the infrastructure layer underneath.

A stablecoin can potentially provide a digital representation of value that moves across internet-native networks.

This creates new possibilities for:

treasury movement
settlement
liquidity
cross-border transfers
programmable financial workflows

A customer might interact with a completely familiar experience.

They might simply see:

Send $500.

Behind the scenes, however, the infrastructure may involve multiple layers.

For example:

Customer Initiates Payment
          ↓
Collection Infrastructure
          ↓
Currency Conversion
          ↓
Settlement Layer
          ↓
Liquidity Movement
          ↓
Local Payout Network
          ↓
Recipient Receives Funds

In some systems, stablecoin infrastructure may play a role somewhere in that process.

The user does not necessarily need to see it.

And that may be one of the most important lessons.

Infrastructure does not need to become the product.

The Customer Should Not Have to Care About the Rails

There is a tendency in technology to make the underlying technology the main story.

But users rarely care about infrastructure for its own sake.

Nobody opens a ride-sharing application because they are excited about GPS APIs.

Nobody sends an email because they are fascinated by SMTP.

Nobody watches a movie because they want to experience a content delivery network.

They care about the outcome.

Financial products should be thought about in the same way.

The customer wants to:

get paid
send money
receive money
pay someone
manage their business
access their funds

The underlying infrastructure should support those outcomes.

The better the infrastructure works, the less the customer may notice it.

That does not reduce the importance of infrastructure.

It increases it.

Because invisible infrastructure still has to be reliable.

Global Money Requires Local Reality

One of the hardest problems in global payments is that the world is simultaneously connected and fragmented.

The internet is global.

Financial systems are often local.

Different countries have:

different currencies
different regulations
different banking systems
different payment preferences
different identity requirements
different settlement networks

A global product cannot simply treat every market as identical.

A user in Nigeria may have different payment expectations from a user in the United States.

A business in Kenya may operate differently from a business in the United Kingdom.

A customer in Ghana may prefer a different financial workflow from a customer in Europe.

This means global infrastructure needs to understand local systems.

The challenge is not simply:

Connect every country.

It is:

Connect different financial realities without forcing every user to understand the complexity.

That is a much harder problem.

The Infrastructure Layer Has to Translate Complexity

Imagine two businesses in different countries.

They may use different currencies.

They may have accounts with different institutions.

They may use different local payment networks.

They may operate under different regulatory environments.

Yet the product experience should ideally feel simple.

The infrastructure layer becomes a translator.

It translates:

one system into another.

It translates:

one currency into another.

It translates:

one network into another.

It translates:

complex processes into simple actions.

This is why financial infrastructure is difficult to build.

The complexity has not disappeared.

Someone still has to manage:

liquidity
settlement
compliance
risk
network relationships
reconciliation

The difference is where that complexity lives.

Good infrastructure allows product builders to access complicated capabilities without recreating the entire underlying system.

What This Means for Developers

For developers, the opportunity is enormous.

A generation ago, building a global financial product required a massive organization.

Today, a small engineering team can begin with infrastructure.

That does not mean building financial products is easy.

Far from it.

Financial applications still require careful thinking about:

security
authentication
compliance
user experience
transaction states
error handling
reconciliation

But the starting point has changed.

Developers can spend less time asking:

How do I build a payment network?

and more time asking:

What financial problem is currently poorly solved?

That is where innovation happens.

The infrastructure enables the product.

But the product creates the value.

The Best Opportunities Are Often Workflow Problems

Payments alone are rarely the complete problem.

The real opportunity is often the workflow surrounding the payment.

Consider an international freelancer.

Their problem may not simply be:

I need to receive money.

Their actual workflow might involve:

finding clients
invoicing
receiving payments
converting currencies
managing balances
tracking income

A payment feature solves one part of the workflow.

A well-designed product can solve the larger problem.

The same is true for businesses.

A business does not merely need to send a payment.

It may need to:

approve the payment
schedule it
assign it to a department
track it
reconcile it
report it

This is why infrastructure creates opportunities for vertical products.

The financial action becomes part of a specialized workflow.

Programmable Money Creates Automation Opportunities

Once financial actions become accessible through software, automation becomes increasingly important.

Imagine a company that regularly pays contractors.

Instead of manually initiating every payment, a system could potentially automate parts of the workflow.

For example:

Work Completed
      ↓
Manager Approval
      ↓
Invoice Verified
      ↓
Payment Scheduled
      ↓
Funds Sent
      ↓
Transaction Recorded
      ↓
Recipient Notified

The payment itself is only one step.

The larger workflow is where automation creates value.

The same concept can apply to:

payroll
vendor payments
subscriptions
marketplace settlements
recurring collections
treasury operations

Financial infrastructure allows money movement to become connected to business logic.

That is a major change.

The Future May Belong to Orchestration

As infrastructure providers become more specialized, another category becomes increasingly important.

The orchestrator.

An orchestrator does not necessarily own every rail.

It coordinates them.

Imagine a product with access to multiple capabilities.

It may have:

different payment methods
multiple currencies
several payout networks
multiple liquidity sources

The challenge becomes choosing how to coordinate them.

Which route should be used?

Which currency should be selected?

Which provider is available?

How should failures be handled?

How should the transaction be tracked?

The orchestration layer creates intelligence around infrastructure.

This may become one of the most important areas of financial technology.

The future is not necessarily one network replacing every other network.

It may be better coordination between networks.

Why Reliability Matters More Than Novelty

Moving money is different from many other software problems.

A social application can survive a minor interface bug.

A payment application can lose trust.

If a user sends money, they expect:

the transaction to be processed correctly
the amount to be accurate
the recipient to receive the funds
the status to be clear

Financial infrastructure therefore needs a different level of discipline.

The user experience must account for uncertainty.

What happens when:

a network is unavailable?
a transaction is pending?
a payout fails?
a recipient cannot receive funds?
a conversion rate changes?
a transfer requires additional review?

These questions are not edge cases.

They are part of the product.

The best financial products do not pretend complexity does not exist.

They manage complexity without exposing unnecessary complexity to the customer.

Trust Is Infrastructure Too

When we talk about infrastructure, we often think about technology.

Servers.

Networks.

APIs.

Databases.

But financial infrastructure also depends on trust.

Users need to trust that:

their money is safe
transactions are accurately recorded
balances are correct
sensitive information is protected
problems can be resolved

Trust is built through technology.

But it is also built through operations.

Through transparency.

Through reliability.

Through customer support.

Through clear communication.

This means a company cannot simply integrate an API and declare that it has solved finance.

Infrastructure creates capabilities.

Trust creates adoption.

The Infrastructure Opportunity Is Bigger Than Payments

Payments are one of the most visible applications of financial infrastructure.

But the opportunity extends much further.

Programmable financial infrastructure can support:

Global Payroll

Companies increasingly work with people across borders.

Infrastructure can help support systems that manage international compensation.

Marketplaces

Marketplaces need to collect money from one side of the platform and distribute it to another.

Financial infrastructure can simplify those flows.

Creator Economies

Creators increasingly operate internationally.

Products can help them receive, manage, and move money.

Business Operations

Businesses need tools for:

collections
payouts
expenses
reconciliation
reporting

Treasury Management

Companies operating internationally may need to manage multiple currencies and liquidity positions.

Embedded Financial Products

Software companies can integrate financial capabilities directly into their existing products.

The common pattern is simple.

Everywhere there is a financial workflow, there may be an infrastructure opportunity.

From Access to Innovation

The biggest consequence of infrastructure is not that it makes existing products easier to build.

It makes new products possible.

When a capability becomes easier to access, more people experiment with it.

Cloud infrastructure created millions of software companies that would never have built their own data centers.

Mobile platforms created businesses that would never have existed without smartphones.

Financial infrastructure may create a similar wave.

The important thing is access.

When a small team can access capabilities that previously required massive organizations, the range of possible products expands.

A founder does not need to begin by asking:

Do we have the resources to become a financial institution?

They can begin with:

What experience should exist that does not exist today?

That is a much more interesting question.

Where Afriex Fits Into This Story

The story of modern financial infrastructure is ultimately about reducing the distance between an idea and a working financial product.

That is where platforms such as Afriex become relevant.

Builders and businesses do not always want to spend their time navigating the underlying complexity of money movement.

They want to build.

They want to create products.

They want to serve customers.

They want to operate across borders.

Infrastructure can provide the foundation that makes those ambitions more practical.

The goal is not necessarily to make every company become a financial institution.

The goal is to give companies access to financial capabilities so they can focus on what they do best.

This is the broader idea behind financial infrastructure.

The rails exist so that builders can build on top of them.

The Next Generation of Financial Products May Not Look Like Fintech

This may be the most interesting consequence of all.

The next generation of financial products may not describe themselves as fintech.

They may be:

commerce companies
creator platforms
business software products
marketplaces
logistics platforms
workforce platforms

Financial capabilities will simply be part of what they do.

A company might say:

We help businesses manage suppliers.

And somewhere inside the product is payment infrastructure.

Another company might say:

We help creators run their businesses.

And somewhere inside the product is a financial layer.

The financial capability becomes embedded inside the customer experience.

This is how infrastructure changes industries.

It stops being a separate category.

It becomes a capability.

The Real Shift Is Happening Beneath the Surface

Consumers may not notice the transformation immediately.

They will simply notice that products become more capable.

Payments may become faster.

Global products may become easier to access.

Businesses may automate more of their financial operations.

Developers may build things that previously required large financial organizations.

The transformation is happening beneath the surface.

APIs.

Networks.

Wallets.

Settlement systems.

Liquidity.

Stablecoins.

Compliance technology.

All of these layers are contributing to a new financial stack.

The customer sees an application.

The builder sees an API.

The infrastructure provider sees a network.

Together, they create a financial experience.

Final Thoughts

In Part I, we explored why moving money across borders is complicated.

The answer was simple.

The world is financially fragmented.

Different currencies.

Different networks.

Different regulations.

Different institutions.

Moving money requires coordination between all of them.

In Part II, we explored what happens when that coordination becomes accessible as infrastructure.

The answer is equally significant.

Builders get more leverage.

Companies can focus more on products.

Financial capabilities become programmable.

Money movement becomes part of software workflows.

And new categories of businesses become possible.

The future of finance may not be about everyone becoming a bank.

It may be about more builders gaining access to the capabilities that banks and financial institutions have historically controlled.

That is what infrastructure changes.

It takes something complicated.

It creates an abstraction.

And then it gives more people the ability to build.

The rails may remain invisible.

But what gets built on top of them could change everything.

Part I: The Hidden Complexity of Moving Money Across Borders

Part II: When Money Becomes Infrastructure

The Hidden Complexity of Moving Money Across Borders

0xSonOfUri — Sat, 12 Sep 2026 06:31:12 +0000

Why sending money from one country to another is still harder than sending a message and the infrastructure working behind the scenes

Sending money should be simple.

Open an app. Enter a recipient. Choose an amount. Press Send.

A few seconds later, someone on the other side of the world receives a notification.

From the user's perspective, that is the entire experience.

But behind that single button is one of the most complex systems humanity has ever built.

Moving money across borders can involve multiple financial institutions, currencies, payment networks, compliance systems, liquidity providers, settlement arrangements, foreign exchange markets, treasury operations, and local payout infrastructure.

The experience may take seconds.

The infrastructure behind it has been developing for decades.

And that creates an interesting contradiction.

We live in a world where information can travel globally almost instantly. A message sent from Lagos can reach London, Nairobi, New York, or Accra in milliseconds. Software can be deployed globally. A video can be streamed across continents. A company can serve millions of customers in dozens of countries from a single application.

But moving value is different.

Sending money from one country to another is still far more complicated than sending information.

Why?

Because the internet standardized the movement of information.

The global financial system did not develop as one unified network.

It developed country by country.

Bank by bank.

Currency by currency.

Regulation by regulation.

That history still shapes how money moves today.

In this article, we will look beneath the simple experience of a cross-border payment and explore the hidden infrastructure involved in moving money around the world.

This is not a guide to sending money.

It is a look at the systems working behind the Send button.

1. Money Doesn't Move the Way Most People Think

When most people imagine sending money internationally, they imagine something physical moving from one place to another.

Something like this:

You
  ↓
Your Money
  ↓
Recipient

In reality, financial systems are usually more complicated.

A cross-border payment can involve the communication of payment instructions, changes to balances, settlement between institutions, foreign exchange conversions, and the coordination of liquidity.

The important point is this:

A payment is not always as simple as taking money from one location and physically moving it to another.

Financial institutions maintain records of who owns what. They maintain balances. They maintain obligations to one another. They communicate instructions. They settle transactions. They manage liquidity.

A customer sees:

Send $100

The infrastructure may see something closer to:

Payment Instruction
        ↓
Authorization
        ↓
Compliance Checks
        ↓
Currency Conversion
        ↓
Liquidity Allocation
        ↓
Settlement
        ↓
Local Payout
        ↓
Recipient Balance Updated

The exact process depends on the countries, institutions, currencies, and payment methods involved.

But the larger lesson is important.

The simplicity of a modern payment interface does not mean the underlying financial system is simple.

In fact, one of the primary jobs of modern financial infrastructure is to hide that complexity from the user.

2. A Global Economy Built on Local Financial Systems

The world feels increasingly global.

Businesses sell internationally. Teams work remotely. Families live across multiple countries. Freelancers work with clients around the world. Digital products can acquire customers almost anywhere.

But the financial systems supporting this global activity are still heavily localized.

Every country has its own financial environment.

That environment can include different:

currencies
banks
payment networks
regulations
licensing requirements
settlement systems
consumer payment habits

A person in one country may primarily use bank transfers. Someone in another market may rely heavily on mobile money. A business elsewhere may use card payments, domestic clearing systems, or other local rails.

There is no single global payment rail that every person, bank, business, and financial institution uses in exactly the same way.

Instead, cross-border money movement often requires infrastructure capable of connecting different systems.

Think about the problem.

A customer may want to pay in one currency. A business may operate in another. The recipient may want to receive a completely different currency.

The sender's financial institution and the recipient's financial institution may not even operate on the same domestic payment network.

So the challenge is not simply:

Move money from Country A to Country B.

The real challenge may be:

Connect multiple financial systems, currencies, institutions, regulatory environments, and liquidity sources in a way that produces a simple experience for the customer.

That is a very different problem.

3. The Correspondent Banking World

One of the most important concepts in international banking is correspondent banking.

Banks do not necessarily maintain direct relationships with every other bank in the world. Instead, financial institutions can rely on relationships with other institutions to facilitate international transactions.

A simplified representation might look like this:

Sender's Bank
      ↓
Correspondent Institution
      ↓
Another Financial Institution
      ↓
Recipient's Bank

In more complex cases, there can be additional intermediaries. The exact route depends on the institutions and currencies involved.

This creates a fundamental challenge.

The more systems and institutions involved in a transaction, the more coordination may be required.

Potential issues can include:

additional processing time
multiple fees
operational complexity
reconciliation requirements
limited visibility into transaction status

From the customer's perspective, the experience may simply be:

Why hasn't the money arrived yet?

But underneath that question may be multiple institutions processing instructions and settling obligations.

This is one reason cross-border payments historically developed a reputation for being slow, expensive, and difficult to track.

The problem was not that financial institutions did not know how to move money. The problem was that global financial infrastructure developed through a network of institutions that were not originally designed to function like a single, instant, consumer-facing application.

4. Sending an Instruction Is Not the Same as Settling Value

This distinction is useful when thinking about financial infrastructure.

Imagine sending a message. The message can travel from one device to another. The internet has protocols for routing information.

Money is different.

Financial systems must answer questions such as:

Who owns the value?
Which institution is responsible for the balance?
Has the transaction been authorized?
Has the transaction been settled?
Is the receiving institution able to make the funds available?
Is there sufficient liquidity in the required currency?

A payment instruction can be communicated quickly.

That does not automatically mean final settlement happens at the same speed.

This distinction between communication and settlement is one of the reasons financial infrastructure is more complicated than a simple messaging system.

A modern application may show:

Payment sent

But several processes may still need to occur behind the scenes depending on the payment method and infrastructure being used.

That is why the architecture behind a payment matters.

Speed is not simply a matter of making the user interface faster. The infrastructure responsible for authorization, settlement, liquidity, compliance, and payout also matters.

5. Every Currency Introduces Another Layer

Now add currencies to the equation.

Suppose someone wants to send money internationally.

The sender has:

Currency A

The recipient wants:

Currency B

The payment now involves more than money movement.

It may also involve foreign exchange.

Conceptually:

Currency A
     ↓
Foreign Exchange
     ↓
Currency B
     ↓
Recipient

That simple diagram hides an enormous amount of infrastructure.

Foreign exchange can involve:

exchange rates
spreads
liquidity
market availability
conversion timing
treasury management
risk management

Consider a business that receives revenue in one currency but needs to make payments in several others.

That business needs to think about more than individual transactions.

It needs to think about where its liquidity exists.

For example:

USD Balance
    ↓
Need to pay suppliers in another market
    ↓
FX Conversion Required
    ↓
Liquidity Required
    ↓
Local Payout

At a small scale, this may seem straightforward.

At a global scale, it becomes an operational challenge.

This is why foreign exchange infrastructure is an essential part of cross-border payments.

Moving value between countries often means moving between currencies.

And moving between currencies requires someone, somewhere, to provide liquidity.

6. Liquidity: The Invisible Requirement Behind Every Payment

Liquidity is one of those financial concepts that customers rarely think about.

But infrastructure providers think about it constantly.

Imagine a company that needs to make payments in several markets. Customers may be paying the company in dollars, euros, pounds, and local currencies. Meanwhile, the company may need to make payouts in completely different currencies.

The company needs to ensure that value is available where it is needed.

That is a liquidity problem.

A simplified example:

Customers
    ↓
USD Collected
    ↓
Treasury
    ↓
Liquidity Management
    ↓
Currency Conversion
    ↓
Local Funds Available
    ↓
Payout

The recipient of the payment does not care about this process.

They care about one thing:

Did I receive my money?

That is exactly why infrastructure is valuable.

Good infrastructure hides complexity.

The user does not need to understand how liquidity was coordinated. The business does not necessarily want to manually manage every underlying financial relationship.

The infrastructure handles as much of that complexity as possible.

7. The Local Payout Problem

Sending money across a border is only half the problem.

The recipient must still receive it.

This sounds obvious.

But it introduces another layer of complexity.

How should the recipient receive funds?

Depending on the market, the answer could be:

a bank account
a mobile wallet
a digital wallet
a virtual account
another local payment method

This means that a global payment experience often requires local delivery infrastructure.

Imagine building a product that serves users across multiple countries. Your customers may expect completely different experiences.

One market might expect:

Bank Transfer

Another might expect:

Mobile Money

Another may prefer:

Wallet

The product cannot simply think globally.

It must also understand how value is delivered locally.

This is one of the central challenges of building cross-border financial products.

Global movement requires local access.

A system can be technically capable of moving value internationally, but if the recipient cannot conveniently receive that value through familiar local infrastructure, the experience is incomplete.

8. Compliance Travels With the Money

There is another reason moving money is different from sending information.

Money operates inside regulated systems.

Financial institutions have responsibilities.

Those responsibilities can include processes related to:

identity verification
anti-money laundering requirements
transaction monitoring
sanctions screening
fraud prevention
regulatory reporting

The exact requirements vary depending on the product, institution, jurisdiction, and transaction.

But the broader point is simple.

Moving money is not merely a technical problem.

It is also a regulatory and operational problem.

A developer can build a beautiful interface. A company can create an excellent user experience. But the underlying system still needs to operate responsibly within the financial environments in which it functions.

That creates a major difference between many traditional software products and financial products.

A social application can send a message.

A financial application may need to answer:

Who is sending the money?
Who is receiving it?
What is the nature of the transaction?
Does the transaction trigger additional review?
Are there restrictions that apply?

This complexity is often invisible to the user.

And ideally, much of it should be.

But it still exists.

9. Treasury Is the Operating System Behind Global Money

When people think about financial products, they often think about payments.

They think about:

Send
Receive
Pay
Withdraw

But businesses operating at scale need to think about something broader.

Treasury.

Treasury is concerned with how an organization manages its financial resources.

For a company operating across borders, that can involve questions such as:

Where is our money?
In which currencies do we hold value?
Where do we need liquidity?
How do we fund payouts?
When should we convert currencies?
How do we reconcile incoming and outgoing transactions?

A simplified global money flow might look like:

Customer Payment
        ↓
Collection
        ↓
Company Balance
        ↓
Treasury Management
        ↓
Liquidity Allocation
        ↓
Conversion
        ↓
Payout

At scale, these processes become significantly more complicated.

A company may receive money in one region while needing to make payments somewhere else. It may need to manage balances across multiple currencies. It may need visibility into incoming and outgoing transactions. It may need to reconcile activity across several financial partners.

This is why the phrase moving money can be misleading.

The real challenge is often managing the entire lifecycle of value.

10. Why Cross-Border Payments Can Be Expensive

A customer may see a single fee.

Behind that fee can be an entire financial system.

Potential costs can arise from:

payment processing
foreign exchange
banking relationships
intermediary institutions
local payout infrastructure
liquidity provision
compliance operations
fraud prevention
operational systems

This does not mean every transaction involves every one of these costs in the same way. Payment infrastructure varies.

But the important point is that a cross-border payment is not one single action.

It can be a chain of financial operations.

Historically, each additional layer created opportunities for additional cost.

That is why infrastructure innovation matters.

The opportunity is not simply to make a prettier payment application.

It is to improve the systems behind the experience.

Reduce unnecessary complexity.

Improve connectivity.

Increase transparency.

Make financial capabilities easier to access.

11. The Internet Solved Information. Money Is Still Catching Up.

This is perhaps one of the most interesting ways to think about the modern financial system.

Information became increasingly global.

You can:

send an email anywhere
make a video call across continents
deploy software to users worldwide
publish information instantly
collaborate with people thousands of kilometres away

The infrastructure of the internet makes this possible.

Developers do not need to negotiate with every telecommunications company before sending an API request.

They use common infrastructure.

They use protocols.

They use networks.

They build applications on top.

Money is different.

The global financial system is made up of:

institutions
currencies
regulations
payment networks
local systems

It is not one single network.

This fragmentation is one of the reasons financial infrastructure is becoming such an important area of innovation.

The challenge is not necessarily to replace every existing financial system.

The challenge is to make the systems easier to connect.

Easier to program.

Easier to build on.

Easier to access.

The future may not require one universal financial network.

But it increasingly requires better infrastructure for connecting existing networks.

12. From Financial Institutions to Financial Infrastructure

For a long time, building a financial product required significant direct interaction with the financial system.

A company might need to:

establish banking relationships
negotiate partnerships
build operational processes
maintain settlement accounts
create compliance operations
integrate multiple payment providers

For many startups, this was a major barrier.

The company was not just building a product.

It was building the infrastructure required to support the product.

That model is changing.

Increasingly, specialized infrastructure providers expose financial capabilities through software interfaces.

Instead of building every component, businesses can access certain capabilities as infrastructure.

Conceptually:

Before

Financial Product Company
        ↓
Build Everything
        ↓
Financial Operations
        ↓
Product

Now:

Infrastructure Provider
        ↓
Financial Capabilities
        ↓
APIs and Integrations
        ↓
Financial Product

This does not mean financial complexity disappears.

It means complexity can be packaged.

A company can focus on its product while infrastructure providers handle specialized parts of the underlying system.

That is a profound shift.

13. APIs Don't Remove Complexity. They Package It.

It is easy to look at an API and think:

await sendPayment();

Simple.

But the simplicity of an API call does not mean the underlying process is simple.

An API may represent years of infrastructure development.

Behind one endpoint could be:

banking relationships
compliance systems
payment routing
settlement processes
monitoring
security
reconciliation

The API does not magically eliminate those things.

It creates an interface through which developers can access capabilities without rebuilding everything themselves.

That distinction matters.

APIs don't remove financial complexity.

They package complexity into reusable infrastructure.

This is similar to cloud computing.

A developer can create a server without physically constructing a data centre.

That does not mean the data centre disappeared.

Someone still built and operates it.

The infrastructure simply became accessible through an abstraction.

Financial infrastructure is increasingly moving in a similar direction.

Developers can focus on:

user experiences
workflows
automation
business logic
distribution

while specialized providers focus on underlying financial capabilities.

14. The New Financial Stack

We can think about a modern financial product as a stack.

At the top is the experience the user sees.

Below that is the application logic.

Below that is the infrastructure enabling financial actions.

And beneath that are the networks and institutions that make the infrastructure possible.

Conceptually:

┌──────────────────────────────┐
│        APPLICATION           │
│                              │
│  UX • Product • Experience   │
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│       BUSINESS LOGIC         │
│                              │
│  Rules • Workflows • Automation
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│   FINANCIAL INFRASTRUCTURE   │
│                              │
│  APIs • Accounts • Payments  │
│  Wallets • FX • Payouts      │
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│     FINANCIAL NETWORKS       │
│                              │
│  Banks • Payment Rails       │
│  Liquidity • Settlement      │
└──────────────────────────────┘

The application does not necessarily need to own every layer.

That creates new possibilities.

A startup can focus on solving a specific customer problem.

A marketplace can focus on buyers and sellers.

A payroll product can focus on employers and workers.

A creator platform can focus on creators.

The infrastructure beneath the product can provide access to financial capabilities.

This is one of the most important changes happening in fintech.

15. Stablecoins Add a New Infrastructure Layer

Stablecoins have added another dimension to conversations about global money movement.

The most interesting use case is not always visible to consumers.

A customer may not necessarily care what infrastructure is used behind a transaction.

They care about:

speed
reliability
cost
accessibility

But stablecoins can potentially provide new infrastructure capabilities for certain financial workflows.

Depending on the system and use case, they can be used in areas such as:

value transfer
settlement
liquidity movement
treasury operations
programmable financial workflows

This is why stablecoins are increasingly discussed as infrastructure rather than simply as consumer-facing assets.

The customer might see:

Send Money

The underlying architecture could involve a more complex flow:

Collection
    ↓
Settlement
    ↓
Treasury Movement
    ↓
Liquidity
    ↓
Payout

The important idea is not that every payment product should use stablecoins.

The important idea is that new forms of programmable value can create new options for infrastructure design.

Financial products can increasingly separate the customer experience from the complexity of the underlying settlement architecture.

That separation is powerful.

16. Invisible Infrastructure Is Often the Best Infrastructure

The best infrastructure is often invisible.

Think about the technologies you use every day.

When you open a website, you probably do not think about:

DNS
TCP/IP
data centres
load balancers
databases

You simply expect the page to load.

When you send a message, you do not think about the network infrastructure behind it.

You simply expect the message to arrive.

Financial infrastructure should increasingly work the same way.

The average customer should not need to understand:

correspondent banking
liquidity management
settlement architecture
payment routing
treasury operations

They should simply understand the outcome.

Did the money arrive?

This is the ultimate test of infrastructure.

Not whether the architecture is impressive.

Not whether the system uses fashionable technology.

The question is:

Does the infrastructure make the experience better?

Better infrastructure should make financial products:

easier to build
easier to operate
easier to scale
easier to access

And ideally, easier to use.

17. The Opportunity Is Not Just Moving Money Faster

When people talk about fintech innovation, the conversation often focuses on speed.

Faster payments.

Instant settlement.

Real-time transfers.

Those things matter.

But the opportunity is bigger.

The real transformation may come from making financial capabilities more programmable.

Consider what happens when software can interact directly with financial infrastructure.

A product can potentially:

trigger a payment
create an account
initiate a payout
retrieve transaction information
automate reconciliation
manage workflows

This changes what developers can build.

Financial operations become part of the software stack.

Instead of manually coordinating every financial action, software can increasingly participate in the workflow.

That does not remove the need for responsible financial operations.

But it changes the interface through which businesses access those capabilities.

18. The Most Important Shift: From Building Rails to Building Products

This may be the defining shift.

Historically, a company entering financial services often faced a difficult question:

How do we build or connect to the financial infrastructure we need?

Today, the question is increasingly becoming:

What can we build on top of financial infrastructure?

That difference matters.

It changes where startups spend their time.

Instead of spending years attempting to recreate foundational capabilities, they can increasingly focus on:

product design
customer experience
automation
vertical-specific workflows
distribution
business models

Consider a freelancer platform.

The company does not necessarily want to become a bank.

Its core problem may be:

Help businesses pay freelancers efficiently.

The platform needs financial capabilities.

But the financial infrastructure is not necessarily the product itself.

The product is the workflow.

Similarly, a marketplace may not want to build a global banking network.

It wants to:

collect payments
manage transactions
pay sellers

Infrastructure can make those capabilities accessible.

The rails exist.

The opportunity is to build better products on top of them.

19. What Happens Next?

We are moving toward a world where financial infrastructure becomes increasingly modular.

Businesses can combine different capabilities.

For example:

Accounts
+
Payments
+
Payouts
+
FX
+
Wallet Infrastructure
+
Automation

The result is not necessarily a bank.

It could be:

a marketplace
a payroll platform
a creator economy product
a global commerce application
a treasury tool
a business operations platform

The innovation happens at the combination layer.

The infrastructure provides primitives.

Builders decide what to create with them.

This is similar to what happened in software.

Cloud computing did not eliminate software development.

It expanded what software developers could build.

APIs did not eliminate complexity from the internet.

They made capabilities more accessible.

Financial infrastructure may follow a similar path.

The most important companies may not be the ones that build every underlying rail.

They may be the ones that understand customer problems well enough to use existing infrastructure in new ways.

Conclusion: The World Is Becoming More Connected. Money Is Learning to Catch Up.

The global financial system was not designed as one unified application.

It evolved over decades.

Country by country.

Institution by institution.

Currency by currency.

That history created an incredibly powerful financial system.

But it also created fragmentation.

Moving money across borders can involve a combination of:

financial institutions
payment networks
foreign exchange
liquidity
compliance
settlement
local payout infrastructure

The user may only see one button.

Behind that button is an entire world.

But something is changing.

Financial infrastructure is becoming more accessible.

More programmable.

More modular.

More connected.

Businesses increasingly do not need to build every underlying financial capability themselves.

They can build on infrastructure.

And that changes the question.

The question is no longer only:

How do we connect to the financial system?

Increasingly, the question becomes:

What can we build on top of it?

The internet created a world where information became programmable.

Financial infrastructure is moving toward a future where value can increasingly become part of software workflows too.

The rails are becoming more accessible.

The interfaces are becoming more developer-friendly.

The infrastructure is becoming easier to build on.

And that creates an enormous opportunity.

Because once the complexity of financial infrastructure is abstracted away, builders can focus on something far more important.

The problem.

The customer.

The experience.

The product.

Part II: When Money Becomes Infrastructure

In the second part of this series, we will explore what happens when financial capabilities become accessible as programmable infrastructure.

We will look at:

the rise of financial APIs
the modern financial product stack
programmable money
stablecoins as infrastructure
embedded finance
the new generation of global financial products

And ultimately, one important question:

What will builders create when they no longer have to build every rail themselves?

This is Part I of a two-part series exploring the infrastructure behind global money and the technologies reshaping how financial products are built.

How to Collect Mobile Money Payments for Your SaaS Through Afriex

Victory Lucky — Fri, 28 Aug 2026 18:23:48 +0000

Building a product is hard enough. Getting paid for it shouldn't be. In this post I'll show you how to accept mobile money payments from Kenya, Uganda and Tanzania in 5 steps.

Cards barely work for recurring billing in these markets. Mobile money — a wallet held against a phone number — is how people actually pay.

Mobile money collection is live in Kenya (KES), Uganda (UGX), Tanzania (TZS), Côte d'Ivoire and Benin (XOF), Cameroon (XAF) and Ethiopia (ETB). Ghana, Rwanda and a few others are payout-only for now, so check the supported rails table before you support a market.

The flow:

list providers -> verify the number -> save it -> charge it -> track it

Setup

npm install @afriex/sdk

// src/afriex/client.ts
import { AfriexSDK } from "@afriex/sdk";

export const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY!,
  environment: process.env.NODE_ENV === "production" ? "production" : "staging",
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY!,
  retryConfig: { maxRetries: 3, retryDelay: 1000 },
});

Retries are off by default — turn them on. Grab both keys from Developer -> API keys and Developer -> Webhooks at business.afriex.com. Staging and production webhook keys differ.

Your customer must exist in Afriex before they can have a payment method:

// src/afriex/customers.ts
export async function createAfriexCustomer(user: User): Promise<string> {
  const customer = await afriex.customers.create({
    fullName: user.fullName,
    email: user.email,
    phone: user.phone,   // E.164, must match countryCode
    countryCode: user.countryCode, // "KE" | "UG" | "TZ"
  });

  return customer.customerId; // store this on your user row
}

If the email or phone already exists you get a 400 back, but details.data.customerId carries the existing ID — adopt it instead of doing a lookup.

Step 1 — List the providers

Don't hardcode providers. Fetch them per country.

// src/afriex/institutions.ts
export interface MobileMoneyProvider {
  institutionCode: string;
  institutionName: string;
  institutionId?: string;
}

export async function listMobileMoneyProviders(
  countryCode: string,
): Promise<MobileMoneyProvider[]> {
  return afriex.paymentMethods.getInstitutions({
    channel: "MOBILE_MONEY",
    countryCode,
  });
}

Live responses:

// KE
[{ "institutionCode": "SAFARICOM", "institutionName": "SAFARICOM" },
 { "institutionCode": "AIRTEL",    "institutionName": "AIRTEL" }]

// UG
[{ "institutionCode": "MTN",    "institutionName": "MTN" },
 { "institutionCode": "AIRTEL", "institutionName": "AIRTEL" }]

Send institutionCode to the API. Don't show institutionName to users — SAFARICOM means nothing to someone who calls it M-Pesa. Map it yourself:

// src/afriex/provider-labels.ts
export const PROVIDER_LABELS: Record<string, string> = {
  SAFARICOM: "M-Pesa",
  MTN: "MTN MoMo",
  AIRTEL: "Airtel Money",
};

Step 2 — Verify the number

Check who owns a number before you save it. This is the difference between a typo caught in the UI and a failed charge.

// src/afriex/resolve-account.ts
export async function resolveMobileMoneyAccount(options: {
  phoneNumber: string;
  countryCode: string;
  institutionCode: string;
}): Promise<{ recipientName: string }> {
  const { phoneNumber, countryCode, institutionCode } = options;

  return afriex.paymentMethods.resolveAccount({
    channel: "MOBILE_MONEY",
    accountNumber: phoneNumber,
    institutionCode,
    countryCode,
  });
}

Returns { recipientName, institutionName, institutionCode }. Show recipientName and make the user confirm before continuing.

Staging returns canned values here (you'll see John Doe), so build the confirmation UI but test it against production before trusting the name.

Step 3 — Save the payment method

// src/afriex/payment-methods.ts
export async function saveMobileMoneyMethod(options: {
  customerId: string;
  accountName: string;
  phoneNumber: string;
  countryCode: string;
  institutionCode: string;
}): Promise<string> {
  const {
    customerId, accountName, phoneNumber, countryCode, institutionCode,
  } = options;

  const paymentMethod = await afriex.paymentMethods.create({
    channel: "MOBILE_MONEY",
    customerId,
    accountName,
    accountNumber: phoneNumber,
    countryCode,
    institution: { institutionCode, institutionName: institutionCode },
    type: "DEPOSIT", // required — see below
  });

  return paymentMethod.paymentMethodId;
}

Don't skip type. It sets the method's capability, and it defaults to WITHDRAW — the payout direction. Omit it and you get a method you can send money to, not collect from:

// with type: "DEPOSIT"     -> "capabilities": ["DEPOSIT"]
// with type omitted        -> "capabilities": ["WITHDRAW"]

Your charge in step 4 will fail against a WITHDRAW-only method, and the error won't obviously point back here.

Also worth knowing: currency is derived from country and channel — don't send it. And the API stores accountNumber with a + prefix even though it accepts it without one, so normalise phone numbers on the way in rather than round-tripping the stored value.

Store paymentMethodId against your subscription. You'll pass it as sourceId on every charge.

Step 4 — Charge it

Collecting is a DEPOSIT with the customer's wallet as sourceId. For a deposit, destinationAmount is required and sourceAmount is optional — the reverse of the withdraw rules.

The simplest correct setup collects in the customer's own currency, so no conversion happens at charge time:

// src/afriex/collect.ts
import { ulid } from "ulid";

export async function chargeSubscription(options: {
  customerId: string;
  paymentMethodId: string;
  subscriptionId: string;
  localAmount: string;   // e.g. "3750.00"
  localCurrency: string; // "KES" | "UGX" | "TZS"
}) {
  const {
    customerId, paymentMethodId, subscriptionId, localAmount, localCurrency,
  } = options;

  const reference = `sub_${subscriptionId}_${Date.now()}`;

  const transaction = await afriex.transactions.create({
    type: "DEPOSIT",
    customerId,
    sourceId: paymentMethodId,
    sourceCurrency: localCurrency,
    destinationCurrency: localCurrency, // same currency — no FX on collection
    destinationAmount: localAmount,     // required for DEPOSIT
    meta: {
      idempotencyKey: ulid(),
      reference,
      narration: "Monthly subscription",
    },
  });

  return { transaction, reference };
}

Persist reference on the subscription row before you await. If the call times out you still know what to look for — and reference is what you'll match the webhook on.

Amounts accept a number or a numeric string, and come back as strings. Keep money as bigint minor units internally and format only at this boundary — the balance endpoint hands back values like 51291590.19999999, and floats will burn you.

The response also carries rate and fee, both worth logging.

Collect in local currency, convert on your own schedule

Notice that destinationCurrency above is KES, not USD. That's deliberate.

You publish "KES 3,750/month" and the customer agrees to that number. If you set destinationCurrency: "USD", you're doing an FX conversion inside every single charge, and one of the two amounts has to absorb the rate movement. On mobile money the charged amount appears in the OTP prompt on the customer's phone, so a figure that drifts away from your pricing page is an abandonment risk, not just an accounting quirk.

Collecting KES into your KES wallet means no conversion at charge time. The customer pays exactly what you quoted, every cycle. You then convert when you choose, in whatever size you choose, with a SWAP:

// src/jobs/settle-to-usd.ts
await afriex.transactions.create({
  type: "SWAP",
  sourceCurrency: "KES",
  sourceAmount: accumulatedKes, // exactly one of source/destination
  destinationCurrency: "USD",
  meta: {
    idempotencyKey: ulid(),
    reference: `settlement-${settlementRunId}`,
  },
});

A SWAP takes exactly one of sourceAmount or destinationAmount — the API computes the other side at the live rate. Sending both is rejected with Only one of source amount or destination amount can be provided. customerId is omitted, so it runs against your business wallet.

This also means fewer, larger conversions instead of one per subscriber, which is usually the cheaper side of the spread.

If you do convert at charge time

If you'd rather land USD directly, set destinationCurrency: "USD" and send destinationAmount as the USD figure — it's required for a deposit either way. sourceAmount is optional, and if you send both, destinationAmount wins by default. shouldPreferSourceAmount: true flips that so the source side drives, but the docs frame that flag around payouts, so test it on a deposit before relying on it. Either way, read the realized rate and the actual amounts off the response rather than assuming you got what you asked for.

The OTP step

Mobile money deposits often need a one-time password. If the response comes back CUSTOMER_ACTION_REQUIRED with meta.otpRequired: true, collect the OTP from the customer and submit it:

// src/afriex/authorize-deposit.ts
export async function authorizeDeposit(options: {
  transactionId: string;
  otp: string;
}) {
  const { transactionId, otp } = options;

  return afriex.transactions.authorize(transactionId, {
    type: "OTP",
    otp,
  });
}

Skip this and the deposit sits unfinished forever. Handle it in your UI:

if (transaction.status === "CUSTOMER_ACTION_REQUIRED" && transaction.meta.otpRequired) {
  return { needsOtp: true, transactionId: transaction.transactionId };
}

Step 5 — Track the payment

The webhook is the source of truth. Signatures are RSA-SHA256, base64, computed over the raw body — so you need the raw bytes, not the parsed object:

// src/plugins/raw-body.ts
import fastifyPlugin from "fastify-plugin";

export default fastifyPlugin(async (fastify) => {
  fastify.addContentTypeParser(
    "application/json",
    { parseAs: "string" },
    (request, body: string, done) => {
      request.rawBody = body;
      try {
        done(null, JSON.parse(body));
      } catch (error) {
        done(error as Error, undefined);
      }
    },
  );
});

verifyAndParse is synchronous and takes positional arguments:

// src/routes/webhooks/afriex.ts
export async function afriexWebhookRoute(fastify: FastifyInstance) {
  fastify.post("/webhooks/afriex", async (request, reply) => {
    const signature = request.headers["x-webhook-signature"];

    if (typeof signature !== "string" || !request.rawBody) {
      return reply.code(400).send({ error: "missing_signature" });
    }

    try {
      const event = afriex.webhooks.verifyAndParse(request.rawBody, signature);

      if (event.event === "TRANSACTION.UPDATED") {
        await applyTransactionEvent(event.data);
      }

      return reply.code(200).send({ received: true });
    } catch {
      return reply.code(400).send({ error: "invalid_signature" });
    }
  });
}

Return 200 fast. Afriex retries failed deliveries up to 12 times with exponential backoff starting at 30 seconds, so a slow handler becomes a duplicate event.

There's no event ID in the payload, so key idempotency on the transaction and its status:

// src/subscriptions/apply-transaction-event.ts
const TERMINAL = ["SUCCESS", "FAILED", "CANCELLED", "REJECTED"];

export async function applyTransactionEvent(
  data: AfriexTransactionEventData,
): Promise<void> {
  const reference = data.merchantReference ?? data.meta?.reference;
  if (!reference || data.type !== "DEPOSIT") return;

  await database.transaction(async (trx) => {
    const inserted = await trx
      .insert(processedEvents)
      .values({ transactionId: data.transactionId, status: data.status })
      .onConflictDoNothing()
      .returning({ transactionId: processedEvents.transactionId });

    if (inserted.length === 0) return; // replay

    const subscription = await findByReference(trx, reference);
    if (!subscription) return;

    if (data.status === "SUCCESS") {
      await activateSubscription(trx, subscription.id);
    } else if (TERMINAL.includes(data.status)) {
      await markPaymentFailed(trx, subscription.id, data.meta?.failureReason);
    }
  });
}

The composite unique index on (transactionId, status) is what makes this idempotent — not an if, which two workers will race through together.

On failure, meta.failureReason carries a stable AFX_* code, a customer-safe message, and a retryable boolean. Branch on code, never the message:

if (failureReason?.retryable) {
  await scheduleRetry(subscription.id);
}

Codes include AFX_VELOCITY_LIMIT_EXCEEDED, AFX_AMOUNT_LIMIT_EXCEEDED, AFX_COMPLIANCE_REJECTED and AFX_INVALID_RECIPIENT. The set grows, but existing values don't change meaning.

Testing it

Sandbox settles transactions automatically in a minute or two, and you steer the outcome through meta.reference:

Put this in `meta.reference`	What happens
anything containing `fail`	settles `FAILED`
`SIMULATE_OTP`	returns `CUSTOMER_ACTION_REQUIRED`
`SIMULATE_NO_OTP`	completes with no OTP step
anything else	settles `SUCCESS`

The sandbox OTP is 123456. Any other value is rejected, so you can test the wrong-OTP path too.

You can also fire a real signed webhook at your endpoint without generating the activity:

await afriex.webhooks.triggerTestWebhook({
  event: "TRANSACTION.UPDATED",
  entityId: transactionId,
});

Gotchas

Staging and production webhook public keys are different.
Pagination is zero-indexed — the first page is page: 0.
merchantReference on the webhook mirrors meta.reference from create.
Customer phone must match countryCode, or you get PHONE_COUNTRY_MISMATCH.
Surface details.friendlyMessage to users; branch on code.

That's it

Five calls: list providers, resolve the number, save the method, create a DEPOSIT, handle the webhook. Plus the OTP step, which is the one most integrations forget.

The New Fintech Stack: APIs, Stablecoins, and the Infrastructure Behind Global Money

0xSonOfUri — Fri, 21 Aug 2026 09:45:17 +0000

For decades, building a financial product meant building a significant part of the financial system around it.

If you wanted to create a payments company, you needed banking relationships.

If you wanted customers to receive money, you needed accounts.

If you wanted to move money across borders, you needed access to payment networks, foreign exchange, settlement partners, and liquidity.

If you wanted to build a global product, all of that complexity had to be solved before you could focus on the product itself.

That model is changing.

Today, financial infrastructure is becoming increasingly programmable, composable, and accessible through APIs.

Developers can build on top of infrastructure that handles many of the complicated layers underneath a financial product.

At the same time, stablecoins are introducing another programmable layer for moving value globally.

Together, these changes are creating something that looks increasingly like a new fintech stack.

And the most interesting part isn't simply that the infrastructure is getting better.

It's that more businesses can now build financial products without owning every layer of the financial infrastructure themselves.

The Old Fintech Stack

Historically, financial products were deeply tied to financial institutions.

If you wanted to build a product that moved money, you typically needed to establish relationships with banks and payment providers.

The architecture might have looked something like this:

BANKING SYSTEM
     │
┌────┼────────────┐
│    │            │
Accounts       Payments       FX
│    │            │
└────┼────────────┘
     │
 Settlement
     │
Your Product
     │
 Customer

The product was sitting very close to the underlying financial infrastructure.

That created enormous barriers to entry.

A startup could have an excellent product idea and still spend months or years solving infrastructure problems before reaching meaningful scale.

The challenge wasn't necessarily building the user interface.

The challenge was gaining access to everything behind it.

Financial Infrastructure Was Historically a Moat

This complexity wasn't accidental.

Moving money is difficult.

A financial transaction can involve multiple systems, institutions, currencies, compliance requirements, ledgers, settlement processes, and counterparties.

Even a seemingly simple action like:

"Pay someone $1,000"

can involve significantly more infrastructure underneath.

For example:

Customer
   │
   ▼
Payment Initiation
   │
   ▼
Payment Provider
   │
   ▼
Bank / Financial Institution
   │
   ▼
Clearing
   │
   ▼
Settlement
   │
   ▼
Recipient

Every layer introduces its own requirements.

This meant financial infrastructure itself became a competitive moat.

Companies that already had access to banking relationships and payment networks had a significant advantage over startups trying to build from scratch.

Then APIs Changed Software

We've already seen this transformation happen in another industry.

Cloud computing.

A company building software in the early days of the internet had to think about physical servers, networking, storage, data centers, hardware maintenance, and infrastructure capacity.

Then cloud platforms abstracted much of that complexity.

Developers could request infrastructure through software.

Instead of thinking:

"How do we build and maintain a data center?"

They could think:

"What application do we want to build?"

The infrastructure still existed.

It simply became programmable.

Financial infrastructure is going through a similar transformation.

Financial Infrastructure Is Becoming Programmable

Modern financial infrastructure increasingly exposes financial capabilities through APIs.

Instead of manually coordinating with multiple institutions for every capability, developers can interact with financial infrastructure programmatically.

The conceptual shift looks like this:

BEFORE

Business
   │
   ├── Bank relationship
   ├── Payment provider
   ├── FX provider
   ├── Settlement partner
   └── Treasury infrastructure
            │
            ▼
         Product


AFTER

                    ┌──────────────┐
                    │Infrastructure│
                    │     APIs     │
                    └──────┬───────┘
                           │
                           ▼
                        Product
                           │
                           ▼
                        Customer

The financial infrastructure hasn't disappeared.

It has become a layer that developers can integrate with.

The New Fintech Stack

This leads us to the idea of a new fintech stack.

Instead of thinking about fintech as one enormous system that a company has to build itself, we can think about it as a collection of composable layers.

A simplified version might look like:

┌─────────────────────────────────────┐
│           Customer Experience       │
├─────────────────────────────────────┤
│             Your Product            │
├─────────────────────────────────────┤
│       Financial Application Layer   │
├─────────────────────────────────────┤
│             APIs & SDKs              │
├─────────────────────────────────────┤
│     Payments / Accounts / FX        │
├─────────────────────────────────────┤
│      Settlement & Liquidity         │
├─────────────────────────────────────┤
│       Banking / Financial Rails     │
└─────────────────────────────────────┘

The startup doesn't necessarily need to own every layer.

It can choose which layers to build and which layers to consume.

That distinction is incredibly important.

Build vs. Compose

One of the biggest decisions a fintech founder makes is deciding what to build internally.

You could build everything.

But should you?

A modern software company doesn't build its own database engine, cloud provider, email infrastructure, authentication system, analytics platform, and networking stack before launching its product.

It composes infrastructure.

The same thinking is increasingly applicable to financial products.

Consider a company building a global marketplace.

It needs:

Customer onboarding
Payments
Accounts
Payouts
Currency conversion
Transaction tracking
Settlement
Treasury
Reporting

The company doesn't necessarily need to build a bank.

It needs to build a marketplace.

The financial infrastructure can become a layer beneath that marketplace.

The Financial Primitives

This is where the concept of financial primitives becomes useful.

A primitive is a fundamental capability that can be combined with other capabilities to create something larger.

For financial products, primitives might include:

Accounts
Payments
Payouts
Foreign Exchange
Balances
Transactions
Settlement
Treasury
Stablecoin Transfers

These primitives can then be composed into products.

For example:

             MARKETPLACE
                  │
        ┌─────────┴─────────┐
        │                   │
     Payments            Payouts
        │                   │
        └─────────┬─────────┘
                  │
             Accounts
                  │
             Settlement

The marketplace itself is the product.

The financial primitives are the infrastructure underneath.

Where Afriex Fits

This is where platforms such as Afriex become particularly interesting.

The purpose of financial infrastructure isn't simply to expose APIs.

The larger opportunity is to give businesses access to capabilities they can incorporate into their own products, operations, and workflows.

Instead of every company independently figuring out how to connect financial systems across markets, infrastructure providers can provide a layer through which those capabilities become accessible programmatically.

That changes the question for builders.

Instead of:

"How do I build the entire financial infrastructure?"

the question becomes:

"What financial capabilities does my product need?"

That is a much more interesting problem.

From Infrastructure to Product

Imagine you're building a marketplace.

Your customers don't care which payment infrastructure powers the transaction.

They care that:

They can pay.
Their payment works.
Their money arrives.
They can receive funds.
They can understand their balance.
The experience is fast and reliable.

The customer sees the product.

The infrastructure stays underneath.

                 CUSTOMER
                    │
                    ▼
             Your Marketplace
                    │
                    ▼
          Financial Infrastructure
                    │
       ┌────────────┼────────────┐
       ▼            ▼            ▼
    Payments      Accounts       FX
       │            │            │
       └────────────┼────────────┘
                    ▼
                Settlement

This abstraction is powerful.

The customer doesn't need to understand the infrastructure.

They simply need the experience to work.

The Rise of Stablecoins

Now introduce another major development.

Stablecoins.

Stablecoins are particularly interesting because they combine characteristics of digital assets with relatively stable units of account.

More importantly for developers, they can function as programmable representations of value that can move across blockchain networks.

That creates another potential layer in the global financial stack.

Instead of every movement of value needing to happen through traditional financial rails, stablecoins can sometimes provide another mechanism for moving value between participants and systems.

The architecture can become something like:

Local Currency
      │
      ▼
Payment Infrastructure
      │
      ▼
   Settlement
      │
      ▼
Stablecoin Treasury
      │
      ▼
   Settlement
      │
      ▼
Payment Infrastructure
      │
      ▼
Local Currency

The customer may never see any of this.

From their perspective:

SEND $1,000

Behind the scenes, the infrastructure may involve multiple layers.

That is the point of abstraction.

Stablecoins Don't Replace Everything

It is important not to frame stablecoins as a replacement for the entire financial system.

They are another component of the stack.

A global financial product may still need:

Local payment rails
Banking relationships
Currency conversion
Compliance systems
Settlement
Liquidity
Treasury management
Customer accounts

Stablecoins can fit into that architecture rather than necessarily replacing all of it.

The interesting opportunity is composition.

Traditional Rails
       +
APIs
       +
Stablecoins
       +
Liquidity
       +
Financial Infrastructure
       =
New Financial Products

The Customer Experience Becomes the Abstraction

This is one of the most important changes.

Customers don't want to think about financial infrastructure.

They want to complete an action.

They want to:

Pay

Receive

Send

Withdraw

Convert

The complexity underneath should ideally be invisible.

Consider what a customer might see:

┌──────────────────────────────┐
│                              │
│        Send Money            │
│                              │
│        $1,000                │
│                              │
│        [ Send ]              │
│                              │
└──────────────────────────────┘

What they don't see could be:

Authentication
      ↓
Payment Processing
      ↓
Currency Conversion
      ↓
Liquidity
      ↓
Settlement
      ↓
Treasury
      ↓
Recipient

The best infrastructure makes complicated systems feel simple.

This Is Similar to Cloud Computing

There is a useful analogy here.

Cloud computing didn't eliminate servers.

It abstracted them.

Payment infrastructure doesn't eliminate banks, payment networks, liquidity providers, or settlement systems.

It can abstract access to them.

The developer doesn't necessarily need to know every implementation detail.

They need a reliable interface.

CLOUD

Application
    ↓
Cloud API
    ↓
Servers
    ↓
Networking
    ↓
Data Centers


FINTECH

Financial Product
    ↓
Financial API
    ↓
Payments
    ↓
Settlement
    ↓
Financial Rails

The abstraction layer is what makes the system accessible to a much larger number of builders.

The Developer Becomes a Financial Product Builder

This is perhaps the biggest consequence.

Historically, financial products were primarily built by financial institutions.

Increasingly, software companies can build financial experiences too.

A developer who understands APIs, infrastructure, and product design can potentially build:

Payment platforms
Global marketplaces
Payroll products
Remittance applications
Treasury tools
Creator platforms
B2B payment workflows
Embedded financial experiences

The developer doesn't need to become a bank to understand the product problem.

They need to understand the infrastructure available to them.

A Marketplace Example

Imagine a marketplace connecting businesses in multiple countries.

A traditional approach might look like:

Buyer
  ↓
Marketplace
  ↓
Bank
  ↓
Payment Provider
  ↓
Settlement
  ↓
Seller

Now imagine composing financial infrastructure through APIs.

Buyer
  ↓
Marketplace
  ↓
Financial APIs
  ├── Payment
  ├── Account
  ├── FX
  └── Settlement
        ↓
      Seller

The marketplace can focus on:

Matching buyers and sellers
Product discovery
Pricing
Customer support
Trust
Logistics
User experience

Financial infrastructure becomes one of the services supporting the marketplace.

A Global Payroll Example

Consider another use case.

A company has employees or contractors across several markets.

The product doesn't need to become a bank.

It needs to solve a business problem:

Pay people reliably.

The product could be responsible for:

Employee Management
       ↓
Payroll Calculation
       ↓
Payment Instructions
       ↓
Financial Infrastructure
       ↓
Payout

The company's competitive advantage might be payroll automation, reporting, compliance workflows, or employee experience.

Not the underlying payment rails.

A Remittance Example

Remittance products show why this infrastructure layer matters.

A customer might simply want:

"Send money home."

But the infrastructure underneath may involve:

Sender
  ↓
Collection
  ↓
Currency Conversion
  ↓
Liquidity
  ↓
Settlement
  ↓
Local Payout
  ↓
Recipient

The customer should not have to understand any of those layers.

They should have a simple experience.

That is the promise of abstraction.

Global Businesses Need Global Infrastructure

As businesses become more global, financial infrastructure becomes increasingly important.

A company may begin in one country.

Then it acquires customers elsewhere.

Then it hires internationally.

Then it pays suppliers across borders.

Then it expands into new markets.

Every new market introduces another financial problem.

The old approach was to build another set of integrations.

The newer approach is to use infrastructure that is designed to support multiple financial workflows and markets.

This is where infrastructure becomes a growth enabler rather than simply a technical dependency.

Infrastructure Can Accelerate Distribution

There is another important consequence.

Infrastructure affects how quickly a company can expand.

Suppose a company has discovered strong product-market fit in one market.

Its next challenge is expansion.

If every new market requires rebuilding its financial stack, expansion becomes slow.

But if financial infrastructure is accessible through reusable APIs and standardized workflows, the company can potentially move faster.

The equation changes from:

New Market
    ↓
New Infrastructure
    ↓
New Integrations
    ↓
New Product Work
    ↓
Launch

toward:

New Market
    ↓
Configure Financial Infrastructure
    ↓
Adapt Product
    ↓
Launch

The difference can be significant.

The New Competitive Advantage

This brings us to a larger question.

If infrastructure becomes increasingly accessible, where does the competitive advantage move?

It moves upward.

The infrastructure becomes increasingly standardized.

The product becomes increasingly differentiated.

Consider two companies with access to similar financial primitives.

They could still create completely different products.

One might build:

A global payroll platform.

Another:

A marketplace.

Another:

A remittance product.

Another:

A treasury platform.

The underlying capabilities may overlap.

The customer experience doesn't.

That is where innovation happens.

The Stack Becomes More Modular

The fintech stack increasingly starts to resemble modern software architecture.

Instead of one monolithic system:

┌─────────────────────────────┐
│                             │
│      EVERYTHING IN ONE      │
│          COMPANY            │
│                             │
└─────────────────────────────┘

we get specialized layers:

┌─────────────────────────────┐
│        Your Product         │
├─────────────────────────────┤
│     Financial Workflows     │
├─────────────────────────────┤
│      Infrastructure APIs    │
├─────────────────────────────┤
│ Payments │ FX │ Accounts    │
├─────────────────────────────┤
│ Settlement │ Liquidity      │
├─────────────────────────────┤
│ Banking / Financial Rails   │
└─────────────────────────────┘

Each layer can specialize.

The product builder doesn't need to own everything.

They need to orchestrate the right pieces.

But Abstraction Doesn't Mean Simplicity

There is an important caveat.

Abstracting infrastructure does not eliminate complexity.

It relocates it.

A company building on financial APIs still needs to understand:

Authentication
Security
Transaction states
Error handling
Reconciliation
Compliance requirements
Webhooks
Operational monitoring
Customer support
Financial risk

APIs make infrastructure more accessible.

They don't make financial engineering trivial.

That's an important distinction.

The Responsibility Moves Up the Stack

When infrastructure is abstracted, the responsibility of the product builder changes.

You don't necessarily need to understand every underlying payment rail.

But you absolutely need to understand what your application promises to the customer.

If your product says:

"Your payment has been received."

You need to be certain that it actually has.

If your product says:

"Your money is available."

Your system needs reliable confirmation.

If your product says:

"Your payout has been completed."

You need the underlying financial state to support that claim.

The abstraction layer makes development easier.

It also makes good engineering practices more important.

APIs Are Becoming Financial Building Blocks

The most important shift isn't that APIs exist.

We've had APIs for years.

The shift is that financial capabilities themselves are increasingly exposed as programmable building blocks.

Developers can work with concepts such as:

Customer
Account
Balance
Payment
Transaction
Payout
Exchange Rate
Webhook
Settlement

These aren't just backend resources.

They are building blocks for financial products.

A developer can combine them with:

Authentication
Databases
AI
Analytics
Notifications
Automation

and create an entirely new product.

AI Adds Another Layer

There is another development worth watching.

AI is increasingly becoming an interface for software.

Traditionally:

Human
 ↓
Code
 ↓
API
 ↓
Infrastructure

Now we're beginning to see:

Human
 ↓
AI Agent
 ↓
Tools / APIs
 ↓
Financial Infrastructure

This creates interesting possibilities.

An AI system could potentially help with:

Payment operations
Treasury monitoring
Transaction analysis
Reconciliation workflows
Financial reporting
Operational alerts

The infrastructure still matters.

But the interface for interacting with it is changing.

This is one reason programmable financial infrastructure becomes even more interesting in an AI-native world.

The Financial Stack Is Becoming More Composable

Put all of this together and the picture becomes clearer.

We have:

                 AI / AUTOMATION
                       │
                       ▼
                 YOUR PRODUCT
                       │
                       ▼
              FINANCIAL WORKFLOWS
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
      Payments       Accounts        FX
         │             │             │
         └─────────────┼─────────────┘
                       ▼
                  Settlement
                       │
              ┌────────┴────────┐
              ▼                 ▼
        Traditional Rails   Stablecoins
              │                 │
              └────────┬────────┘
                       ▼
                    MONEY

This is what makes the new fintech stack so interesting.

It's no longer one monolithic system.

It's a collection of layers that can be composed.

What This Means for Startups

For founders, this changes what is possible.

You can start with a customer problem.

Then identify the financial capabilities required to solve it.

Then assemble those capabilities.

Instead of beginning with:

"How do we become a financial institution?"

You can begin with:

"What financial experience does our customer need?"

That's a dramatically better starting point.

What This Means for Developers

For developers, the opportunity is equally significant.

The skill set is shifting.

You still need to know how to build software.

But increasingly, you also need to understand how to compose infrastructure.

The developer of the future may not just ask:

"How do I write this API call?"

They'll ask:

"How do I compose these financial primitives into a reliable product?"

That's a higher-level engineering problem.

And potentially a much more valuable one.

What This Means for Financial Infrastructure Providers

For infrastructure providers, the opportunity is to make complexity disappear.

The best infrastructure isn't necessarily the infrastructure with the most features.

It's the infrastructure that lets developers accomplish difficult things without needing to understand every underlying system.

That means:

Good APIs
Clear documentation
Reliable infrastructure
Strong developer tooling
Good observability
Predictable behavior
Easy onboarding

Developer experience becomes part of financial infrastructure itself.

The Future May Be Invisible

The most interesting financial infrastructure may eventually become almost invisible.

A customer won't care whether a payment passed through:

Bank A
→ Payment Provider B
→ Stablecoin C
→ Liquidity Provider D
→ Bank E

They'll simply see:

Payment successful.

The infrastructure becomes invisible.

The product becomes visible.

And that is exactly what good infrastructure is supposed to accomplish.

Where Afriex Fits Into This Future

Platforms such as Afriex are part of this broader transition.

The value isn't simply in providing another financial API.

It's in helping businesses access financial infrastructure that can become part of their own products and operations.

For a builder, that means the financial layer can become something they compose into the product, rather than something they have to build entirely from scratch.

The result is a different kind of fintech architecture:

                    YOUR BUSINESS
                         │
                         ▼
                  YOUR EXPERIENCE
                         │
                         ▼
                 YOUR APPLICATION
                         │
                         ▼
                  AFRIEX INFRASTRUCTURE
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
         Payments      Accounts       FX
            │            │            │
            └────────────┼────────────┘
                         ▼
                    Settlement
                         │
                         ▼
                  Financial Rails

The business owns the customer relationship and product experience.

The infrastructure handles the financial complexity beneath it.

That's the fundamental idea.

The Biggest Shift Isn't Technology

It is tempting to look at all of this as a technology story.

APIs.

Cloud infrastructure.

Stablecoins.

AI.

Automation.

But underneath all of those technologies is a much bigger shift:

Who gets to build financial products?

If financial infrastructure becomes increasingly accessible through APIs, then the answer is no longer simply:

Banks and large financial institutions.

It becomes:

Software companies, startups, developers, and businesses that know how to compose the infrastructure.

That's a profound change.

From Owning Infrastructure to Composing Infrastructure

The previous generation of fintech often competed on infrastructure ownership.

The next generation may increasingly compete on infrastructure composition.

The question becomes:

What can you combine?

Not:

What can you build entirely yourself?

That distinction matters.

Because building everything is expensive.

Composing the right infrastructure can be much faster.

The New Fintech Stack

So if we zoom out, the new fintech stack looks something like this:

┌──────────────────────────────────────┐
│              EXPERIENCE              │
│          What customers see          │
├──────────────────────────────────────┤
│               PRODUCT                │
│       Business logic & workflows     │
├──────────────────────────────────────┤
│          FINANCIAL APIS              │
│ Accounts • Payments • FX • Payouts  │
├──────────────────────────────────────┤
│         FINANCIAL INFRASTRUCTURE     │
│      Settlement • Liquidity • Rails  │
├──────────────────────────────────────┤
│          PROGRAMMABLE VALUE          │
│              Stablecoins              │
├──────────────────────────────────────┤
│          TRADITIONAL SYSTEMS         │
│        Banks • Networks • Rails      │
└──────────────────────────────────────┘

And increasingly, AI and automation can sit across the entire stack.

The result is a financial ecosystem that is more modular than the one that came before it.

The Opportunity for Builders

This is what makes the current moment particularly exciting.

A developer with a good idea doesn't necessarily need to start by building a bank.

A founder doesn't necessarily need to own every payment rail.

A marketplace doesn't necessarily need to create its own settlement network.

A payroll company doesn't necessarily need to build banking infrastructure.

A remittance startup doesn't necessarily need to recreate the entire global financial system.

They need to identify the problem.

Then compose the infrastructure required to solve it.

Final Thoughts

The fintech industry is moving toward a model that looks increasingly familiar to anyone who has built modern software.

Infrastructure is becoming modular.

Capabilities are becoming programmable.

APIs are becoming the interface between businesses and financial systems.

Stablecoins are introducing new ways to move programmable value.

AI is creating new ways to interact with software.

And infrastructure providers are abstracting more of the complexity that once required direct ownership and deep institutional relationships.

The result is a new fintech stack.

One where the underlying financial infrastructure can increasingly become a building block.

And that changes the opportunity for builders.

The question is no longer simply:

"How do we build the financial infrastructure?"

It's becoming:

"What can we build because the infrastructure is already there?"

That is where things get interesting.

Because the next generation of fintech products may not be built by companies that own every financial rail.

They may be built by companies that know how to compose the rails into something customers actually want.

The infrastructure is becoming programmable.

The money is becoming programmable.

Now the opportunity is to build what comes next.

Build a Digital Marketplace with Afriex, Fastify and Postgres, Part 2: Checkout and Payouts

Victory Lucky — Sun, 16 Aug 2026 06:30:00 +0000

At the end of Part 1, Tunde was stuck. He clicked Buy on Amara's ₦12,000 preset pack, an order was created but no money moved, because nothing in Part 1 knows how to move money.

This part fixes that, in both directions:

Checkout: collect Tunde's ₦12,000 through Afriex: by card, bank transfer, or mobile money, whichever suits him.
Payouts: track what the platform owes Amara, and send it to her bank account when she asks.

The full source is on GitHub if you want to follow along.

What you'll have at the end

Tunde can pay for an order through the Afriex checkout page.
A confirmed payment completes the order and credits Amara's balance, minus the platform fee.
Amara can register her bank account, and the platform verifies it actually belongs to her before any money moves.
Amara can withdraw her balance on demand, or get paid out on a schedule.
A failed or ambiguous payout never silently loses money: it either refunds her balance or waits for review.

Before you start

You need Part 1's code running, plus an Afriex business account with API keys in your .env (AFRIEX_API_KEY and AFRIEX_WEBHOOK_PUBLIC_KEY). The withdrawal queue in this part runs on Redis; if you started the repo's docker compose up -d in Part 1, Redis is already running. The disbursement worker is its own process, started with pnpm worker:dev alongside pnpm dev. Everything below assumes the schema and module layout from Part 1.

Let's look at the whole flow first

Read it top to bottom and it's Tunde's money coming in, then Amara's money going out. Two structural choices in this diagram shape everything that follows:

One payment confirmation triggers two separate writes. When Tunde's payment clears, the order gets completed (so he gets his download) and a sale gets recorded (so Amara gets credited).
A sale credits a balance; it never sends money. Recording that the platform owes Amara ₦10,800 and actually transferring ₦10,800 to her bank are separate acts, possibly days apart. Because they're separate, you can offer instant payouts, weekly sweeps, or minimum-balance thresholds.

Let's create the checkout session

Call the Afriex create session endpoint to create a checkout session, and create an order row pointing at it.

// modules/orders/orders.service.ts
async createCheckoutSession(input: {
  productId: string;
  customerEmail: string;
  customerName: string;
  successUrl: string;
  cancelUrl: string;
}): Promise<{ sessionId: string; sessionUrl: string; provider: string }> {
  const product = await productsService.getPublishedById(input.productId);
  const provider = getPaymentProvider(resolveCheckoutProvider());
  const creator = await creatorsRepository.findById(product.creatorId);

  const result = await provider.createCheckoutSession({
    amount: product.price,
    currency: product.currency,
    customerEmail: input.customerEmail,
    customerName: input.customerName,
    successUrl: input.successUrl,
    cancelUrl: input.cancelUrl,
    metadata: {
      productId: product.id,
      creatorId: product.creatorId,
      creatorUserId: creator?.userId ?? '',
    },
  });

  await ordersRepository.create({
    productId: product.id,
    creatorId: product.creatorId,
    customerEmail: input.customerEmail,
    customerName: input.customerName,
    amount: product.price,
    currency: product.currency,
    paymentSessionId: result.sessionId,
  });

  return { sessionId: result.sessionId, sessionUrl: result.sessionUrl, provider: resolveCheckoutProvider() };
}

The API responds with sessionUrl, the frontend redirects Tunde there, and he pays on Afriex's page. Here's the provider side of that call:

// infra/payment/providers/afriex-checkout.ts
async createCheckoutSession(params: CreateCheckoutSessionParams): Promise<CheckoutSessionResponse> {
  const merchantReference = `co-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;

  const session = await afriex.checkout.createSession({
    amount: toMinorUnits(params.amount, params.currency),
    currency: params.currency,
    merchantReference,
    redirectUrl: params.successUrl,
    customer: {
      name: params.customerName,
      email: params.customerEmail,
      phone: params.customerPhone ?? params.metadata.customerPhone ?? '+2340000000000',
      countryCode: params.metadata.countryCode ?? 'NG',
    },
    channels: ['CARD', 'VIRTUAL_BANK_ACCOUNT', 'MOBILE_MONEY'],
    metadata: params.metadata,
  });

  return { sessionId: merchantReference, sessionUrl: session.checkoutUrl, provider: this.name };
}

Three details to slow down on:

toMinorUnits converts the amount before it leaves your server. Like most payment APIs, Afriex takes amounts in the currency's smallest unit (kobo for naira, cents for dollars). So Amara's ₦12,000.00 product is sent as 1200000.

channels decides what Tunde sees. The same call serves a card buyer in the US and a mobile-money buyer in Kenya. You list which channels the platform accepts; Afriex shows Tunde whichever of them work in his country.

merchantReference. When Afriex later reports "this session was paid," this reference is how you find which order it means.

One webhook, two writes

The only way to know when Tunde pays is when Afriex sends you a webhook event, CHECKOUT_SESSION.CREATED. Your server verifies the request signature to prove it came from Afriex, then acts on it.

One handler acts on the payment confirmation, and it makes both writes from the diagram:

// modules/sales/sales.controller.ts
if (provider.isCheckoutCompletedEvent(event)) {
  const metadata = provider.getMetadata(event);
  const sessionId = provider.getTransactionId(event);

  if (sessionId) {
    await ordersService.completeOrder(sessionId);
  }

  const creator = await creatorsService.getById(metadata.creatorId);
  const amount = provider.getAmount(event);
  const currency = provider.getCurrency(event);

  if (creator && amount && currency) {
    await salesService.recordConfirmedPayment({
      paymentIntentId: sessionId ?? 'unknown',
      creatorUserId: creator.userId,
      grossAmount: amount,
      currency: currency as 'USD' | 'NGN' | 'GHS' | 'KES',
    });
  }
}

completeOrder updates the orders.status to COMPLETED and issues the download token. recordConfirmedPayment is where this article's tables begin:

// modules/sales/sales.service.ts
async recordConfirmedPayment(event: ConfirmedPaymentEvent): Promise<Sale> {
  const existing = await salesRepository.findByPaymentIntentId(event.paymentIntentId);
  if (existing) return existing; // webhook replay — already processed

  const creator = await creatorsService.getByUserId(event.creatorUserId);
  const sale = await salesRepository.create({
    creatorId: creator.id,
    paymentIntentId: event.paymentIntentId,
    grossAmount: event.grossAmount,
    currency: event.currency,
    status: 'PAID',
  });

  await earningsService.processSale(sale);
  return sale;
}

That existing check exists because webhooks get delivered more than once. If your endpoint is slow to respond, or the connection drops after you processed the event but before Afriex has received your 200 OK response, it retries. Normal behavior, not a bug. Handle the same event twice naively and Amara gets credited ₦10,800 twice for one sale.

The check at the top is the fast path, but it's not the real protection. Two replays arriving at the same moment can both pass it before either inserts. The real protection is paymentIntentId which carries a UNIQUE constraint, so the second insert fails at the database no matter how the requests race.

Sale → earning → balance

processSale splits the money and credits Amara. Tunde paid ₦12,000, the platform fee is 10% (which is ₦1,200), then Amara gets ₦10,800.

// modules/earnings/earnings.service.ts
async processSale(sale: Sale): Promise<Earning> {
  const fee = computeFee(sale.grossAmount, env.PLATFORM_FEE_PERCENT);

  const earning = await earningsRepository.create({
    creatorId: sale.creatorId,
    saleId: sale.id,
    grossAmount: fee.grossAmount,
    platformFeeAmount: fee.platformFeeAmount,
    amount: fee.netAmount,
    currency: sale.currency,
    status: 'CONFIRMED',
  });

  // Credit the creator's balance in the sale currency — not the payout currency.
  await creatorsRepository.incrementBalance(sale.creatorId, fee.netAmount, sale.currency);

  // Gross settles into that currency's pool account; the fee stays platform revenue.
  const poolAccount = await poolAccountsService.getByCurrencyOrThrow(sale.currency);
  await poolAccountsService.settleSaleIntoPool(poolAccount.id, fee.grossAmount);

  return earning;
}

Notice there is no Afriex call in this function. It's pure bookkeeping, and it writes to two different kinds of account:

Amara's balance goes up by ₦10,800. This is a liability, money the platform owes her.
The NGN pool account goes up by ₦12,000. A pool account tracks the money the platform is actually holding in a given currency. The ₦1,200 gap between what the pool holds and what creators are owed is the platform's revenue.

Balances and pools are both tracked per currency. An NGN sale credits an NGN balance and settles into the NGN pool; a USD sale uses its own pool. Keeping the currencies in separate books means a report can always answer "how much NGN do we hold vs. owe?" without any exchange-rate assumptions. It's also why the withdrawal code below refuses to pay an NGN balance out to a USD bank account.

Onboarding Amara for payout

Before Amara can withdraw anything, she registers her bank account. This is the one step where the platform asks Afriex to confirm something is real rather than just storing what was typed:

// infra/afriex/afriex-client.ts
async registerRecipient(params: RegisterRecipientParams): Promise<RegisterRecipientResult> {
  const customer = await afriex.customers.create({
    fullName: params.fullName,
    email: params.email,
    phone: params.phone,
    countryCode: params.countryCode,
  });

  // A payment method is only VERIFIED when Afriex's own account-resolution
  // endpoint returns an account-holder name matching the creator's name on
  // file — creating the payment method alone proves nothing about whether
  // the account belongs to this creator.
  let verified = false;
  let resolvedAccountName: string | undefined;
  try {
    const resolved = await afriex.paymentMethods.resolveAccount({
      channel: 'BANK_ACCOUNT',
      accountNumber: params.accountNumber,
      institutionCode: params.bankCode,
      countryCode: params.countryCode,
    });
    resolvedAccountName = resolved.recipientName;
    verified = resolvedAccountName ? namesMatch(resolvedAccountName, params.fullName) : false;
  } catch {
    // Resolution failed — leave the method PENDING rather than guessing.
  }

  const paymentMethod = await afriex.paymentMethods.create({
    channel: 'BANK_ACCOUNT',
    customerId: customer.customerId,
    accountName: resolvedAccountName ?? params.fullName,
    accountNumber: params.accountNumber,
    countryCode: params.countryCode,
    institution: { institutionCode: params.bankCode, institutionName: params.bankName },
  });

  return {
    afriexCustomerId: customer.customerId,
    afriexPaymentMethodId: paymentMethod.paymentMethodId,
    verified,
  };
}

Account resolution is the step worth naming: when Amara provides her account number and bank code (gotten from the Afriex institutions list), Afriex verifies the account and returns the registered holder's name. Let's say "AMARA JOHNSON" is the name returned; namesMatch compares that against the name on her profile, and only a match marks the method VERIFIED.

The failure case is the reason this exists. If Amara fat-fingers one digit, the resolved name comes back as some stranger's, the match fails, and the method stays PENDING, instead of her first ₦10,800 payout landing in that stranger's account, unrecoverable. Only VERIFIED methods make a creator payoutEligible, and only eligible creators enter the scheduled sweep.

Requesting and disbursing a withdrawal

Amara can withdraw on demand, or a scheduled sweep can pay out every eligible creator's balance. Both paths converge on the same queue:

// modules/withdrawals/withdrawals.service.ts
async requestOnDemandWithdrawal(creatorId: string, amount?: string, currency?: CurrencyCode) {
  const creator = await creatorsRepository.findById(creatorId);
  this.assertCooldownElapsed(creator);

  const withdrawCurrency = currency ?? creator.payoutCurrency;
  const payoutMethod = await payoutMethodsService.getVerifiedMethodOrThrow(creatorId);
  if (payoutMethod.currency !== withdrawCurrency) {
    throw new ValidationError(`Your verified payout method is in ${payoutMethod.currency}.`);
  }

  const poolAccount = await poolAccountsService.getByCurrencyOrThrow(withdrawCurrency);
  return this.createAndQueue({ creator, payoutMethodId: payoutMethod.id, poolAccountId: poolAccount.id, amount: amount || available, currency: withdrawCurrency, trigger: 'ON_DEMAND' });
}

Queueing instead of calling Afriex inline matters because the transfer call can be slow, can fail, and needs retries, none of which should hold Amara's payout request open. The queue here is BullMQ, a Redis-backed job queue; a worker picks the job up and makes the actual call.

The worker, and the one distinction that protects the money

// infra/queue/worker.ts
try {
  const transfer = await afriexClient.createTransfer({
    customerId: payoutMethod.afriexCustomerId,
    paymentMethodId: payoutMethod.afriexPaymentMethodId,
    amount: withdrawal.amount,
    currency: withdrawal.currency,
    idempotencyKey: withdrawal.id,
  });

  await withdrawalsRepository.markProcessing(withdrawal.id, transfer.afriexTransactionId);
  await poolAccountsRepository.decrementBalance(poolAccount.id, withdrawal.amount);

  if (transfer.status === 'COMPLETED') {
    await withdrawalsRepository.markPaid(withdrawal.id);
  }
} catch (err) {
  const isFinalAttempt = job.attemptsMade + 1 >= (job.opts.attempts ?? 1);
  if (!isFinalAttempt) throw err; // let BullMQ retry

  if (isDefiniteRejection(err)) {
    // Afriex explicitly rejected the request (4xx, not a rate limit) —
    // safe to fail the withdrawal and credit the balance back.
    await failWithdrawal(withdrawal, err.message);
  } else {
    // Timeout, 5xx, or network error: Afriex may have already processed
    // the transfer server-side. Crediting the balance back here could
    // double-pay the creator if it did go through, so this is parked as
    // UNKNOWN for manual reconciliation instead of guessed at.
    await withdrawalsRepository.markUnknown(withdrawal.id, err.message);
  }
}

When the transfer call fails on its final retry, do we know for certain the money didn't move?

What happened	What it means	What the worker does
4xx rejection (bad account, insufficient pool)	Afriex definitely did not send money	Mark `FAILED`, credit Amara's balance back
Timeout, 5xx, network error	Afriex might have sent it before things broke	Mark `UNKNOWN`, touch nothing, flag for a human

The UNKNOWN state is the careful choice. Suppose the request timed out but Afriex actually completed the transfer. If the worker "helpfully" credited ₦10,800 back to Amara's balance, she'd have the money in her bank and the balance to withdraw it again: the platform pays twice. Parking the withdrawal for reconciliation by a human (or a later job) checking Afriex's transaction record against yours costs a support ticket. Guessing costs real money.

Closing the loop

Bank transfers aren't always instant, so a transfer that left in PROCESSING state gets its final answer by webhook, the same pattern as checkout:

// infra/afriex/afriex-webhook.router.ts
const { transactionId, status, meta } = payload.data;

// The idempotency key exists in our DB before the transfer call was even
// made, so looking withdrawals up by it — instead of by afriexTransactionId,
// which is only written after the call returns — means the webhook can
// never arrive "too early" to find its withdrawal.
const idempotencyKey = meta?.idempotencyKey;
const withdrawal = isUuid(idempotencyKey)
  ? await withdrawalsRepository.findById(idempotencyKey)
  : await withdrawalsRepository.findByAfriexTransactionId(transactionId);

if (status === 'COMPLETED' || status === 'SUCCESS') {
  await withdrawalsRepository.markPaid(withdrawal.id);
} else if (status === 'FAILED' || status === 'CANCELLED' || status === 'REJECTED') {
  await withdrawalsRepository.markFailed(withdrawal.id, `Afriex reported ${status}`);
  await creatorsRepository.incrementBalance(withdrawal.creatorId, withdrawal.amount, withdrawal.currency);
  await poolAccountsRepository.incrementBalance(withdrawal.poolAccountId, withdrawal.amount);
}

The idempotency key sent to Afriex is the withdrawal's own database ID, chosen before the transfer call, not after. Because the ID existed in Postgres first, the confirmation webhook can always find its withdrawal by that key, even if it somehow arrives before the transfer call's response was recorded. Sending a key also means a retried createTransfer with the same key can't produce a second transfer on Afriex's side, the same double-send protection Part 1's unique constraint gave orders, now on the provider's side of the wire.

Same handler shape as checkout: verify the signature, find the row this event is about, move it to a terminal state, and, on failure, put the money back where it came from, in both books.

Where we are

✅ Tunde pays through a hosted checkout: card, bank transfer, or mobile money
✅ One webhook completes his order and records Amara's sale
✅ A 10% fee split leaves ₦10,800 on Amara's NGN balance and ₦12,000 in the NGN pool
✅ Amara's bank account is verified by name before it can receive money
✅ Withdrawals retry, refund on definite failure, and park as UNKNOWN when the outcome is uncertain

The Afriex Business API's multi-currency payout support gives you the opportunity to send and receive payments globally, whether the goal is personal or business, small team or large enterprise. The docs cover everything this series didn't touch.

The full source for this project, including the withdrawal cooldown, minimum-amount logic, and the scheduled sweep cron, is on GitHub. Questions or feedback? Drop them in the comments or reach out on X @codewithveek.

Build a Digital Marketplace with Afriex, Fastify and Postgres, Part 1: Data Model and the Storefront

Victory Lucky — Sat, 15 Aug 2026 18:25:07 +0000

Amara designs Lightroom presets in Lagos. She wants to sell a pack for ₦12,000 to buyers in Nigeria, Ghana, Kenya, and the US.

Tunde wants to buy that pack. He wants to pay with his card, get the download link in his inbox, and never create an account.

Amara wants the ₦12,000 to land in her bank account.

That is the whole product. You've probably used it before: it's Gumroad, or Selar if you're in Nigeria. This series builds a small version of the same thing, and like those platforms, it splits cleanly in two:

Everything up to "a paid order exists" is a storefront. Products, listings, carts, orders. Mostly reads and writes to your own database.
Everything after that is payments. Charging Tunde, tracking what you owe Amara, paying her out.

This series keeps the halves apart on purpose:

Part 1 (this article): the four tables and the Fastify API that serve the storefront. No payment provider is involved anywhere in it.
Part 2: wiring Afriex into what Part 1 built: Checkout to collect Tunde's money, Payouts to send Amara hers.

The full source is on GitHub: a Fastify + Postgres backend with a Next.js storefront on top. This article covers the backend.

What you'll have at the end

A running API where:

A creator can sign in, create a product, and publish it.
Anyone can list published products and view one, without an account.
An order can be created for a product and later marked paid.
A paid order hands back a download link that expires.

No money moves. That's Part 2's job, and it will not require changing a single table you build here.

Before you start

You need Node 20+, Docker, and a terminal. You should have built a REST API before, in any framework. You do not need to have used Fastify or Drizzle; I will explain everything step by step.

The repo ships a docker-compose.yml that starts Postgres (and Redis, which Part 2's payout queue will need), so there's nothing to install by hand:

git clone https://github.com/codewithveek/afriex-creator-payout
cd afriex-creator-payout
docker compose up -d        # starts Postgres and Redis

cd server
cp .env.example .env
pnpm install
pnpm db:migrate
pnpm dev                    # API on http://localhost:4000

In .env, set DATABASE_URL to match the compose credentials:

DATABASE_URL=postgresql://afriex:afriex_dev_password@localhost:5432/afriex_creator_payout

If you'd rather run your own Postgres 16+, skip the compose step and point DATABASE_URL at it instead.

Let's start from what the app has to do

Before writing any schema, let's write down the actions as a list:

A creator lists a product for a price in a currency.
A creator keeps a product hidden while they're still editing it.
Anyone can browse published products.
A buyer buys one product, with or without an account.
A buyer gets a download link that only works for them.
Later, the platform pays the creator.

Those six list items are the schema. Item 1 needs creators and products. Item 4 needs orders and an optional customers. Item 6 is Part 2.

The four tables

creators: people who sell. This table holds the payout details Part 2 will read.
products: what they sell.
customers: people who bought and chose to create an account.
orders: one row per purchase attempt.

Four design decisions in there are worth walking through slowly, because each one prevents a specific bug.

Decision 1: buyers and sellers live in separate tables

Amara is a creator. Tunde is a customer. Amara might also buy someone else's presets, so she can be both, but the platform never forces it.

More importantly, Tunde can buy without an account at all. He types his email at checkout and leaves. That's a guest checkout, and it's why orders.customer_id is nullable:

customerId: uuid('customer_id').references(() => customers.id, { onDelete: 'set null' }),

The order still stores his email and name directly, so you can email him the download link whether or not a customers row exists.

If you'd instead forced every buyer through a shared users table, you'd have to create an account for Tunde before he can pay. That's a signup form standing between a willing buyer and a checkout button. Notice that Gumroad and Selar both let you buy with nothing but an email for exactly this reason.

Decision 2: money is `numeric(14, 2)`, never a float

Postgres has a real and a double precision type. Don't reach for either. Here's why, in a Node REPL:

> 16.08 * 3           // three copies of a $16.08 product
48.239999999999995

> 4.35 * 100          // converting $4.35 to cents
434.99999999999994

> Math.round(1.005 * 100) / 100   // rounding $1.005 to the nearest cent
1                     // not 1.01

Floating-point numbers store binary fractions. Decimal amounts like 16.08 have no exact binary form, so every arithmetic operation drifts by a fraction of a cent. Do that across a few thousand orders and a payout report stops matching the ledger.

numeric stores digits exactly:

price: numeric('price', { precision: 14, scale: 2 }).notNull(),

precision: 14 means up to 14 total digits. scale: 2 means two of them sit after the decimal point. That's up to $999,999,999,999.99 per product, more headroom than any preset pack needs, and cheap to keep.

One thing that catches people: the Postgres driver returns numeric columns to JavaScript as strings, not numbers, precisely so it doesn't lose the precision you just paid for. So product.price is "16.08". If you do product.price * 3 you're back in float land. Do money arithmetic either in SQL or with a decimal library like decimal.js.

Decision 3: currency is an enum, not a `varchar`

// infra/database/schema/enums.ts
export const currencyEnum = pgEnum('currency', ['USD', 'NGN', 'GHS', 'KES']);

export const orderStatusEnum = pgEnum('order_status', [
  'PENDING',
  'COMPLETED',
  'REFUNDED',
  'FAILED',
]);

A Postgres enum is a custom type with a fixed list of allowed values. Insert anything outside the list and the database rejects the row.

With a varchar currency column, nothing stops 'ngn', 'NGN ', 'Naira', and 'NGN' from all ending up in the same column, and then a payout query that filters WHERE currency = 'NGN' silently misses orders. The enum makes that impossible at the storage layer instead of hoping every code path remembers to normalize.

products.currency, orders.currency, and Part 2's payout tables all reference this same type. Adding a fifth currency means writing a migration (ALTER TYPE currency ADD VALUE 'ZAR'), which is exactly the amount of friction supporting a new corridor deserves.

In Postgres 12 and later you can add an enum value inside a transaction, but you can't use the new value until that transaction commits. Keep the ADD VALUE migration separate from any migration that writes rows with it.

Decision 4: how to search an encrypted email column

Emails are encrypted at rest, so customers.email holds ciphertext rather than tunde@example.com.

That breaks a query you will absolutely need. Tunde checks out as a guest today. Next month he creates an account with the same address, and you want to attach his old orders to it. The natural query is:

SELECT * FROM orders WHERE customer_email = 'tunde@example.com';

That returns nothing. Proper encryption is randomized: encrypting the same email twice produces two different ciphertexts, on purpose, so an attacker with the database can't tell which two customers share an address. Randomized ciphertext means equality comparison is off the table.

The fix is a blind index: a second column holding a keyed hash of the value, used only for exact-match lookups.

// infra/crypto/blind-index.ts
import { createHmac } from 'node:crypto';

export function emailBlindIndex(email: string): string {
  const normalized = email.trim().toLowerCase();
  return createHmac('sha256', BLIND_INDEX_KEY).update(normalized).digest('hex');
}

customerEmail: text('customer_email').notNull(),                                    // ciphertext
customerEmailHash: varchar('customer_email_hash', { length: 64 }).notNull().default(''), // blind index

Lookups then run against the hash, never the plaintext:

const hash = emailBlindIndex(input.email);
const previousOrders = await db.query.orders.findMany({
  where: eq(orders.customerEmailHash, hash),
});

Three details that matter:

HMAC, not plain SHA-256. There are only so many plausible email addresses. Someone holding a table of plain hashes can grind through a wordlist and recover addresses in minutes. HMAC mixes in a secret key that lives outside the database, so a stolen dump is useless without it.
Normalize before hashing. Tunde@Example.com and tunde@example.com must produce the same hash, or the lookup misses.
Exact match only. You can't do LIKE '%@gmail.com' or sort alphabetically on a blind index. If you need those, you need a different design, usually a searchable subset stored separately, with its own risk tradeoff.

The products table

// infra/database/schema/products.ts
export const products = pgTable(
  'products',
  {
    id: uuid('id').primaryKey().defaultRandom(),
    creatorId: uuid('creator_id').notNull().references(() => creators.id, { onDelete: 'cascade' }),

    name: varchar('name', { length: 255 }).notNull(),
    description: text('description'),
    price: numeric('price', { precision: 14, scale: 2 }).notNull(),
    currency: currencyEnum('currency').notNull().default('USD'),

    fileUrl: varchar('file_url', { length: 512 }),
    fileName: varchar('file_name', { length: 255 }),
    fileSize: numeric('file_size', { precision: 14, scale: 0 }),

    published: boolean('published').notNull().default(false),

    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    index('idx_products_creator').on(table.creatorId),
    index('idx_products_published').on(table.published),
    index('idx_products_published_created').on(table.published, table.createdAt),
    index('idx_products_creator_published').on(table.creatorId, table.published),
  ],
);

published replaces a drafts table. A product Amara is still writing copy for has published = false and never appears in public queries. One boolean, one table, nothing to keep in sync.

The indexes exist because of specific queries. Don't add indexes by vibes: every index slows down writes and costs disk. Each one here has a query behind it:

Index	The query it serves
`(published, created_at)`	The public storefront feed: newest published products first
`(creator_id, published)`	Amara's dashboard, filtered to her live products
`(creator_id)`	Everything else scoped to one creator

The order of columns in a composite index matters. Postgres can use (published, created_at) for a query that filters on published alone, but not for one that filters on created_at alone, because an index is usable from its leftmost column rightward. Put the column you filter for equality first, the one you sort or range-scan second.

How a request travels through the app

Every domain (products, orders, customers, and creators) has the same number of files. app.ts only bolts modules together:

// app.ts
export async function buildApp() {
  const app = Fastify({ /* ... */ });

  await app.register(productsRoutes);
  await app.register(ordersRoutes);
  await app.register(customersRoutes);

  return app;
}

Here's what each layer is allowed to do:

Layer	Its one job	May import
Router	Declare the URL and which guards run before it	Controller, middleware
Controller	Read the HTTP request, shape the HTTP response	Service
Service	Enforce the business rules	Repository
Repository	Talk to Postgres	Drizzle, schema

A controller never writes SQL. A repository never knows an HTTP request exists. That's the whole convention, and it's what lets Part 2 add a payments module without editing any of these files.

The router: the access model in one screen

// modules/products/products.router.ts
export async function productsRoutes(fastify: FastifyInstance) {
  fastify.post('/api/products', {
    preHandler: [authenticate, authorize(Role.CREATOR), validateBody(CreateProductSchema)],
    handler: productsController.create,
  });

  fastify.get('/api/products/mine', {
    preHandler: [authenticate, authorize(Role.CREATOR)],
    handler: productsController.listMyProducts,
  });

  // No preHandler. This is the public storefront feed.
  fastify.get('/api/products', {
    handler: productsController.listPublished,
  });

  fastify.get('/api/products/:id', {
    handler: productsController.getById,
  });
}

preHandler is Fastify's term for functions that run before the route handler and can reject the request early. Reading this one file tells you exactly who can access what: creating and listing your own products needs a creator session; the public feed and the product page need nothing.

The controller, and a leak it prevents

// modules/products/products.controller.ts
function sanitizeForPublic(product: Record<string, unknown>) {
  const { fileUrl, fileName, fileSize, ...rest } = product;
  return rest;
}

export const productsController = {
  async listPublished(request: FastifyRequest, reply: FastifyReply) {
    const pag = parsePagination(request.query as Record<string, unknown>);
    const { rows, total } = await productsService.getPublished(
      (pag.page - 1) * pag.pageSize,
      pag.pageSize,
    );
    return reply.code(200).send({
      data: rows.map(sanitizeForPublic),
      meta: buildPaginationMeta(pag, total),
    });
  },
};

sanitizeForPublic strips the file fields from a product before it goes out in a public response.

The same products row backs two very different responses: Amara's dashboard, where she needs to see her uploaded file, and the public feed, where fileUrl is the paid download. Forget to strip it and GET /api/products looks like this:

// leaking
{
  "id": "9d1b…",
  "name": "Lagos Golden Hour Presets",
  "price": "12000.00",
  "fileUrl": "https://cdn.example.com/files/lagos-presets.zip"  // 👈 free for everyone
}

Instead of what it should be:

{
  "id": "9d1b…",
  "name": "Lagos Golden Hour Presets",
  "price": "12000.00",
  "currency": "NGN"
}

You could solve it with a second table or a database view. Stripping the fields once, at the HTTP boundary, is less machinery, as long as it happens in one function that every public response goes through, rather than being re-remembered at each endpoint.

The service: this is where the business rules live

// modules/products/products.service.ts
async update(creatorId: string, productId: string, input: Record<string, unknown>): Promise<Product> {
  const product = await productsRepository.findById(productId);
  if (!product) throw new NotFoundError('Product not found');
  if (product.creatorId !== creatorId) throw new NotFoundError('Product not found');
  return (await productsRepository.update(productId, input))!;
}

Notice that both failures throw the same NotFoundError.

That's deliberate. If "you don't own this" returned a 403 and "no such product" returned a 404, then a creator could loop through product IDs and use the status codes to map out the catalogue: 403 means "real product, someone else's", 404 means "nothing here". Returning 404 for both tells the prober nothing. The cost is that a creator debugging their own integration sees a slightly less helpful error, a fair trade, and one worth writing in a comment so nobody "fixes" it later.

The repository: the only file that interacts with Drizzle

// modules/products/products.repository.ts
async findPublished(offset: number, limit: number): Promise<{ rows: Product[]; total: number }> {
  const rows = await db.query.products.findMany({
    where: eq(products.published, true),
    orderBy: (p, { desc }) => [desc(p.createdAt)],
    offset,
    limit,
  });
  const total = await db.$count(products, eq(products.published, true));
  return { rows, total };
}

The orders table, where the storefront stops

// infra/database/schema/orders.ts
export const orders = pgTable(
  'orders',
  {
    id: uuid('id').primaryKey().defaultRandom(),
    productId: uuid('product_id').notNull().references(() => products.id, { onDelete: 'restrict' }),
    creatorId: uuid('creator_id').notNull().references(() => creators.id, { onDelete: 'restrict' }),
    customerId: uuid('customer_id').references(() => customers.id, { onDelete: 'set null' }),

    customerEmail: text('customer_email').notNull(),
    customerEmailHash: varchar('customer_email_hash', { length: 64 }).notNull().default(''),
    customerName: text('customer_name').notNull(),

    amount: numeric('amount', { precision: 14, scale: 2 }).notNull(),
    currency: currencyEnum('currency').notNull(),
    status: orderStatusEnum('status').notNull().default('PENDING'),

    paymentSessionId: varchar('payment_session_id', { length: 255 }).notNull().unique(),

    downloadTokenEncrypted: text('download_token_encrypted'),
    downloadTokenHash: varchar('download_token_hash', { length: 64 }),
    downloadTokenExpiresAt: timestamp('download_token_expires_at', { withTimezone: true }),

    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
  },
);

The order row exists before any money moves

When Tunde clicks Buy, the API writes a PENDING order first, with a paymentSessionId, and only then calls the payment provider. Later, a confirmation flips the row to COMPLETED.

That ordering does real work. paymentSessionId is unique, which makes order creation idempotent: if Tunde double-clicks Buy or his phone retries the request on a flaky connection, the second insert hits a unique-constraint violation instead of creating a second order and a second charge. Running it twice with the same session has the same effect as running it once.

Creating an order looks like this:

curl -X POST http://localhost:3000/api/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "9d1b…",
    "customerEmail": "tunde@example.com",
    "customerName": "Tunde A."
  }'

{
  "data": {
    "id": "4f22…",
    "status": "PENDING",
    "amount": "12000.00",
    "currency": "NGN",
    "paymentSessionId": "sess_01HZ…"
  }
}

At this point in Part 1, paymentSessionId is generated locally. In Part 2 it becomes the ID Afriex hands back when you open a checkout session, and nothing else on this page changes.

Download access is a token, not a boolean

A paid order gets a signed download token. The raw token goes out by email or redirect; the database only ever stores downloadTokenHash. Every download request hashes the incoming token and compares.

The reason is a bad day. If someone reads your database, hashes give them nothing usable: they can't reverse a hash into a working token. Storing raw tokens would hand them working download links for every order you've ever fulfilled.

downloadTokenExpiresAt limits the other bad day: a link forwarded into a WhatsApp group stops working in 24 hours instead of forever.

The delete rules encode what each row means

productId: ... { onDelete: 'restrict' }
creatorId: ... { onDelete: 'restrict' }
customerId: ... { onDelete: 'set null' }

restrict means Postgres refuses to delete a product or creator that has orders. An order is a financial record. If Amara deletes a product, the row proving Tunde paid ₦12,000 for it must survive; you'll need it for refunds, support, and Part 2's payouts. Deactivate products; don't delete them.

set null on the customer is the opposite case. If Tunde deletes his account, the order stays (you still owe Amara for it) and simply stops pointing at a customer.

What this table deliberately doesn't know

Nowhere in orders is there a column naming a payment provider. Stripe, Paystack, Afriex Checkout: the schema can't tell which one confirmed the payment.

That's what makes Part 2 an additive change. Whatever collects the money has exactly one job against this table: flip PENDING to COMPLETED. Everything downstream (the download token, Amara's dashboard, Tunde's order history) already works off status.

Where we are

You now have a storefront that runs on its own:

✅ Amara can create a product and publish it
✅ Anyone can browse published products, without leaking the file URL
✅ An order can be created for a guest buyer and marked paid
✅ A paid order yields an expiring download link
❌ No money has actually changed hands

Part 2 adds exactly two things, and neither one touches the tables above:

A checkout module that opens an Afriex checkout session and stores its ID in orders.paymentSessionId.
A webhook handler that verifies Afriex's callback and flips orders.status to COMPLETED.

Then Amara's payouts. This is also where the platform comparison shows the true capabilities of Afriex: Selar pays creators out locally, but Afriex disburses across 30+ countries (bank transfer in Nigeria, mobile money in Kenya or Ghana, SWIFT to the US or UK), so the same payout module works whether Amara banks in Lagos or her co-creator banks in Nairobi.

In the next part of this series, you will learn how to integrate the Afriex Business API into everything built here: creating hosted checkout sessions so buyers can pay by card, bank transfer, or mobile money, handling the webhook that confirms a payment and completes the order, splitting each sale into the platform fee and the creator's earnings, verifying a creator's bank account before any money is sent to it, and disbursing payouts on demand or on a schedule. See you in Part 2.

How to Accept International Payments as an African Developer or Business

Victory Lucky — Thu, 30 Jul 2026 18:44:40 +0000

If you're an African developer, SaaS founder, freelancer, or online business, one of the biggest challenges isn't finding customers. It's getting paid by them.

Most articles about African payment APIs focus on moving money out of Africa. But what if your customers are the ones sending money to you?

Whether you're billing international clients, collecting subscription payments, or accepting payments from marketplace users, you need a collection method that's easy for customers and simple to reconcile on your end.

The Afriex Business API offers three different ways to collect payments, each designed for a different use case. Depending on who your customers are and how they prefer to pay, you can collect funds through dedicated virtual accounts, shared pool accounts, or stablecoin wallets.

In this guide, you'll learn how each collection method works, when to use it, and how to integrate it into your application.

The Three Collection Methods

Although all three collection methods ultimately deposit funds into your Afriex Business wallet, they differ in how customers send money and how you identify who made each payment.

Method	Best for	How the payer sends
Dedicated virtual account	Known customers, repeat payments	Bank transfer to a unique account number
Pool account	Quick collection, one-off payments	Bank transfer with a reference
Crypto wallet	Customers holding USDT or USDC	Crypto transfer to a wallet address

Choosing the right method depends on your product and your payment flow. If you already know your customers and expect them to pay repeatedly, dedicated virtual accounts provide the smoothest experience. If you want to launch quickly without creating individual accounts for every customer, pool accounts are a great fit. And if your users prefer paying with stablecoins, crypto wallets make that process straightforward.

Method 1: Dedicated Virtual Accounts

Dedicated virtual accounts are the easiest way to reconcile bank transfers from repeat customers.

Instead of asking every customer to send money to the same account and include a payment reference, each customer receives their own unique bank account number. Any payment that arrives in that account automatically belongs to that customer, so there's no manual matching or reconciliation required.

This approach works especially well for:

SaaS products with recurring subscriptions
Marketplaces that maintain seller balances
Businesses collecting repeat payments from customers
Platforms serving African businesses that pay through bank transfers

Afriex supports two types of dedicated virtual accounts:

Static virtual accounts remain permanently assigned to a customer, making them ideal for ongoing billing relationships.
Dynamic virtual accounts are temporary. They're tied to a specific payment amount and expire after a short period, making them a good choice for invoices and one-time payments.

Creating a Static or Dynamic Virtual Account

import { afriex } from "@/lib/afriex";

// Static virtual account — permanent, for repeat payments
const staticAccount = await afriex.paymentMethods.createVirtualAccount({
  currency: "NGN",
  customerId: "your-customer-id",
  label: "COLLECTIONS",
});

// Dynamic virtual account — expires after a short window, for a single invoice
const dynamicAccount = await afriex.paymentMethods.createVirtualAccount({
  currency: "NGN",
  customerId: "your-customer-id",
  amount: 150000, // exact amount expected
});

// Both return a real account number and bank name to share with the customer
console.log(staticAccount.data.accountNumber); // e.g. "3820404958"
console.log(staticAccount.data.institution.institutionName); // e.g. "FIDELITY BANK"

Once you've created the account, share the returned account number and bank name with your customer. Behind the scenes, Afriex automatically associates every payment with the customer that owns that virtual account, eliminating the need for payment references or manual reconciliation.

Reusing Existing Accounts

Creating static virtual accounts is idempotent. If you request another static account for the same customer and currency, Afriex returns the existing account instead of generating a new one.

A good practice is to check whether an account already exists before creating one.

const existing = await afriex.paymentMethods.listVirtualAccounts({
  currency: "NGN",
  customerId: "your-customer-id",
});

if (existing.data.length === 0) {
  // Create one
  await afriex.paymentMethods.createVirtualAccount({
    currency: "NGN",
    customerId: "your-customer-id",
    label: "COLLECTIONS",
  });
}

This approach keeps your integration predictable while ensuring each customer maintains a single permanent account for recurring payments.

NGN Requirements

If you're creating static NGN virtual accounts, the customer must have a Bank Verification Number (BVN) on file. This is a regulatory requirement set by the Central Bank of Nigeria.

You can provide the BVN when creating the customer or update it later through the customer KYC endpoint.

Dynamic virtual accounts don't have this requirement.

At the time of writing, dedicated virtual accounts has support for NGN, USD, GBP, and EUR accounts.

Method 2: Pool Accounts

Pool accounts are the fastest way to start accepting bank transfers when you don't need a dedicated account number for every customer.

Instead of creating individual virtual accounts, Afriex provides a shared account for a specific country. Every customer pays into the same account, while a unique payment reference identifies who the payment belongs to.

This approach significantly reduces the setup required, making it a great choice for products that need to start collecting payments quickly.

The trade-off is that your application becomes responsible for keeping track of the payment reference associated with each customer. Though as long as those references are stored correctly, reconciling incoming deposits remains straightforward.

Retrieving a Pool Account

import { afriex } from "@/lib/afriex";

const poolAccount = await afriex.paymentMethods.listPoolAccounts({
  country: "NG",
  customerId: "your-customer-id",
});

// Share both pieces with the customer
console.log(poolAccount.data.accountNumber);  // the shared account number
console.log(poolAccount.data.reference);       // unique to this customer

Unlike dedicated virtual accounts, there isn't a separate account number for each customer. Everyone transfers money to the same bank account, but each customer receives their own unique reference, which must be included when making the payment.

When the transfer arrives, Afriex uses that reference to identify which customer made the payment and credits it accordingly.

Store the Reference Before Sharing It

The payment reference is the key to matching an incoming transfer to the correct customer. Because of that, you should save it immediately after retrieving the pool account details.

A good pattern is to persist the payment details first, then send the payment instructions to the customer.

// Store reference before sharing account details with customer
await db.insert(pendingPayments).values({
  customerId: "your-customer-id",
  afriexReference: poolAccount.data.reference,
  expectedAmount: 50000,
  currency: "NGN",
  createdAt: new Date(),
});

// Then share account details with your customer
const paymentInstructions = {
  bank: poolAccount.data.institution.institutionName,
  accountNumber: poolAccount.data.accountNumber,
  accountName: poolAccount.data.accountName,
  reference: poolAccount.data.reference, // customer MUST include this
  amount: 50000,
};

Persisting the reference helps ensure every transfer can be matched correctly, even if the customer completes the payment hours or days later.

Country-Based Accounts

Pool accounts are provisioned per country. You simply provide the appropriate country code, and Afriex returns the shared account for that market.

There's no need to specify the currency separately because it's derived automatically from the country. For example, passing NG returns an account that accepts NGN payments.

Method 3: Crypto Wallets (USDT / USDC)

Not every customer prefers paying through a bank transfer. Some already hold stablecoins and would rather pay directly from their crypto wallet.

For these customers, Afriex lets you generate dedicated wallet addresses for supported stablecoins such as USDT and USDC.

When funds arrive, Afriex automatically converts the deposit to its USD equivalent and records it as a DEPOSIT transaction in your business wallet. That means you don't need to perform a separate conversion step before reconciling payments.

Creating or Retrieving a Customer Wallet

import { afriex } from "@/lib/afriex";

// Get or create a USDT wallet for a specific customer
const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT",
  customerId: "your-customer-id",
});

console.log(wallet.data.addresses);
// Returns addresses on multiple networks, e.g:
// [
//   { address: "0x1234...5678", network: "ETHEREUM_MAINNET" },
//   { address: "TYASr5...HLS",  network: "TRON_MAINNET" }
// ]

The response contains wallet addresses for multiple blockchain networks. Share the address that matches the network your customer intends to use.

For many customers, Tron is the preferred option because transaction fees are generally lower than on Ethereum.

The wallet creation endpoint is idempotent, so requesting a wallet for the same customer and asset returns the same address instead of creating a new one each time.

Detecting Crypto Deposits

Crypto deposits work a little differently from bank transfers.

Instead of sending a webhook when funds arrive, you'll need to periodically check your transaction history for new DEPOSIT records.

const recentDeposits = await afriex.transactions.list({
  type: "DEPOSIT",
});

Your application can poll this endpoint at a suitable interval and process any newly discovered deposits.

Keep in mind that crypto wallets are available only in production and require the customer to complete verification before a wallet can be created.

Knowing When a Deposit Has Landed

Collecting payments is only one part of the integration. Your application also needs a reliable way to know when funds have actually arrived so you can update balances, fulfill orders, or unlock access for customers.

For payments made through dedicated virtual accounts and pool accounts, Afriex sends a webhook whenever a deposit is received. Instead of repeatedly checking for new transactions, your application can simply listen for these events and react as they happen.

Handling Deposit Webhooks

import { afriex } from "@/lib/afriex";

export async function POST(req: Request) {
  const signature = req.headers.get("x-webhook-signature");
  if (!signature) {
    return Response.json({ error: "Missing signature" }, { status: 401 });
  }

  // Read raw body before any parsing — signature is verified against these exact bytes
  const rawBody = await req.text();

  let event;
  try {
    event = afriex.webhooks.verifyAndParse(rawBody, signature);
  } catch {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }

  if (event.event === "TRANSACTION.CREATED" && event.data.type === "DEPOSIT") {
    const { transactionId, destinationAmount, destinationCurrency } = event.data;

    // Attribute the deposit to the right customer and update your records
    await recordDeposit({
      transactionId,
      amount: destinationAmount,
      currency: destinationCurrency,
    });
  }

  return Response.json({ received: true });
}

A few implementation details are worth paying attention to:

Always verify the webhook signature before processing the request.
Read the raw request body before parsing it. Signature verification depends on the original payload.
Respond quickly after processing the event. Long-running work should happen asynchronously whenever possible.

These practices help keep your webhook endpoint secure and reliable in production.

Registering Your Webhook

Once your endpoint is ready, register it in the Afriex dashboard under Developers > Webhooks.

You'll also need to configure your application with the AFRIEX_WEBHOOK_PUBLIC_KEY, which is used to verify incoming webhook signatures.

Your webhook should return an HTTP 200 response within five seconds. If it doesn't, Afriex automatically retries delivery using exponential backoff, giving your application multiple chances to process the event successfully.

For a complete walkthrough of every available webhook event and recommended handling patterns, see the Afriex webhook integration guide:

Choosing the Right Collection Method

Each payment method solves a different problem, so the right choice depends on how your customers pay and how much reconciliation you want your application to handle.

Use Dedicated Virtual Accounts if...

Choose dedicated virtual accounts when your customers are known ahead of time and are likely to make repeat payments.

Since every customer receives a unique bank account number, incoming transfers are automatically attributed to the correct customer. This eliminates manual reconciliation and provides the smoothest experience for subscription platforms, marketplaces, and businesses with recurring billing.

Use Pool Accounts if...

Pool accounts are the better option when you want to start accepting payments quickly without creating virtual accounts for every customer.

Although you'll need to store and match payment references yourself, the integration is lighter and requires less operational overhead, making it an excellent choice for products that prioritize speed of implementation.

Use Crypto Wallets if...

Crypto wallets are ideal when your customers already hold USDT or USDC and prefer paying with stablecoins instead of making bank transfers.

Learn More

If you like to explore each payment method in more detail, these guides provide a deeper look at their individual integration flows:

*
How to accept USDT and USDC
Virtual accounts and pool accounts

You can also explore the Afriex Business platform and API documentation here:

Final Thoughts

There's no single payment collection method that's right for every product.

If your business relies on repeat customers, dedicated virtual accounts provide the simplest reconciliation experience. If speed matters more than individual account management, pool accounts let you start collecting payments with minimal setup. And if your customers already use stablecoins, crypto wallets offer a familiar way to pay while Afriex handles the conversion behind the scenes.

By offering multiple collection methods through a single API, you can support different customer preferences without maintaining separate payment integrations.

Whether you're building a SaaS platform, marketplace, fintech product, or any business that serves customers across borders, the Afriex Business API gives you the flexibility to accept payments in the way that best fits your users.

Build a Remittance App with the Afriex Cross-border API

Victory Lucky — Tue, 30 Jun 2026 22:54:02 +0000

Sending money across borders involves more moving parts than most developers expect. You need to know the live exchange rate before the user confirms. You need to register the recipient correctly. You need to attach their bank account or mobile wallet. You need to trigger the transfer and then track it through to settlement. And you need to handle failures gracefully when something goes wrong in the corridor.

Most of that complexity is what the Afriex Cross-border API is built to handle. This article walks through the full remittance flow — from registering a sender to confirming delivery, using the Afriex SDK from start to finish.

Get your API key

Everything starts at business.afriex.com. Create a Business account if you do not have one. Once you are in:

Go to Developer then API Keys
Click Create new keys
Give it a name (e.g. "Remittance App")
Set the permissions your use case needs — for a remittance app, you need at minimum: View wallet balances, Initiate withdrawals, View payment methods, and Add or manage payment methods
Copy the key immediately. You cannot view it again after leaving the page.

Store it as an environment variable:

AFRIEX_API_KEY=your-api-key-here
AFRIEX_ENVIRONMENT=staging  # switch to production when you go live

Start in the staging environment so nothing real moves while you build.

Install and initialize the SDK

npm install @afriex/sdk

Initialize once and reuse the instance across your application:

// src/lib/afriex.ts
import { Afriex } from "@afriex/sdk";

export const afriex = new Afriex({
  apiKey: process.env.AFRIEX_API_KEY!,
  environment:
    (process.env.AFRIEX_ENVIRONMENT as "staging" | "production") ?? "staging",
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
});

The retryConfig handles transient failures automatically. If the Afriex API returns a 429 or a 503, the SDK retries up to three times with a delay between attempts, so you do not have to write that logic yourself. The webhookPublicKey is used later for signature verification, you can get it from the Developers > Webhooks section of your dashboard.

Step 1: Show the live exchange rate

Before anything else, show the sender what rate they are getting. A remittance user deciding between providers makes that decision based on the rate they see. Never show a hardcoded or cached rate — always fetch live.

import { afriex } from "@/lib/afriex";

async function getRate(from: string, to: string) {
  const result = await afriex.rates.getRates({
    fromSymbols: from,
    toSymbols: to,
  });

  const rate = result?.rates?.[from]?.[to];

  if (!rate) {
    throw new Error(`Rate not available for ${from}/${to}`);
  }

  return parseFloat(rate);
}

// Usage: sender sends USD, recipient gets NGN
const rate = await getRate("USD", "NGN");
console.log(`1 USD = ${rate} NGN`);

This call returns the live mid-market rate for the currency pair. Show it to the user with a clear note about when it was fetched, since rates can shift between the moment they see it and the moment they confirm. The rate the user sees is informational — the actual conversion happens on Afriex's end when the transaction is created.

Step 2: Create the recipient as a customer

The recipient needs to exist in the Afriex system before you can attach a payment method or send them money. This is a one-time step per recipient.

import { afriex } from "@/lib/afriex";

async function registerRecipient(details: {
  fullName: string;
  email: string;
  phone: string;
  countryCode: string;
}) {
  const customer = await afriex.customers.create({
    fullName: details.fullName,
    email: details.email,
    phone: details.phone,         // E.164 format, e.g. +2348012345678
    countryCode: details.countryCode, // ISO 3166-1 alpha-2, e.g. NG, KE, GH
  });

  return customer;
}

const recipient = await registerRecipient({
  name: "Victory Lucky",
  email: "victory@example.com",
  phone: "+2348012345678",
  countryCode: "NG",
});

console.log(recipient.customerId); // store this — you need it in every subsequent call

Save the customerId that comes back. Every subsequent API call references this ID rather than the recipient's personal details.

If you are building a product where senders send to the same recipient repeatedly (for example, a diaspora parent sending to family), store the customerId against the recipient record in your own database on first creation and skip this step for future transfers.

Step 3: Attach the recipient's payment method

Now tell Afriex where to send the money — the recipient's bank account or mobile wallet.

Bank account

async function attachBankAccount(params: {
  customerId: string;
  accountName: string;
  accountNumber: string;
  institutionCode: string; // bank code, e.g. "058" for GTBank Nigeria
  institutionName: string;
  countryCode: string;
}) {
  const paymentMethod = await afriex.paymentMethods.create({
    customerId: params.customerId,
    channel: "BANK_ACCOUNT",
    accountName: params.accountName,
    accountNumber: params.accountNumber,
    countryCode: params.countryCode,
    institution: {
      institutionCode: params.institutionCode,
      institutionName: params.institutionName,
    },
  });

  return paymentMethod;
}

const bankMethod = await attachBankAccount({
  customerId: recipient.customerId,
  accountName: "Victory Lucky",
  accountNumber: "0123456789",
  institutionCode: "058",
  institutionName: "GTBank",
  countryCode: "NG",
});

console.log(bankMethod.paymentMethodId); // store this too

Mobile money

For recipients receiving on MTN, M-Pesa, Airtel, or similar networks, the channel changes but the pattern is the same:

const mobileMethod = await afriex.paymentMethods.create({
  customerId: recipient.customerId,
  channel: "MOBILE_MONEY",
  accountName: "Victory Lucky",
  accountNumber: "+2348012345678", // recipient's mobile number
  countryCode: "NG",
  institution: {
    institutionCode: "MTN",
    institutionName: "MTN Mobile Money",
  },
});

Not sure which institution code to use? Call afriex.paymentMethods.listInstitutions({ countryCode: "NG", channel: "BANK_ACCOUNT" }) to get the full list for any country and channel combination.

Like the customerId, save the paymentMethodId that comes back. This is what you pass when you create the transaction.

Step 4: Send the transfer

This is the call that actually moves money. Everything before this was set up, this is the execution.

import { afriex } from "@/lib/afriex";

async function sendRemittance(params: {
  customerId: string;
  paymentMethodId: string;
  amount: number;
  sourceCurrency: string;      // currency the sender is sending
  destinationCurrency: string; // currency the recipient receives
  reference: string;           // your internal reference for this transfer
}) {
  const idempotencyKey = `idem-${params.reference}`;

  const transaction = await afriex.transactions.create({
    type: "WITHDRAW",
    customerId: params.customerId,
    destinationId: params.paymentMethodId,
    sourceAmount: `${params.amount}`,
    destinationAmount: `${params.amount}`,
    sourceCurrency: params.sourceCurrency,
    destinationCurrency: params.destinationCurrency,
    meta: {
      reference: params.reference,
      idempotencyKey,
      narration: `Remittance — ${params.reference}`,
      merchantId: params.reference,
    },
  });

  return transaction;
}

const transfer = await sendRemittance({
  customerId: recipient.customerId,
  paymentMethodId: bankMethod.paymentMethodId,
  amount: 100,
  sourceCurrency: "USD",
  destinationCurrency: "NGN",
  reference: "txn-478-001",
});

console.log(transfer.transactionId); // the Afriex transaction ID — store this
console.log(transfer.status);        // starts as PENDING

Two things worth understanding about this call.

The idempotencyKey is derived from your own reference. If this call fails due to a network error and your code retries it, the same key means Afriex will not create a duplicate transaction. It recognizes the key and returns the existing transaction instead of creating a new one.

The transaction comes back with a status of PENDING. That is not a failure — it is the expected starting state. The actual settlement happens asynchronously, and Afriex tells you what happened next through webhooks.

Step 5: Track the transfer through webhooks

You will not know the outcome of a transfer by polling the response from the create call. Afriex sends a signed HTTP POST to your webhook URL every time the transaction status changes. This is how you know when money has actually landed.

First, register your webhook URL in the Afriex dashboard under Developers > Webhooks. Copy the webhook public key from that page and add it to your environment:

AFRIEX_WEBHOOK_PUBLIC_KEY=your-webhook-public-key

Then use the built-in handler from the SDK:


// Signature verification
function verifySignature(
  signature: string,
  rawBody: string
): boolean {
  try {
     const event = afriex.webhooks.verifyAndParse(rawBody, signature);
return event
  } catch {
    return null
  }
}

// Webhook handler (Next.js route example)
export async function POST(req: Request) {
  const signature = req.headers.get("x-webhook-signature");

  if (!signature) {
    return Response.json({ error: "Missing signature" }, { status: 401 });
  }

  // Read raw body before any parsing — the signature was computed against these exact bytes
  const rawBody = await req.text();

  const payload = verifySignature(
    signature,
    rawBody
  );

  if (!payload) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }
  if (
    event.event === "TRANSACTION.UPDATED" ||
    event.event === "TRANSACTION.CREATED"
  ) {
    const { transactionId, status } = event.data;

    // Update your database with the new status
    await updateTransferStatus(transactionId, status);

    switch (status) {
      case "SUCCESS":
        // Money has landed — notify the sender
        await notifySender(transactionId, "Your transfer was delivered.");
        break;

      case "IN_REVIEW":
        // Compliance hold — not a failure, just needs time
        await notifySender(transactionId, "Your transfer is under review.");
        break;

      case "RETRY":
        // The network is retrying automatically — no action needed
        break;

      case "FAILED":
      case "REJECTED":
        // Terminal failure — let the sender know and offer a retry
        await notifySender(transactionId, "Your transfer could not be completed.");
        break;
    }
  }

  return Response.json({ received: true });
}

A few important things about how this handler is written.

It reads the raw body with req.text() before parsing anything. The SDK handles the RSA-SHA256 signature verification which was computed against those exact rawBody bytes. If you parse to JSON first and re-serialize, the verification will fail even if the payload is genuine.

It returns 200 immediately. Afriex expects a response within about five seconds. If your handler does slow work (database writes, email sending) before returning, put that work in a queue and return immediately. Afriex will retry delivery up to twelve times with exponential backoff if it does not get a success response.

IN_REVIEW and RETRY are not failures. IN_REVIEW means a compliance hold that will resolve into SUCCESS or REJECTED. RETRY means the payment network is handling it automatically. Treating either as a failure will cause you to alert users unnecessarily.

The full picture

Here is the complete flow in sequence:

1. Fetch live rate          →  afriex.rates.getRates()
2. Register recipient       →  afriex.customers.create()
3. Attach payment method    →  afriex.paymentMethods.create()
4. Send the transfer        →  afriex.transactions.create()
5. Receive status updates   →  afriex.webhooks.verifyAndParse()

Steps 2 and 3 are one-time per recipient. For a sender who sends to the same person repeatedly, you store the customerId and paymentMethodId and jump straight to step 4 on subsequent transfers.

Afriex handles the currency conversion, the corridor routing, and the settlement. Your application handles the user flow, the data storage, and the notification layer. The two concerns stay clean and separate.

The full API reference is at docs.afriex.com and the Business dashboard is at business.afriex.com. If you have questions, drop them in the comments or reach out on X @codewithveek.

How to Accept USDT and USDC Payments and Settle Automatically in USD with Afriex

Victory Lucky — Mon, 22 Jun 2026 11:16:12 +0000

Stablecoin payments are becoming a mainstream way for businesses across Africa and global markets to collect funds. USDT and USDC now account for a significant share of cryptocurrency transaction volume because they offer fast settlement, lower transaction costs, and predictable value compared to traditional cross-border payment methods.

For many businesses, however, accepting stablecoins introduces a new challenge: managing wallets, handling conversions, and moving funds into a usable currency.

The Afriex crypto wallet endpoint simplifies this process. You generate a wallet address for USDT or USDC, your customer sends funds to that address, and Afriex automatically converts the deposit into its USD equivalent in your business balance.

There is no manual conversion step, no separate swap operation, and no need to hold cryptocurrency after the payment is received.

Generate a USDT or USDC wallet address

Getting started requires a single API call and one required parameter:

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT", // or "USDC"
  customerId: "optional-customer-id",
});

If you omit customerId, the wallet belongs directly to your business account. This is useful when you want a single shared collection address for all incoming crypto payments.

If you provide a customerId, the wallet is associated with that specific customer. This approach is ideal when you need automatic payment attribution and want to know exactly which customer made a deposit without requiring payment references or manual reconciliation.

The endpoint is idempotent. Requesting a wallet for the same asset and customer multiple times returns the same wallet address each time.

{
  "data": {
    "id": "695271a3ba52c13b669fad2b",
    "addresses": [
      { "address": "0x1234567890123456789012345678901234567890", "network": "ETHEREUM_MAINNET" },
      { "address": "TYASr5UV6HEcXatwdFQfmLVUqQQQMUxHLS", "network": "TRON_MAINNET" }
    ]
  }
}

For USDT wallets, Afriex returns addresses on both Ethereum and Tron networks. You can share whichever network your customer prefers. In most cases, Tron offers lower transaction fees and is often the more economical option for senders.

How crypto deposits are converted to USD

Once USDT or USDC arrives at the generated wallet address, Afriex automatically converts the funds into their USD equivalent and records the transaction as a DEPOSIT in your account.

No additional API calls are required.

The balance that appears in your business wallet is already denominated in USD, making it easier to manage accounting, payouts, and reporting without handling cryptocurrency directly.

This workflow is especially useful for businesses that want to accept stablecoin payments while operating entirely in USD.

Detecting successful crypto payments

One important operational detail is that there is currently no dedicated webhook event for crypto-to-USD conversion deposits.

If your application relies on real-time payment notifications, you should monitor incoming deposits by polling the transactions endpoint and looking for new DEPOSIT records associated with the wallet's payment method.

const transactions = await afriex.transactions.list({
  type: "DEPOSIT",
  // filter or sort by createdAt to catch new ones
});

A common production approach is to poll periodically, track the latest processed transaction, and reconcile new deposits as they appear.

This ensures your system can reliably identify successful payments and update customer records automatically.

Production requirements and limitations

Like Afriex virtual accounts and pool accounts, crypto wallet collection is available only in the production environment.

The endpoint is not available in staging or sandbox environments.

During development, you should test your payment processing logic using mocked responses and validate the end-to-end deposit flow after going live.

If you provide a customerId, the associated customer must be verified. Requests made with an unverified customer return a 400 validation error instead of a wallet address.

Crypto wallet vs virtual account

Both crypto wallets and virtual accounts ultimately create attributable deposits in your Afriex account, but they solve different payment collection problems.

Use a virtual account when:

Customers pay via local bank transfer
Customers prefer traditional banking rails
You are collecting fiat currency payments

Use a crypto wallet when:

Customers already hold USDT or USDC
You want to accept stablecoin payments
You serve freelancers, remote workers, diaspora customers, or crypto-native businesses
Customers prefer blockchain-based payment methods

Virtual accounts are covered in the virtual accounts guide.

The Afriex crypto wallet endpoint is designed for businesses that want the speed and accessibility of stablecoin payments while keeping settlement and accounting simple through automatic USD conversion.

Frequently Asked Questions

Does Afriex support USDT on Tron?

Yes. When you create a USDT wallet, Afriex returns wallet addresses for both the Ethereum and Tron networks.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT",
});

You can provide either address to your customer depending on the network they intend to use. In many cases, Tron is preferred because transaction fees are typically lower than Ethereum.

Does Afriex support USDC payments?

Yes. The crypto wallet endpoint supports both USDT and USDC.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDC",
});

Once funds are received, Afriex automatically converts the deposit into its USD equivalent and credits your business balance.

How are crypto deposits settled?

Crypto deposits are settled automatically in USD.

When a customer sends USDT or USDC to a generated wallet address:

The blockchain confirms the transaction.
Afriex receives the stablecoin deposit.
The deposit is automatically converted into USD.
A DEPOSIT transaction is created in your account.
Your USD balance is updated.

No separate conversion request or manual swap operation is required.

Can I receive payment notifications through webhooks?

Currently, Afriex does not emit a dedicated webhook event when a crypto deposit is converted into USD.

To detect new crypto payments, periodically query the Transactions API and look for newly created DEPOSIT transactions.

const transactions = await afriex.transactions.list({
  type: "DEPOSIT",
});

Many production systems poll this endpoint at regular intervals and reconcile newly discovered deposits automatically.

Can I create separate wallets for different customers?

Yes.

Pass a customerId when creating a wallet to generate a customer-scoped payment destination.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT",
  customerId: customer.id,
});

This makes payment attribution significantly easier because deposits can be associated directly with the customer who owns the wallet.

Is the crypto wallet endpoint available in sandbox mode?

No.

The crypto wallet endpoint is currently available only in production environments. During development, use mocked responses and test payment reconciliation workflows before validating against live deposits.

Depending on how your customers prefer to pay, you may need a combination of crypto payment collection, bank transfers, and payout infrastructure.

Afriex Virtual Accounts

Use virtual accounts when customers need to pay via local bank transfer rather than cryptocurrency.

Virtual accounts provide dedicated account details that make payment collection and reconciliation easier for fiat transactions.

Recommended for:

Local bank transfers
Customer deposits
Marketplace payments
Subscription collections

Afriex Pool Accounts

Pool accounts are useful when you want to collect payments into a shared account and attribute funds programmatically after receipt.

Recommended for:

High-volume payment collection
Marketplaces
Platforms with many users
Automated reconciliation workflows

Transactions API

The Transactions API is particularly important when working with crypto deposits because it allows you to:

Detect successful deposits
Reconcile incoming payments
Build internal payment ledgers
Trigger business workflows after settlement

If you plan to accept USDT or USDC payments in production, this endpoint will likely become a core part of your integration.

Customer Verification

When creating customer-scoped wallets, ensure the associated customer has completed verification requirements.

Unverified customers will receive validation errors when attempting to create crypto wallets tied to their account.

Customer verification is therefore an important prerequisite for customer-specific payment collection workflows.

Conclusion

The Afriex crypto wallet endpoint makes it easy to accept USDT and USDC payments without managing conversions yourself. Generate a wallet address, receive stablecoin payments, and have deposits automatically settled in USD.

If you're ready to start accepting stablecoin payments, create an Afriex account, complete your business setup, and begin collecting USDT and USDC with automatic USD settlement.

I Built an Afriex MCP Prompt Cookbook So Developers Never Have to Stare at a Blank Prompt Again

0xSonOfUri — Sun, 21 Jun 2026 00:17:23 +0000

A few weeks ago, I started exploring the Afriex MCP server.

The setup was surprisingly straightforward.

Connect your MCP client.
Configure your API key.
Verify the connection.

Done.

But then I ran into a different problem.

Not a technical problem.

A prompt problem.

The Blank Prompt Problem

Once everything was connected, I found myself staring at an empty prompt box.

What should I ask?

Sure, I could retrieve balances.

I could create customers.

I could generate virtual accounts.

But what were the most useful workflows?

What were the prompts that would actually help developers build real products?

This isn't a problem unique to Afriex.

It's becoming a common challenge across the entire MCP ecosystem.

The infrastructure exists.

The tools work.

But many developers don't know where to start.

MCP Changes How We Build

Traditionally, integrating a payment API looked something like this:

Read documentation
Find the endpoint
Write HTTP requests
Parse responses
Build business logic

With MCP, the workflow looks very different.

You can simply tell your AI assistant what you want to build.

For example:

Create a customer onboarding flow that:

- Collects customer details
- Generates a virtual account
- Displays payment instructions

Build it using Next.js and TypeScript.

Instead of manually stitching everything together, the AI can interact with infrastructure through the MCP server.

That's incredibly powerful.

But only if you know what to ask.

The Idea

That's what led me to build the:

Afriex MCP Prompt Cookbook

A collection of practical, production-oriented prompts designed specifically for developers building with Afriex MCP.

The goal is simple:

Copy.

Paste.

Build.

Instead of starting from scratch every time.

The cookbook is open source and available on GitHub:

https://github.com/SonOfUri/afriex-mcp-cookbook

Feel free to explore the prompts, use them in your own projects, and contribute new recipes.

What's Inside

The cookbook is organized around real-world use cases.

Not API endpoints.

Not documentation pages.

Actual products and workflows.

Getting Started

For developers who have just connected their MCP client.

Examples include:

Retrieving balances
Creating customers
Monitoring transactions

Virtual Accounts

Examples include:

Customer onboarding flows
Collections systems
Payment request workflows

Payments

Examples include:

Payment links
Payout systems
Payment status tracking

Stablecoins

Examples include:

USDC deposit flows
Treasury monitoring
Settlement operations

AI Agents

Examples include:

Operations agents
Treasury agents
Monitoring agents

OpenClaw Integrations

Examples focused on combining AI agents with payment infrastructure.

My Favorite Prompt

One of my favorite recipes asks Cursor to build an entire virtual account collection flow.

Using Afriex MCP:

Create a customer onboarding flow that:

- Collects customer details
- Creates a customer record
- Generates a virtual account
- Displays payment instructions

Build this as a modern Next.js application using TypeScript and TailwindCSS.

Show me the complete implementation.

This is the kind of workflow that would traditionally require:

reading documentation
understanding endpoints
designing data models
wiring API calls

Now it can start with a single prompt.

Why I Think Prompt Libraries Matter

We're entering a new phase of software development.

Documentation remains important.

SDKs remain important.

APIs remain important.

But prompts are becoming a new layer of developer experience.

The best developer platforms won't just provide endpoints.

They'll provide examples, recipes, workflows, and patterns that help developers move from idea to implementation faster.

That's exactly what this cookbook is trying to do.

What Comes Next

The current version focuses on:

payments
virtual accounts
stablecoins
AI agents
OpenClaw integrations

Future additions will include:

more production workflows
community-contributed recipes
example applications
advanced MCP patterns

Final Thoughts

One of the most surprising lessons I've learned while working with MCP is that access to tools isn't enough.

Developers also need examples of what's possible.

That's what the Afriex MCP Prompt Cookbook aims to provide.

Not more documentation.

Not another SDK.

A collection of practical prompts that help developers build faster.

Because sometimes the hardest part isn't connecting the infrastructure.

It's knowing what to ask next.

Explore The Cookbook

GitHub:

https://github.com/SonOfUri/afriex-mcp-cookbook

If you're building with Afriex MCP, I'd love to see what you create and what prompts you find most useful.

Contributions, suggestions, and new recipes are always welcome.