DEV Community: Afriex

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.

Afriex Virtual Accounts: A Developer's Guide to Dedicated and Pool Accounts

Victory Lucky — Sat, 20 Jun 2026 09:56:25 +0000

Reconciling inbound payments seems straightforward until you have more than a handful of customers. Someone sends money to your business account, and now you need to determine who sent it, why they sent it, and what the payment was for. In most cases, this means asking customers to include a reference, which they will eventually forget.

Virtual accounts solve this problem by reversing the model. Instead of having everyone pay into a single account, you generate a unique account number for a customer, a purpose, or even a single transaction. When funds arrive, you already know exactly who the payment belongs to. There is no reference matching, no guesswork, and no manual reconciliation.

This guide explains how virtual accounts work in the Afriex Business API, including the two available account types, when to use each one, the key constraints you should understand before building, and the complete integration pattern.

Two ways to collect: Dedicated accounts vs. pool accounts

Afriex provides two distinct models for collecting inbound payments, and choosing the right one can significantly simplify your integration.

Dedicated virtual accounts (VIRTUAL_BANK_ACCOUNT) are created specifically for an individual customer. You generate them through the API, and Afriex assigns a real account number linked directly to that customer in your system. Every deposit into that account is automatically attributed to the correct customer.

Pool accounts (POOL_ACCOUNT) take a different approach. Afriex maintains a shared account that multiple customers can pay into. Deposits are reconciled using a reference value that you store and track on your side. There is no account creation step. You simply call the endpoint, receive the account details and reference, and provide them to your customer.

A simple rule of thumb:

Use a dedicated virtual account when you want a stable account number permanently assigned to a customer.
Use a pool account when you need a lightweight collection flow and are comfortable managing payment references yourself.

Important limitation: Production only

Before implementing virtual accounts, be aware of one critical limitation: virtual accounts and pool accounts are only available in production environments.

They are not supported in staging or sandbox environments. As a result, you cannot fully test the end-to-end collection flow before going live. The recommended approach is to build and unit test your integration against mocked responses, then carefully validate the complete payment flow after deployment to production.

Dedicated virtual accounts

Static vs. dynamic accounts

Dedicated virtual accounts come in two variants. The API determines which type to create based on the parameters you provide alongside currency and customerId.

Static accounts are created with a label and never expire. The account number remains valid indefinitely, making them ideal for customers who need to fund an account repeatedly over time.

Supported labels include:

SALES, OPERATIONS, PAYROLL, COLLECTIONS, VENDOR_PAYMENTS, TAX, REFUNDS, MARKETING, TREASURY, and GENERAL.

The label is purely organizational. It allows you to categorize accounts internally according to their intended use.

Dynamic accounts are created using an amount instead of a label. They expire after a short period and are designed for collecting a specific amount within a limited timeframe, such as a one-time invoice or order payment.

The label and amount fields are mutually exclusive. Including both in the same request will result in an error.

// Static virtual account, grouped under SALES
const staticAccount = await afriex.paymentMethods.createVirtualAccount({
  currency: "NGN",
  customerId: "68e6717848e1f632e9686460",
  label: "SALES",
});

// Dynamic virtual account, tied to a specific amount
const dynamicAccount = await afriex.paymentMethods.createVirtualAccount({
  currency: "NGN",
  customerId: "68e6717848e1f632e9686460",
  amount: 50000,
});

The response includes the account details you can share directly with the customer:

{
  "data": {
    "paymentMethodId": "690cc5bbe2a1143ff6070119",
    "channel": "VIRTUAL_BANK_ACCOUNT",
    "customerId": "68e6717848e1f632e9686460",
    "institution": { "institutionName": "FIDELITY BANK" },
    "accountName": "Lily New",
    "accountNumber": "3820404958",
    "countryCode": "NG"
  }
}

NGN virtual accounts and BVN requirements

When creating a static NGN virtual account, the customer must have a Bank Verification Number (BVN) on file. This is a regulatory requirement for permanently assigned Nigerian bank accounts.

If the customer does not have a BVN recorded, account creation will fail.

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

This requirement applies only to static NGN virtual accounts. Dynamic virtual accounts are exempt, and the requirement does not apply to other currencies.

If your product relies on static NGN accounts, collecting BVNs during onboarding will prevent failed account creation requests later in the user journey.

Per-customer account limits

Virtual account creation is subject to limits based on the combination of business, customer, and currency.

If you exceed the allowed number of accounts for a specific customer and currency, the API returns a 400 response with the error code VIRTUAL_ACCOUNT_LIMIT_REACHED.

To avoid unnecessary creation attempts, consider checking for existing accounts before creating a new one:

const existing = await afriex.paymentMethods.listVirtualAccounts({
  currency: "NGN",
  customerId: "68e6717848e1f632e9686460",
});

if (existing.data.length === 0) {
  // safe to create
  await afriex.paymentMethods.createVirtualAccount({
    currency: "NGN",
    customerId: "68e6717848e1f632e9686460",
    label: "SALES",
  });
}

A breaking change to be aware of

Previous versions of the API automatically created a virtual account when the list endpoint was called and no account existed.

That behavior has been removed.

The list endpoint is now strictly read-only. If no accounts exist, it returns a 200 response with an empty array and does not create anything.

Account creation must now be performed explicitly through the POST endpoint.

If your integration previously relied on a "get-or-create" workflow, update it to follow a clear check-then-create pattern like the example above.

Pool accounts

Pool accounts operate differently because customers are not assigned dedicated account numbers.

Instead, you call the endpoint with a country code, and Afriex returns an existing pool account along with a unique reference value.

const poolAccount = await afriex.paymentMethods.getPoolAccount({
  country: "NG",
  customerId: "6929843e2c4653277440acc0",
});

{
  "data": {
    "paymentMethodId": "69c2804b30314b491e48b305",
    "channel": "VIRTUAL_BANK_ACCOUNT",
    "customerId": "6929843e2c4653277440acc0",
    "reference": "6929843e2c4653277440acc0",
    "institution": { "institutionName": "UBA" },
    "accountName": "TEST",
    "accountNumber": "12345678",
    "countryCode": "NG"
  }
}

There are several important differences compared to dedicated virtual accounts:

There is no currency parameter. Currency is inferred from the country code.
NG automatically resolves to NGN.
Pool accounts are only available in countries where Afriex has configured them.
Requests for unsupported countries will return an error.

The most important field in the response is reference.

When a customerId is provided, the returned reference matches that customer. Store this value in your database before sharing account details with the customer.

When a deposit arrives, Afriex uses the reference to identify the payment, allowing your system to correctly attribute funds to the appropriate customer.

Feature	Dedicated Virtual Account	Pool Account
Account number	Unique per customer	Shared across multiple customers
Creation required	Yes	No
Best for	Recurring or long-term customer payments	Quick collections and one-off payments
Customer identification	Automatic via account number	Via stored reference value
Supports repeated top-ups	Yes (static accounts)	Yes, but requires reference tracking
Expires	Static: No, Dynamic: Yes	No
BVN required for NGN	Yes (static NGN accounts only)	No
Per-customer account limits	Yes	No customer-level creation limits
Reconciliation complexity	Low	Medium
Ideal use cases	Wallets, subscriptions, marketplaces, recurring billing	Checkout payments, invoices, temporary collections

Supported currencies

Virtual accounts are currently available across four primary currencies: USD, NGN, GBP, and EUR.

Current country coverage is shown below:

Country	Currency	Virtual Account Status
Nigeria	NGN	Live
Kenya	KES	Live
United States	USD	Live
Ghana	GHS	Coming soon
United Kingdom, all EU countries	GBP / EUR	Coming soon

If virtual accounts are not yet available in your target market, plan for an alternative collection strategy. Depending on availability, that may mean using pool accounts or another payment method until dedicated virtual accounts become available.

Reconciliation pattern

The typical lifecycle of a virtual account payment looks like this:

Create the customer in your system and register them with Afriex if necessary.
Create a static or dynamic virtual account for that customer.
Store the paymentMethodId and accountNumber in your database.
Display the account details to the customer through your checkout flow, invoice, or payment instructions.
The customer transfers funds to the virtual account.
Afriex sends a deposit-related webhook event when funds arrive.
Your webhook handler matches the event to the stored paymentMethodId and updates the corresponding records.

This follows the same reconciliation philosophy described in the webhook integration guide. Webhooks should serve as the source of truth for payment events rather than relying on assumptions made by the application.

For pool accounts, the process is similar, but the reference becomes the primary identifier. Since multiple customers share the same account number, your webhook handler must use the stored reference to determine which customer a deposit belongs to.

Without persisting that reference beforehand, accurate reconciliation becomes impossible.

When should you use each option?

Use a dedicated virtual account when:

You have a known customer who will make recurring payments.
You want deposits to be automatically attributed to that customer.
You want to eliminate reference-based reconciliation entirely.
You are building subscription products, marketplace wallets, stored balances, or recurring billing systems.

Use the dynamic variant when collecting a specific amount within a limited time window, such as a single invoice or one-off purchase.

Use a pool account when:

You need to start collecting payments quickly.
You do not want to manage virtual account creation.
You want to avoid customer-level account limits and BVN requirements.
You are comfortable maintaining reference mappings in your own system.

A checkout experience that generates a unique reference for each order while reusing the same account details for all customers is a common use case.

Use an alternative payment method when:

The country or currency you need is not yet supported.
Virtual account coverage is still marked as "coming soon."
Your target corridor requires a collection method that Afriex does not currently support.

Always verify availability before implementation using the supported currencies reference.

If you'd like to see a practical implementation, the Afriex payment links guide demonstrates how to build shareable payment links backed by dynamic virtual accounts. For complete endpoint documentation and request schemas, refer to the Afriex API reference for virtual accounts and pool accounts.

What Afriex's Visa Direct Partnership Means for Users and Developers

Victory Lucky — Wed, 17 Jun 2026 08:42:51 +0000

On November 1, 2025, Afriex announced a partnership with Visa to enable real-time cross-border payments across more than 160 markets. Through an integration with Visa Direct, Afriex users can now send international money transfers through Visa's global payment network, potentially reducing delivery times from days to near real time.

The integration, which is available immediately through the Afriex mobile app, represents one of the company's most significant upgrades to its cross-border payments infrastructure.

But what does the Afriex Visa Direct partnership actually mean for users, businesses, and developers? More importantly, what has changed, and what remains unclear?

What Is Visa Direct?

Visa Direct is Visa's real-time money movement platform that enables funds to be pushed directly to eligible bank accounts, cards, and wallets connected to the Visa network.

Unlike traditional correspondent banking systems, where international money transfers can pass through multiple intermediary banks before settlement, Visa Direct uses Visa's existing payment network and partner banking infrastructure to move funds more efficiently.

For account and wallet payouts, Visa Direct leverages Visa's network alongside local ACH and real-time payment systems to deliver money into the recipient's domestic banking ecosystem. The result is faster settlement, improved transfer visibility, and a more streamlined payment experience.

Visa Direct itself is not new. The service has been used by payment companies around the world for years. What is new is Afriex's integration with Visa Direct and its decision to incorporate the service into its growing remittance and cross-border payments platform.

How Afriex's Visa Direct Integration Changes International Transfers

Before the Visa Direct integration, most Afriex transfers relied on traditional banking rails that could take anywhere from one to several business days to settle, depending on the payment corridor and recipient bank.

According to Afriex CEO Tope Alabi, speed and transparency remain critical for families and businesses that depend on remittance payments. By connecting to Visa Direct, Afriex can now route eligible transfers through a payment network designed for near real-time money movement.

For users, the experience is straightforward. Funds can be sent through the Afriex mobile app and delivered to supported Visa-connected destinations much faster than traditional settlement methods allow.

The scale of the opportunity is substantial. Visa Direct reaches more than 160 markets and connects to billions of accounts worldwide. However, that number reflects the size of Visa's global payment infrastructure rather than 160 new markets independently added by Afriex.

In practical terms, the Afriex Visa Direct integration gives users access to a much larger network of potential payout destinations without requiring Afriex to build entirely new payment rails for every market.

The Important Caveat

The headline numbers do not mean every transfer automatically qualifies for Visa Direct.

Availability depends on whether the recipient's financial institution participates in the relevant Visa Direct program and whether the destination account is eligible to receive Visa Direct payouts.

If the recipient bank does not support the service, Afriex will continue using its existing payout methods, including bank account transfers, mobile money, SWIFT transfers, and other supported payment channels.

There is another limitation worth noting. According to the partnership announcement, Afriex currently accesses Visa Direct through its financial institution partner, but Push-to-Wallet functionality is not yet commercially available. The live service today primarily supports push-to-account and push-to-card transfers rather than the full suite of Visa Direct products.

This distinction matters because the integration should be viewed as an additional fast payment rail, not a complete replacement for Afriex's existing payment infrastructure.

Why Afriex Is Expanding Its Cross-Border Payment Infrastructure

The Visa Direct partnership fits neatly into Afriex's broader strategy of expanding global payment access while improving the efficiency of its cross-border payments network.

In recent years, Afriex has expanded its reach across Europe, enabling senders in countries such as the Netherlands, Romania, Germany, Ireland, Italy, France, Belgium, and Spain to send money to African markets. The company has also invested in corridor infrastructure connecting African markets with countries including China, India, and Pakistan.

The strategy is clear.

Rather than building new payment infrastructure for every international corridor, Afriex can leverage established global networks such as Visa Direct where they provide meaningful advantages. At the same time, the company can continue investing in proprietary infrastructure where existing financial systems remain slow, expensive, or underserved.

The move also aligns with broader industry trends. As global remittance flows continue to grow, users increasingly expect faster transfers, better visibility into payment status, and more reliable settlement times.

For Afriex, integrating Visa Direct is a logical step toward meeting those expectations while strengthening its position in the international money transfer market.

What the Afriex Visa Direct Partnership Means for Developers

For developers, the picture is less exciting, at least for now.

As of this writing, there is no public indication that Visa Direct functionality is available through the Afriex Business API or SDK. Public announcements surrounding the Afriex Visa Direct partnership focus exclusively on the consumer experience within the Afriex mobile app.

Developers using the Afriex Business API should continue working with the payment methods currently documented by Afriex, including bank accounts, mobile money, SWIFT transfers, and other supported disbursement channels.

If Visa Direct capabilities are eventually exposed through the API, they would likely appear as an additional payment method alongside existing options such as BANK_ACCOUNT, MOBILE_MONEY, and SWIFT. That expectation is based on Afriex's current API structure, but it remains speculation rather than documented functionality.

Until official documentation confirms otherwise, developers should avoid designing workflows that depend on Visa Direct access through the Afriex Business API.

The Bottom Line

The Afriex Visa Direct partnership represents a meaningful upgrade to the company's cross-border payments infrastructure. By connecting to Visa's global payment network, Afriex can offer faster international money transfers and improved payout speed across a large number of supported markets.

For users, the benefits are immediate. Eligible transfers can move through Visa Direct's infrastructure and arrive significantly faster than they would through traditional banking channels.

For developers, however, the story remains largely unchanged. Based on publicly available information, Visa Direct is currently a consumer-facing enhancement rather than a new API capability.

The partnership is significant, but its biggest impact today is on transfer speed and user experience. Whether it eventually becomes part of the Afriex developer ecosystem remains a question for future product announcements.

Building Global Payment Products Without Owning Banking Infrastructure

0xSonOfUri — Fri, 12 Jun 2026 23:46:55 +0000

A decade ago, building a financial product required enormous resources.

If you wanted to launch a payments company, you needed:

banking relationships
settlement infrastructure
compliance operations
payment processing agreements
treasury management systems

For most startups, that was simply out of reach.

Today, things look very different.

A small team can build products that move money globally without owning a bank, operating payment rails, or maintaining treasury infrastructure.

The secret isn't magic.

It's infrastructure.

The Old Fintech Playbook

Historically, launching a financial product meant becoming part of the financial system itself.

That often involved:

obtaining licenses
negotiating banking partnerships
integrating with payment processors
maintaining settlement accounts
building compliance operations

The barriers were high.

And for good reason.

Moving money is complicated.

The New Fintech Stack

Modern fintech companies increasingly build on top of specialized infrastructure providers.

Instead of building everything themselves, they compose financial primitives.

Think of it like cloud computing.

Most startups don't build their own data centers.

They build on AWS, Google Cloud, or Azure.

Financial infrastructure is moving in a similar direction.

Developers now have access to building blocks such as:

virtual accounts
wallet infrastructure
payouts
foreign exchange
stablecoin settlement
transaction monitoring

through APIs.

The Shift from Banks to Building Blocks

Consider a simple requirement:

Receive money from customers.

Years ago, that might require:

direct banking integrations
account provisioning systems
settlement infrastructure

Today, an API can provision receiving accounts for you.

The same pattern appears across the financial stack.

Need to:

receive funds?
send payouts?
manage wallets?
support multiple currencies?

There are infrastructure layers designed to handle those complexities.

What Developers Actually Build

The interesting thing is that most fintech startups are not building payment rails.

They're building products.

The rails already exist.

The real value often comes from:

user experience
automation
workflows
business logic
distribution

Not from rebuilding banking infrastructure.

For example:

A freelancer platform doesn't need to become a bank.

It needs:

customer onboarding
collections
payouts
reporting

Infrastructure providers handle the rest.

The Role of Stablecoins

Stablecoins are accelerating this trend.

Many cross-border payment platforms now use stablecoins internally for:

treasury management
liquidity movement
settlement

while customers continue interacting with familiar payment experiences.

The customer sees:

Send Money

The infrastructure may involve:

Collection
↓
Settlement
↓
Stablecoin Treasury
↓
Liquidity Partner
↓
Payout

The complexity is hidden behind APIs and infrastructure layers.

What This Means for Builders

The question is no longer:

How do I become a bank?

The question is:

What can I build on top of financial infrastructure?

That opens the door to entirely new products.

Developers can focus on:

marketplaces
payroll systems
creator platforms
remittance products
B2B payment workflows
treasury automation

without spending years building foundational infrastructure.

Infrastructure Is Becoming the Advantage

The most successful fintech companies of the next decade may not be the ones that own the rails.

They may be the ones that use the rails most effectively.

Just as cloud providers abstracted away servers, modern financial infrastructure is abstracting away much of the complexity involved in moving money.

That allows builders to focus on solving customer problems rather than rebuilding the financial system from scratch.

Final Thoughts

Building a global payment product used to require becoming part of the banking system.

Today, developers can access many of the same capabilities through infrastructure providers and APIs.

The opportunity has shifted.

Less time spent building rails.

More time spent building products.

And that might be one of the most important changes happening in fintech today.

Accept Payments in Minutes with Afriex Checkout Sessions

Victory Lucky — Sat, 30 May 2026 16:48:17 +0000

Most payment integrations follow the same painful path: you build a checkout UI, set up bank account display logic, handle Mobile Money prompts, manage session timers, poll for confirmation, and somehow do all of this correctly across every edge case. It takes days, sometimes weeks — and that's before you think about testing.

Afriex Checkout Sessions changes that. With a single API call, you get a fully hosted payment page that handles everything: payment method selection, bank transfer details, Mobile Money authorization, session expiration, and redirect on completion. You stay focused on your product; Afriex handles the payment flow.

This guide walks you through a complete integration from scratch — using either the official TypeScript SDK or the REST API directly.

How It Works

The flow is four steps:

Your server creates a checkout session via the SDK or REST API
Afriex returns a checkoutUrl
You redirect the customer to that URL
After payment, Afriex redirects the customer back to your app and fires a webhook to your server

That's the entire integration surface. No payment UI to build. No polling loop. No bank account display to manage.

Prerequisites

Before you start, you'll need:

An Afriex Business account with API access
Your API key from the Afriex dashboard (Developer tab)
Node.js 20+ if you're using the SDK, or any server-side runtime for the REST API
An HTTPS redirect URL where customers will land after payment

Sandbox first. Checkout Sessions is currently available for end-to-end testing in Afriex's sandbox environment. Production rollout is happening soon — use sandbox to validate your integration now so you're ready to flip the switch.

Setup

Using the SDK (Node.js / TypeScript)

Install the official Afriex SDK:

npm install @afriex/sdk
# or
pnpm add @afriex/sdk
# or
yarn add @afriex/sdk

Then initialize it once — typically in a shared module or service file:

import { AfriexSDK } from "@afriex/sdk";

export const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY,
  environment: "staging", // or "production"
});

The SDK maps staging to https://sandbox.api.afriex.com and production to https://api.afriex.com — no need to manage base URLs yourself.

Enable retries for production resilience:

export const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY,
  environment: "production",
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000, // milliseconds
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
});

Using the REST API directly

Set your base URL depending on your environment:

Sandbox:    https://sandbox.api.afriex.com
Production: https://api.afriex.com

Pass your API key on every request via the x-api-key header.

Step 1: Create a Checkout Session

SDK (Node.js / TypeScript)

import { afriex } from "./afriex-client"; // your initialized SDK instance

async function createCheckoutSession(order: Order) {
  const session = await afriex.checkout.createSession({
    amount: order.amountInKobo,          // e.g. 500000 for ₦5,000
    currency: "NGN",
    merchantReference: order.id,          // must be unique per session
    redirectUrl: "https://yourapp.com/checkout/return",
    channels: ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY"],
    customer: {
      name: order.customer.name,
      email: order.customer.email,
      phone: order.customer.phone,        // E.164 format: +2348100000000
      countryCode: "NG",
    },
    metadata: {
      orderId: order.id,
      plan: order.plan,
    },
  });

  return session.checkoutUrl;
}

The SDK returns { checkoutUrl: string } — redirect your customer there immediately.

REST API

cURL

curl -X POST https://sandbox.api.afriex.com/api/v1/checkout-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "amount": 500000,
    "currency": "NGN",
    "merchantReference": "order-2026-05-30-001",
    "redirectUrl": "https://yourapp.com/checkout/return",
    "channels": ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY"],
    "customer": {
      "name": "Amarachi Okafor",
      "email": "amara@example.com",
      "phone": "+2348100000000",
      "countryCode": "NG"
    },
    "metadata": {
      "orderId": "ORD-9912",
      "plan": "pro"
    }
  }'

Node.js (fetch)

async function createCheckoutSession(order) {
  const response = await fetch(
    "https://sandbox.api.afriex.com/api/v1/checkout-session",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.AFRIEX_API_KEY,
      },
      body: JSON.stringify({
        amount: order.amountInKobo,
        currency: "NGN",
        merchantReference: order.id,
        redirectUrl: "https://yourapp.com/checkout/return",
        channels: ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY"],
        customer: {
          name: order.customer.name,
          email: order.customer.email,
          phone: order.customer.phone,
          countryCode: "NG",
        },
        metadata: {
          orderId: order.id,
        },
      }),
    }
  );

  const { data } = await response.json();
  return data.checkoutUrl;
}

Python (requests)

import requests
import os

def create_checkout_session(order):
    response = requests.post(
        "https://sandbox.api.afriex.com/api/v1/checkout-session",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["AFRIEX_API_KEY"],
        },
        json={
            "amount": order["amount_in_kobo"],
            "currency": "NGN",
            "merchantReference": order["id"],
            "redirectUrl": "https://yourapp.com/checkout/return",
            "channels": ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY"],
            "customer": {
                "name": order["customer"]["name"],
                "email": order["customer"]["email"],
                "phone": order["customer"]["phone"],
                "countryCode": "NG",
            },
        },
    )
    return response.json()["data"]["checkoutUrl"]

Response

{
  "data": {
    "checkoutUrl": "https://sandbox.pay.afriex.com/pay/eyJhbGciOiJI..."
  }
}

Redirect your customer to checkoutUrl immediately. The session has an expiration timer, so don't hold on to the URL for later.

Request Reference

Required Fields

Field	Type	Description
`amount`	integer	Amount in minor currency units (kobo for NGN, cents for USD). Minimum: `100`.
`currency`	string	ISO 4217 currency code, uppercase (e.g. `NGN`, `GHS`). Must be enabled for checkout on your account.
`merchantReference`	string	Your unique identifier for this session. Used to match webhooks and reconcile transactions.
`redirectUrl`	string	HTTPS URL the customer is sent to after the checkout flow completes.
`customer`	object	Customer details. See below.

Customer Object

Field	Type	Description
`name`	string	Customer's full name.
`email`	string	Customer's email address.
`phone`	string	Phone number in E.164 format (e.g. `+2348100000000`).
`countryCode`	string	ISO 3166-1 alpha-2 country code (e.g. `NG`, `GH`). Case-insensitive.

Optional Fields

Field	Type	Default	Description
`channels`	array	`["VIRTUAL_BANK_ACCOUNT"]`	Payment methods to offer. Options: `VIRTUAL_BANK_ACCOUNT`, `MOBILE_MONEY`.
`metadata`	object	—	Flat key/value pairs (strings only) you want attached to the session for your own reference.

Step 2: The Customer Completes Payment

Once redirected, the customer lands on the Afriex-hosted checkout page. Depending on the channels you enabled, they can:

Pay by Bank Transfer

The customer sees a one-time virtual bank account — account name, number, and bank — with the exact amount to transfer. They open their banking app, send the transfer, and return to the checkout page. Afriex detects the inbound transfer and confirms payment automatically.

⚠️ Exact amount required. The customer must transfer the precise amount shown. Sending a different amount will cause delays and may require a manual reconciliation or refund.

Pay by Mobile Money

The customer selects their network (e.g. MTN, Airtel), enters their account name and phone number, and taps Pay now. Afriex pushes an authorization prompt to their phone. Once they approve it, the checkout page updates automatically.

Both paths end in one of two outcomes: a success screen (auto-redirects to your redirectUrl) or a failure screen (with guidance to retry or contact support).

Step 3: Handle the Redirect

When the customer lands back on your redirectUrl, show them an appropriate confirmation or error screen. Use the merchantReference you generated to look up the order state in your system.

A typical return handler:

// Express.js example
app.get("/checkout/return", async (req, res) => {
  // The merchantReference you passed when creating the session
  const reference = req.query.reference;

  // Look up your order by reference — don't trust query params for payment status
  const order = await db.orders.findByReference(reference);

  if (order.status === "paid") {
    return res.redirect(`/orders/${order.id}/confirmation`);
  }

  // Not yet confirmed — webhook may still be in flight
  return res.redirect(`/orders/${order.id}/pending`);
});

Don't use the redirect to confirm payment. The redirect tells you the customer finished the checkout flow, not that payment succeeded. Always use the webhook (see Step 4) as the authoritative signal.

Step 4: Listen for the Webhook

When Afriex confirms payment, it fires a CHECKOUT_SESSION.CREATED webhook to the callback URL configured in your Afriex dashboard. This is the source of truth for marking an order as paid.

// Express.js webhook handler example
app.post("/webhooks/afriex", express.raw({ type: "application/json" }), async (req, res) => {
  const event = JSON.parse(req.body);

  if (event.type === "CHECKOUT_SESSION.CREATED") {
    const { merchantReference, amount, currency } = event.data;

    // Mark order as paid using your merchantReference
    await db.orders.markPaid({
      reference: merchantReference,
      amount,
      currency,
    });
  }

  res.status(200).send("OK");
});

Make your webhook handler idempotent — Afriex may retry delivery if your endpoint doesn't respond with a 200. Using merchantReference as your idempotency key is the right approach.

Beyond the Basic Flow: Advanced Use Cases

The checkout session API supports a few patterns beyond the standard redirect flow that are worth knowing about.

Delayed Payment Collection

You don't have to redirect customers immediately after creating a session. You can create the session on your server, store the checkoutUrl, and send it to the customer later — via email, SMS, or a payment link in an invoice. This is useful for billing flows where payment isn't expected at the point of order.

// Create the session when the invoice is generated
const session = await afriex.checkout.createSession({ ...invoiceDetails });

// Store checkoutUrl against the invoice
await db.invoices.update(invoice.id, { paymentUrl: session.checkoutUrl });

// Send it later when the invoice is dispatched
await mailer.send({
  to: invoice.customer.email,
  subject: "Your invoice is ready",
  body: `Pay here: ${invoice.paymentUrl}`,
});

Keep session expiration in mind — if the payment link will be sent days later, build in a check for whether the session is still valid before sending.

Embedded Checkout (Iframe / Webview)

Rather than fully leaving your app, you can open the checkoutUrl inside an iframe (web) or a webview (mobile). This keeps the customer inside your product's shell while Afriex handles the payment UI.

<!-- Web: iframe embed -->
<iframe
  src="https://sandbox.pay.afriex.com/pay/YOUR_SESSION_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
  allow="payment"
></iframe>

// React Native: WebView embed
import { WebView } from "react-native-webview";

<WebView
  source={{ uri: session.checkoutUrl }}
  onNavigationStateChange={(state) => {
    // Detect redirect back to your redirectUrl
    if (state.url.startsWith("https://yourapp.com/checkout/return")) {
      navigation.navigate("OrderConfirmation");
    }
  }}
/>

The webhook still fires regardless of how the customer accesses the checkout — embedded or full redirect.

Important Notes

Amounts are always in minor units

Afriex uses the smallest denomination of each currency — no decimals in the amount field:

Currency	Major unit	Minor unit	Example
NGN	₦1	1 kobo	₦5,000 → `500000`
GHS	₵1	1 pesewa	₵100 → `10000`
USD	$1	1 cent	$10 → `1000`

The minimum amount is 100 (equivalent to 1 major unit).

`merchantReference` must be unique

Each session needs a distinct merchantReference. Re-using a reference from a previous session will result in an error. Use your internal order ID, a UUID, or any other identifier you control.

Sessions expire

Each checkout session has an expiration timer visible to the customer. If the session expires before payment completes, the customer will need a new session. Build a recovery path — for example, let customers re-initiate checkout from your order page.

Phone numbers must be E.164

The customer's phone must be in E.164 format: + followed by the country code and subscriber number, no spaces or punctuation. For example, a Nigerian number would be +2348100000000, not 08100000000.

Testing in Sandbox

All of the above works end-to-end in sandbox today:

Use base URL https://sandbox.api.afriex.com (or set environment: "staging" in the SDK)
Use your sandbox API key from the Afriex dashboard
Successful checkout sessions redirect to https://sandbox.pay.afriex.com/pay/{token}
Webhooks fire to your configured callback URL in sandbox as well

Test the full round-trip — create a session, go through the hosted checkout, and verify your webhook handler receives and processes the event — before switching to production credentials.

Error Responses

Status	Meaning
`400`	Invalid request — check required fields, amount minimum, and currency format
`401`	Unauthorized — verify your `x-api-key` header
`500`	Server error — retry with exponential backoff

What's Next

Afriex SDK Documentation — Full SDK reference covering installation, configuration, and all available modules
SDK Checkout Reference — SDK-specific parameters and examples for the Checkout API
User Flow Guide — See the full customer-facing checkout experience, screen by screen
Webhooks — Configure your callback URL and understand the full webhook payload
REST API Reference — Full OpenAPI spec for the Create Checkout Session endpoint

Afriex Checkout Sessions is currently available in sandbox. Production rollout is expected in the coming weeks — get your integration ready today.

DEV Community: Afriex

How to Collect Mobile Money Payments for Your SaaS Through Afriex

Setup

Step 1 — List the providers

Step 2 — Verify the number

Step 3 — Save the payment method

Step 4 — Charge it

Collect in local currency, convert on your own schedule

If you do convert at charge time

The OTP step

Step 5 — Track the payment

Testing it

Gotchas

That's it

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

The Old Fintech Stack

Financial Infrastructure Was Historically a Moat

Then APIs Changed Software

Financial Infrastructure Is Becoming Programmable

The New Fintech Stack

Build vs. Compose

The Financial Primitives

Where Afriex Fits

From Infrastructure to Product

The Rise of Stablecoins

Stablecoins Don't Replace Everything

The Customer Experience Becomes the Abstraction

This Is Similar to Cloud Computing

The Developer Becomes a Financial Product Builder

A Marketplace Example

A Global Payroll Example

A Remittance Example

Global Businesses Need Global Infrastructure

Infrastructure Can Accelerate Distribution

The New Competitive Advantage

The Stack Becomes More Modular

But Abstraction Doesn't Mean Simplicity

The Responsibility Moves Up the Stack

APIs Are Becoming Financial Building Blocks

AI Adds Another Layer

The Financial Stack Is Becoming More Composable

What This Means for Startups

What This Means for Developers

What This Means for Financial Infrastructure Providers

The Future May Be Invisible

Where Afriex Fits Into This Future

The Biggest Shift Isn't Technology

From Owning Infrastructure to Composing Infrastructure

The New Fintech Stack

The Opportunity for Builders

Final Thoughts

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

What you'll have at the end

Before you start

Let's look at the whole flow first

Let's create the checkout session

One webhook, two writes

Sale → earning → balance

Onboarding Amara for payout

Requesting and disbursing a withdrawal

The worker, and the one distinction that protects the money

Closing the loop

Where we are

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

What you'll have at the end

Before you start

Let's start from what the app has to do

The four tables

Decision 1: buyers and sellers live in separate tables

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

Decision 3: currency is an enum, not a varchar

Decision 4: how to search an encrypted email column

The products table

How a request travels through the app

The router: the access model in one screen

The controller, and a leak it prevents

The service: this is where the business rules live

The repository: the only file that interacts with Drizzle

The orders table, where the storefront stops

The order row exists before any money moves

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

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