DEV Community: Afriex

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.

What Happens After You Click “Send Money”? Lessons from the Afriex Utila Partnership

0xSonOfUri — Fri, 29 May 2026 15:42:42 +0000

Most people think cross-border payments are simple.

You open an app.

Enter an amount.

Choose a recipient.

Click send.

A few moments later, the money arrives.

Simple.

At least on the surface.

What most people never see is the infrastructure required to make that experience possible at scale.

Recently, Utila published a case study about its partnership with Afriex, a company operating cross-border payment corridors across Africa. While the announcement focused on infrastructure, it revealed something much more interesting:

The real challenge in cross-border payments isn't sending money. It's managing liquidity, treasury operations, and settlement across multiple markets simultaneously.

And that's where stablecoins are quietly becoming critical infrastructure.

The Hidden Side of Cross-Border Payments

When users think about a transfer, they typically imagine something like this:

Sender
   ↓
Payment
   ↓
Recipient

Reality looks closer to:

Sender
   ↓
Collection Rail
   ↓
Treasury Layer
   ↓
Liquidity Partner
   ↓
FX Conversion
   ↓
Settlement Layer
   ↓
Local Payout Partner
   ↓
Recipient

Every additional country introduces more complexity:

different currencies
different banking systems
different payout partners
different liquidity requirements

Now imagine operating this across more than 20 African corridors.

The challenge quickly becomes operational.

Afriex's Challenge

According to Utila's case study, Afriex needed the ability to support multiple stablecoins across multiple blockchain networks while settling with payout partners throughout Africa.

The problem wasn't simply storing assets.

It was managing:

USDC
USDT
multiple blockchain networks
treasury movements
partner settlements
growing B2B customer operations

all from a unified operational layer.

Without consolidation, these workflows often require:

multiple exchanges
multiple wallets
manual treasury processes
fragmented operational visibility

As transaction volume grows, that model becomes increasingly difficult to manage.

Why Stablecoins Matter

When most people hear "stablecoins," they think about crypto.

But infrastructure teams increasingly think about them differently.

They think about settlement.

Stablecoins offer something traditional payment systems often struggle to provide:

global interoperability
24/7 settlement
programmable transfers
asset portability across networks

For payment companies, stablecoins are increasingly functioning as operational rails rather than speculative assets.

That's a significant shift.

The Infrastructure Layer

One detail from the case study stood out.

Afriex needed to support:

any stablecoin on any chain

for partner settlements across African markets.

That sounds simple.

It isn't.

Different counterparties may require:

different assets
different networks
different settlement preferences

Supporting that flexibility often introduces substantial operational complexity.

According to the case study, Utila provided a single platform that enabled:

multi-asset support
multi-chain support
treasury operations
wallet provisioning
settlement workflows

from one operational layer.

The result was less fragmentation and greater operational control.

Beyond Treasury: Wallet Infrastructure

Another interesting outcome was wallet provisioning.

As Afriex expanded its B2B platform, business customers needed dedicated wallet infrastructure.

Rather than treating wallets as an internal treasury tool, wallets became part of the customer-facing product experience.

Businesses could receive:

dedicated wallet addresses
preferred stablecoin support
preferred network support

while Afriex managed the infrastructure centrally.

This highlights an important trend:

Stablecoin infrastructure is increasingly becoming product infrastructure.

The Bigger Trend

The Afriex × Utila story reflects a broader industry movement.

Stablecoins are no longer only consumer products.

They are becoming:

treasury infrastructure
settlement infrastructure
liquidity infrastructure
payment infrastructure

Across the payments industry, companies are increasingly evaluating stablecoins as an alternative settlement layer because of their speed, global accessibility, and operational flexibility.

In many ways, stablecoins are evolving into the backend infrastructure powering modern money movement.

Users may never see them.

But they increasingly benefit from them.

The Real Lesson

The most interesting takeaway from the Afriex × Utila partnership isn't that a fintech adopted stablecoins.

It's that operational complexity becomes the biggest challenge as payment systems scale.

Building a payment product is one thing.

Operating liquidity, settlements, treasury, and customer infrastructure across dozens of markets is another challenge entirely.

The companies that succeed are often the ones that find ways to simplify that complexity.

That's what makes this case study interesting.

It's a reminder that behind every successful payment experience is an enormous amount of infrastructure working quietly in the background.

Final Thoughts

Cross-border payments are often discussed from the perspective of user experience.

Faster transfers.

Lower fees.

Better access.

But infrastructure tells a different story.

The real challenge is coordinating liquidity, settlements, treasury operations, and customer assets across a fragmented financial landscape.

The Afriex × Utila partnership offers a glimpse into how modern payment companies are approaching that challenge.

And increasingly, stablecoins are becoming part of the answer.

What Happens When AI Agents Can Access Payment Infrastructure? Exploring OpenClaw + Afriex MCP

0xSonOfUri — Fri, 29 May 2026 15:24:25 +0000

For years, we've built APIs for developers.

Every payment gateway, banking platform, fintech API, and infrastructure provider has been designed around a simple assumption:

A human developer writes the code that interacts with the API.

But what happens when AI agents become the users of those APIs?

That's the question I've been thinking about while exploring OpenClaw and Afriex MCP.

Not from the perspective of replacing developers.

But from the perspective of enabling AI systems to interact with infrastructure in meaningful ways.

The Shift From Code Generation to Infrastructure Interaction

Most developers have already experienced AI-assisted coding.

We use tools like Cursor to:

generate components
write tests
explain code
scaffold projects

But that's still fundamentally code generation.

The AI helps create software.

The developer remains the bridge between the software and the infrastructure.

The next evolution is different.

The AI doesn't just generate code.

The AI interacts with infrastructure directly.

Enter OpenClaw

OpenClaw is an open framework for building AI agents capable of interacting with tools and external systems.

Instead of simply responding to prompts, agents can:

perform actions
execute workflows
use tools
interact with services

This transforms the AI from a conversational assistant into something much more operational.

The interesting question becomes:

What tools should these agents have access to?

And that's where infrastructure enters the picture.

Enter Afriex MCP

Afriex MCP exposes Afriex capabilities through the Model Context Protocol.

This means AI-enabled tools and agents can interact with payment infrastructure through structured tooling.

Instead of building everything manually first, an agent can understand and interact with financial primitives such as:

balances
virtual accounts
transactions
payment workflows

through MCP-enabled interfaces.

On their own, OpenClaw and Afriex MCP are interesting.

Together, they become much more compelling.

What Could an Infrastructure-Aware Agent Do?

Imagine an AI agent with access to payment infrastructure.

Not in a hypothetical science-fiction future.

Today.

Balance Monitoring

An agent could continuously monitor balances across accounts.

When thresholds are reached, it could:

notify teams
trigger workflows
generate reports

without manual intervention.

Payment Operations

An agent could generate receiving instructions for customers.

For example:

Create a virtual account for Customer X.

The agent retrieves the required information and returns payment instructions immediately.

Transaction Monitoring

Instead of manually checking dashboards, agents could monitor transaction events and surface only what requires human attention.

Examples:

failed transactions
delayed settlements
unusual activity
reconciliation issues

Developer Workflows

This is the area that excites me most.

Imagine asking:

Generate a payment integration using Afriex.

Instead of simply generating generic code, the agent understands:

the infrastructure
available tools
workflow patterns

and builds with real context.

The difference is subtle.

But significant.

APIs Were Built for Developers

One idea keeps coming back to me.

For decades, we've designed APIs around human developers.

Documentation.
SDKs.
Authentication.
Request-response patterns.

Everything assumes a human sits in the middle.

But MCP introduces a different model.

Infrastructure becomes accessible not only to developers, but also to AI systems.

That changes how we think about integrations.

It changes how we think about tooling.

And eventually, it may change how software gets built.

Why Fintech Is Particularly Interesting

Many industries can benefit from infrastructure-aware agents.

Fintech stands out because financial workflows are already highly structured.

Consider how much time teams spend:

monitoring transactions
checking balances
reconciling payments
handling operational workflows

These are precisely the kinds of activities agents can assist with.

Not replacing humans.

Augmenting them.

Making teams more efficient.

Reducing operational friction.

The Bigger Picture

I don't think the most interesting outcome is:

AI writes code faster.

I think the more interesting outcome is:

AI understands and interacts with infrastructure.

That's a much bigger shift.

Because once agents can interact with infrastructure safely and predictably, entirely new workflows become possible.

OpenClaw provides the agent layer.

Afriex MCP provides the infrastructure layer.

Together they offer a glimpse into what AI-native financial systems might look like.

Final Thoughts

We're still early.

Most of these patterns are only beginning to emerge.

But one thing feels increasingly clear:

The future isn't just AI-assisted development.

It's infrastructure-aware AI.

And as developers, it's worth paying attention to what becomes possible when agents can interact with the systems we've spent years building.

OpenClaw and Afriex MCP are an interesting place to start exploring that future.

Afriex vs Flutterwave vs Paystack: Which One Should You Choose?

Victory Lucky — Mon, 25 May 2026 12:56:13 +0000

If you are building something that collects payments from customers, Paystack and Flutterwave are both solid choices and you probably already know that. This article is not about that.

This is about the other direction: sending money out. Paying a freelancer in Nairobi from a USD balance. Disbursing contractor fees to someone in Accra via MTN Mobile Money. Running payroll across five African countries without building a separate integration for each one. That is a different problem, and it needs a different tool.

The honest answer is that Paystack and Flutterwave were built collection-first. They handle disbursements, but with limits that matter once you are operating across borders. Afriex was built disbursement-first, for African corridors specifically. The comparison is not that one is better overall — it is that they solve different problems, and picking the wrong one for outbound payments means hitting walls you did not expect.

Here is how they actually compare.

What we are comparing

Three things matter for outbound disbursement:

Coverage — which countries and payment channels can you actually pay out to.

Developer experience — how the API is structured, what you need to do before money can move, how status updates work.

Fit for the use case — whether the tool was designed for this job or adapted to it.

We are not comparing collection features, pricing pages, or dashboard UX. Those are separate decisions.

Coverage

Paystack

Paystack is currently available for companies based in Nigeria, South Africa, Ghana, Kenya, and Côte d'Ivoire, supporting NGN, GHS, ZAR, KES, and USD (USD only in Kenya and Nigeria).

For outbound transfers, Paystack supports bank account payouts within those same markets. It primarily settles in local currencies — if someone pays in USD via a foreign card, funds are often converted to NGN or another local currency. USD payout to a recipient abroad is not a native flow.

If your recipients are Nigerian businesses with local NGN bank accounts and you are already using Paystack for collections, the transfers API works and settlement is fast. The moment your disbursement needs go outside Nigeria, Ghana, Kenya, or South Africa — or you need to pay in USD without conversion — Paystack starts to show its limits.

Flutterwave

Flutterwave is supported in Nigeria, Ghana, Kenya, South Africa, Uganda, Tanzania, the United Kingdom, the United States, and Europe. It processes payouts in 30+ currencies and has broader mobile money coverage than Paystack across East and West Africa.

Flutterwave is the wider net of the two, and for businesses that need to pay out in markets like Uganda and Tanzania where Paystack does not operate, it is the more practical choice. The transfers API is well-documented and the mobile money coverage is real.

The gap is that Flutterwave is still fundamentally a collection platform that also does transfers. The payout flow works, but the API was not designed with multi-country disbursement as its primary job.

Afriex

Afriex covers 31 African countries with payout rails across bank accounts, mobile money (MTN MoMo, M-Pesa, Airtel Money, and others), and SWIFT. Beyond Africa, USD SWIFT payouts reach 100 countries globally, including the US, UK, all of Europe, India, China, Canada, and more. Payment channels include bank transfers, mobile money, SWIFT, UPI (India), Interac (Canada), WeChat Pay and Alipay (China), and crypto (USDC/USDT).

The coverage table for African countries specifically:

Country	Payout Rails
Nigeria	Bank Account
Kenya	Bank Account, Mobile Money, Paybill/Till
Ghana	Bank Account, Mobile Money
Uganda	Bank Account, Mobile Money
Tanzania	Mobile Money
Cameroon	Bank Account, Mobile Money
Côte d'Ivoire	Bank Account, Mobile Money
Ethiopia	Bank Account, Mobile Money
Egypt	Bank Account, Mobile Money
South Africa	Bank Account
Rwanda	Bank Account, Mobile Money
Senegal	Bank Account, Mobile Money
+ 19 more African countries	Mobile Money

The difference is not just the number of countries. It is that mobile money is a first-class channel in the Afriex API, not an add-on. In Kenya, you can pay to a bank account, an M-Pesa wallet, or a Paybill/Till number from the same integration. In Ghana, bank and MTN MoMo are both available. For many recipients in these markets, mobile money is their primary financial account, not a fallback.

Developer experience

How Paystack transfers work

Paystack's transfers API follows a straightforward pattern: create a transfer recipient (stores the bank account details), then initiate a transfer to that recipient. The API is clean and the docs are good. The limitation is that it is scoped to Paystack's supported markets, so there is no concept of channel selection — bank account is the primary output.

For a developer building payroll or contractor payouts strictly within Nigeria, the API is simple and it works. For anything involving mobile money payouts or recipients outside Paystack's five markets, you are building a separate integration.

How Flutterwave transfers work

Flutterwave's transfer API accepts bank account details directly without a separate recipient creation step, which makes it slightly lighter for one-off payouts. Mobile money transfers are supported for several African markets. The documentation covers the major corridors well.

The gap developers hit in production is reliability. Flutterwave offers broad African coverage across 34 countries with extensive mobile money integration but has more variable API reliability than Paystack or Stripe. For a payroll system where every transfer matters, variable reliability in production is a real constraint to account for.

How Afriex transfers work

The Afriex API uses a three-step model: create a customer, attach a payment method, create a transaction. It is slightly more upfront setup than Flutterwave's direct transfer approach, but the structure is deliberate — the payment method record stores verified account details that can be reused across multiple payouts without re-entering them.

POST /api/v1/customer       → returns customerId
POST /api/v1/payment-method → returns paymentMethodId  
POST /api/v1/transaction    → uses both IDs, returns transactionId

For a payroll use case, this is actually the right model. You register an employee once, attach their bank account or mobile wallet once, and then every subsequent payout is a single transaction call with the stored IDs. Repeat disbursements to the same recipient require no additional setup.

The meta.idempotencyKey field on every transaction prevents duplicates if a job retries after a network failure. The reference field maps every transaction back to your internal records. Both are required, which enforces good practice.

Transaction types map cleanly to the three outbound flows:

WITHDRAW — send money from your Afriex wallet to a recipient's account
DEPOSIT — pull money from a customer's account into your wallet
SWAP — convert between currencies in your Afriex wallet without touching any external account

For disbursement specifically, WITHDRAW is the one you use.

Status updates and webhooks

This is where the tools diverge most practically for anyone building a reliable disbursement system.

Paystack and Flutterwave

Both support webhooks for transfer status updates. The status vocabulary is standard: pending, success, failed. For domestic transfers that settle quickly, this is sufficient. For cross-border payouts that can sit in intermediate states for longer — especially in corridors with compliance review steps — a simple success/failed model leaves you with less visibility than you need.

Afriex

The Afriex webhook system fires on TRANSACTION.CREATED and TRANSACTION.UPDATED.
Here's the full status vocabulary:

Status	What it means for your system
`PENDING`	Received, not yet processed — do nothing
`PROCESSING`	Actively moving — do nothing, wait
`COMPLETED` / `SUCCESS`	Settled — notify recipient, update your records
`IN_REVIEW`	Under compliance review — notify the user, do not mark as failed
`RETRY`	Network is retrying automatically — do nothing
`FAILED`	Terminal failure — alert user, allow retry
`REJECTED`	Rejected after review — alert user with reason
`REFUNDED`	Funds returned — update your records
`UNKNOWN`	Indeterminate — alert your team to investigate

The IN_REVIEW and RETRY statuses are the ones that matter most for cross-border corridors. IN_REVIEW reflects a real compliance hold that African payment networks produce — it is not a failure state, and treating it as one causes support noise for payouts that are actually in progress. RETRY means the network is handling it without any action needed from your code.

Webhooks are signed with RSA-SHA256 and verified against your public key from the dashboard. Afriex retries delivery up to 12 times with exponential backoff from 30 seconds to 16 hours, which means a temporary outage on your end does not mean lost status updates.

The full webhook implementation guide is covered in the Afriex webhook article.

When to use each one

This is the honest summary.

Use Paystack transfers if:

Your recipients are in Nigeria, Ghana, Kenya, South Africa, or Côte d'Ivoire only
You are already using Paystack for collection and want a single integration
Your payout volume is primarily NGN bank transfers with fast local settlement

Use Flutterwave transfers if:

You need to pay out in markets Paystack does not cover, like Uganda or Tanzania
You need mobile money coverage across multiple East and West African markets
Your use case tolerates some variability in API reliability for the sake of broader coverage

Use Afriex if:

You are building a product where disbursement is the primary job: payroll, contractor payouts, scholarship disbursements, creator payouts
Your recipients are spread across African countries and corridors, including mobile money wallets
You need to pay out in USD to recipients outside Africa via SWIFT without a separate integration
You need a detailed transaction status model that maps to how African payment networks actually behave
You want to store recipient payment method details once and reuse them across multiple payouts

The cleanest setup for a product that does both collection and disbursement is: Paystack or Flutterwave for inbound (they are better positioned for that job), and Afriex for outbound. They are complementary, not competing. Paystack collects your revenue, Afriex pays your contractors.

Getting started with Afriex disbursements

The Afriex Business API has a free sandbox environment. No approval gate, no manual credentials process to get through before you can test. Create an account, grab your sandbox API key from Settings > API Keys, and you can run the full disbursement flow — customer creation, payment method attachment, transaction execution, webhook delivery — before you touch production.

The integration guide covering the full three-step flow with code examples is in the freelancer payout platform tutorial.

Afriex Webhook Integration Guide: Signature Verification, Event Handling, and Production Best Practices

Victory Lucky — Mon, 25 May 2026 01:17:44 +0000

When you create a transaction through the Afriex Business API, the response you get back is just the start. The transaction comes back with a status of PENDING. What happens after that — whether it moves to PROCESSING, COMPLETED, IN_REVIEW, or FAILED arrives through webhooks.

Most integration bugs in payment systems trace back to webhook handling, not the API calls themselves. Missed signature verification. Handlers that time out. Status updates applied twice. Fields read from parsed JSON instead of the raw body. These are the mistakes that cause payouts to look settled when they are not, or trigger duplicate notifications to your users.

This article covers how Afriex webhooks work, every event the system fires, how to verify signatures correctly, how to build a handler that holds up in production, and how to test locally before you go live.

What Afriex sends and when

Afriex fires a signed HTTP POST to your configured webhook URL whenever a resource changes. Three resource types generate events.

Transaction events are the ones you will interact with most. Every time a transaction is created or its status changes, Afriex fires either TRANSACTION.CREATED or TRANSACTION.UPDATED. Here's the full status vocabulary that a transaction moves through:

Status	What it means
`PENDING`	Transaction received, waiting to be processed
`PROCESSING`	Actively being processed
`COMPLETED`	Settled successfully
`SUCCESS`	Alias for a settled transaction
`FAILED`	Failed. Check `meta` for details
`CANCELLED`	Cancelled before processing started
`REFUNDED`	Funds returned to sender
`IN_REVIEW`	Under manual review
`REJECTED`	Rejected after review
`RETRY`	Being automatically retried by the network
`UNKNOWN`	Status could not be determined. Contact support

Customer events fire when a customer is created (CUSTOMER.CREATED), their details are updated (CUSTOMER.UPDATED), or they are deleted (CUSTOMER.DELETED). These are useful for keeping your local customer records in sync with Afriex.

Payment method events fire on creation (PAYMENT_METHOD.CREATED), update (PAYMENT_METHOD.UPDATED), and deletion (PAYMENT_METHOD.DELETED). If a payment method is deleted on the Afriex side, your application needs to know so it can prompt the user to attach a new one before the next payout.

There is also CHECKOUT_SESSION.CREATED for checkout flows.

Before you go live: allowlist the IP addresses

This step catches developers off guard. Before Afriex can deliver webhooks to your server, your firewall must allow inbound traffic from Afriex's IP addresses. Webhook requests from any other IP should be blocked regardless of whether the signature is valid.

Environment	IP Address
Sandbox	`34.234.189.210`
Production	`34.197.33.100`

Add these to your firewall or security group allowlist. Without this, Afriex webhook requests will be silently blocked before they reach your handler.

Setting up your endpoint

In your Afriex dashboard, go to Developers then the Webhooks tab. Paste your endpoint URL and save. Your webhook public key is on the same screen — copy it and store it as an environment variable. You will need it for signature verification.

Staging and production use different public keys. Make sure you are using the correct one for each environment.

Signature verification

Every webhook Afriex sends includes an x-webhook-signature header. This is a Base64-encoded RSA-SHA256 signature of the raw request body, signed with Afriex's private key. You verify it using the public key from your dashboard.

Two things to get right here that developers frequently get wrong:

Verify against the raw body, not parsed JSON. If you parse the body to JSON first and then try to verify the signature against the re-serialized string, it will fail. The signature was computed against the exact bytes Afriex sent. Any transformation — even a whitespace difference — breaks it.

Reject the request immediately if verification fails. Do not process the payload. Do not log it as a real event. Return 400 or 401 and stop.

Here is the correct verification implementation:

import crypto from "crypto";

function verifyWebhookSignature(
  signature: string,
  rawBody: string | Buffer,
  publicKey: string
): boolean {
  try {
    const verifier = crypto.createVerify("RSA-SHA256");
    verifier.update(rawBody);
    return verifier.verify(publicKey, signature, "base64");
  } catch {
    return false;
  }
}

In a Next.js API route, you need to read the raw body before any parsing happens:

// src/app/api/webhooks/route.ts
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";

export async function POST(req: NextRequest) {
  const signature = req.headers.get("x-webhook-signature");

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 401 });
  }

  // Read raw body before any parsing
  const rawBody = await req.text();

  const isValid = verifyWebhookSignature(
    signature,
    rawBody,
    process.env.AFRIEX_WEBHOOK_PUBLIC_KEY!
  );

  if (!isValid) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  // handle payload
}

In a Fastify application, you need to preserve the raw body before Fastify's JSON parser consumes it:

// Register this plugin before routes
fastify.addContentTypeParser(
  "application/json",
  { parseAs: "string" },
  (req, body, done) => {
    try {
      const parsed = JSON.parse(body as string);
      // Attach raw string to request for webhook verification
      (req as any).rawBody = body;
      done(null, parsed);
    } catch (err) {
      done(err as Error, undefined);
    }
  }
);

The payload structure

Every Afriex webhook follows the same envelope:

{
  "event": "TRANSACTION.UPDATED",
  "data": { ... }
}

The event field tells you what happened. The data field contains the resource. Here is what each resource type looks like:

Transaction payload

{
  "event": "TRANSACTION.UPDATED",
  "data": {
    "transactionId": "69d60071ab82306f11b03393",
    "status": "COMPLETED",
    "type": "WITHDRAW",
    "sourceAmount": "3.28847",
    "sourceCurrency": "USD",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "destinationId": "690df3281c11eea59108fcaf",
    "customerId": "69528240ba52c13b669fb239",
    "meta": {
      "reference": "ref-withdraw-001",
      "idempotencyKey": "idem-withdraw-001"
    },
    "createdAt": "2026-04-08T07:14:57.444Z",
    "updatedAt": "2026-04-08T07:15:30.000Z"
  }
}

Customer payload

{
  "event": "CUSTOMER.UPDATED",
  "data": {
    "customerId": "698b0440cba7ec3daee9163d",
    "name": "John Smith",
    "email": "johnsmith@gmail.com",
    "phone": "+2348012345678",
    "countryCode": "NG",
    "meta": {},
    "createdAt": "2026-02-10T10:11:12.415Z",
    "updatedAt": "2026-02-11T15:30:45.123Z"
  }
}

Payment method payload

{
  "event": "PAYMENT_METHOD.DELETED",
  "data": {
    "paymentMethodId": "69f87b0dcc0ee96511560796",
    "channel": "BANK_ACCOUNT",
    "customerId": "6922e4520a53e858ab42efa8",
    "institution": {
      "institutionCode": "058",
      "institutionName": "GTBank"
    },
    "accountName": "John Smith",
    "accountNumber": "1234567890",
    "countryCode": "NG"
  }
}

Building a production-grade handler

A webhook handler has one job: acknowledge receipt fast, then process asynchronously. Afriex expects a 2xx response within about 5 seconds. If your handler does database writes, sends emails, or calls other APIs synchronously before returning, you will hit that window under any real load.

The pattern that holds up:

Verify signature
Return 200 immediately
Push the raw payload to a queue
Process in a background worker

// Lean handler — verify, acknowledge, enqueue
export async function POST(req: NextRequest) {
  const signature = req.headers.get("x-webhook-signature");
  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 401 });
  }

  const rawBody = await req.text();
  const isValid = verifyWebhookSignature(
    signature,
    rawBody,
    process.env.AFRIEX_WEBHOOK_PUBLIC_KEY!
  );

  if (!isValid) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  // Enqueue for async processing — do not process inline
  await queue.add("webhook", { payload: JSON.parse(rawBody) });

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

Handle each event correctly

Not every status requires the same response. Here is a decision map for transaction events:

async function handleTransactionEvent(payload: TransactionWebhookPayload) {
  const { transactionId, status } = payload.data;

  // Update your database first
  await updateTransactionStatus(transactionId, status);

  switch (status) {
    case "PROCESSING":
      // Informational — no user-facing action needed
      break;

    case "COMPLETED":
    case "SUCCESS":
      // Terminal success — notify user, update UI state
      await sendPayoutConfirmationEmail(transactionId);
      break;

    case "IN_REVIEW":
      // Compliance hold — notify user that payout is under review
      // Do not mark as failed. Wait for further updates.
      await notifyPayoutUnderReview(transactionId);
      break;

    case "RETRY":
      // Network is retrying automatically — no action needed
      // Do not alarm the user
      break;

    case "FAILED":
    case "REJECTED":
      // Terminal failure — notify user, allow them to retry
      await sendPayoutFailedAlert(transactionId, status);
      break;

    case "UNKNOWN":
      // Indeterminate — log and alert your team to investigate
      await alertTeam(`Transaction ${transactionId} reached UNKNOWN status`);
      break;
  }
}

The IN_REVIEW and RETRY statuses are the ones most developers handle incorrectly. IN_REVIEW is not a failure — it is a compliance hold that will resolve into COMPLETED or REJECTED. If you mark it as failed and notify the user, you will have unhappy users chasing payouts that are actually in progress. RETRY means the network is handling it automatically. No action needed on your end.

Make your handler idempotent

Afriex retries webhook delivery up to 12 times with exponential backoff. Your handler will receive the same event more than once. That is by design. Your code needs to handle it gracefully.

The simplest approach: store a record of processed webhook event IDs and skip any you have already handled.

async function processWebhookEvent(payload: WebhookPayload) {
  const eventId = `${payload.event}:${payload.data.transactionId}:${payload.data.updatedAt}`;

  // Check if we have already processed this exact event
  const alreadyProcessed = await db
    .select()
    .from(processedWebhooks)
    .where(eq(processedWebhooks.eventId, eventId))
    .limit(1);

  if (alreadyProcessed.length > 0) {
    // Already handled — acknowledge and return
    return;
  }

  // Process the event
  await handleTransactionEvent(payload);

  // Mark as processed
  await db.insert(processedWebhooks).values({ eventId, processedAt: new Date() });
}

For the idempotency key you can use a combination of event type, resource ID, and updatedAt timestamp. This way, the same status update arriving twice is treated as a duplicate and skipped, but a genuine status change on the same transaction (e.g., PROCESSING followed by COMPLETED) is treated as two distinct events.

Handle customer and payment method events

async function handleCustomerEvent(payload: CustomerWebhookPayload) {
  const { event, data } = payload;

  if (event === "CUSTOMER.UPDATED") {
    // Keep your local record in sync
    await updateLocalCustomer(data.customerId, {
      name: data.name,
      email: data.email,
    });
  }

  if (event === "CUSTOMER.DELETED") {
    // Mark the customer as removed in your DB
    await markCustomerDeleted(data.customerId);
  }
}

async function handlePaymentMethodEvent(payload: PaymentMethodWebhookPayload) {
  const { event, data } = payload;

  if (event === "PAYMENT_METHOD.DELETED") {
    // Remove from your DB and flag the customer as needing a new payout method
    await removePaymentMethod(data.paymentMethodId);
    await flagCustomerNeedsPaymentMethod(data.customerId);
  }
}

Retry behavior

Afriex retries failed webhook deliveries up to 12 times. The schedule:

30s → 1m → 2m → 4m → 8m → 16m → 32m → 1h → 2h → 4h → 8h → 16h

A delivery is considered failed if your endpoint returns a non-2xx status or does not respond within about 5 seconds. This means your handler timing out is treated the same as a hard error — Afriex will retry.

Two practical implications. First, your handler must respond quickly (within 5 seconds) regardless of what processing needs to happen — hence the enqueue-and-return pattern above. Second, you should never rely solely on webhooks for reconciliation. Build a polling fallback: periodically call GET /api/v1/transaction/:id for transactions that have been in a non-terminal status for longer than expected. Webhooks are the fast path. The API is the source of truth.

Testing locally

Afriex provides a sandbox-only endpoint for firing real signed webhooks against your local handler without needing to manufacture underlying activity. You create an entity (a customer, payment method, or transaction) in sandbox, then call the trigger endpoint with the entity ID and the event name you want to test.

curl --request POST \
  --url https://sandbox.api.afriex.com/api/v1/webhooks/trigger \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your-sandbox-api-key' \
  --data '{
    "event": "TRANSACTION.UPDATED",
    "entityId": "69d60071ab82306f11b03393"
  }'

Afriex will send a real signed webhook to your configured callback URL using that entity as the payload. Because it is a real signed payload, your signature verification code runs exactly as it would in production.

To receive it locally, expose your dev server with ngrok:

npx ngrok http 3000

Register the HTTPS URL ngrok gives you as your webhook URL in the Afriex sandbox dashboard, then fire the trigger. You can test every event type this way — CUSTOMER.CREATED, PAYMENT_METHOD.DELETED, TRANSACTION.UPDATED with any status — against a real entity in sandbox.

The trigger endpoint returns 403 Forbidden in production, so there is no risk of accidentally firing test webhooks against your live environment.

Checklist before going live

[ ] Afriex IP addresses added to your server allowlist (34.197.33.100 for production)
[ ] Webhook public key stored as an environment variable, not hardcoded
[ ] Signature verification runs against raw body bytes, not parsed JSON
[ ] Handler returns 2xx within 5 seconds
[ ] Processing happens asynchronously after acknowledgement
[ ] All 11 transaction statuses handled explicitly — including IN_REVIEW, RETRY, and UNKNOWN
[ ] Handler is idempotent — safe to receive the same event multiple times
[ ] PAYMENT_METHOD.DELETED event triggers a flag in your database
[ ] Polling fallback implemented for transactions stuck in non-terminal status
[ ] Tested all event types using the sandbox trigger endpoint

The full webhook reference is at docs.afriex.com/api-reference/endpoint/webhooks/introduction. The transaction API reference, including the full request and response schema, is at docs.afriex.com/api-reference/endpoint/transactions/create.

How Agentic AI Is Changing Cross-Border Payments (and What It Means for Developers)

Victory Lucky — Sun, 24 May 2026 06:21:36 +0000

For most of the last decade, AI in payments meant one thing: fraud detection. A model sitting downstream, flagging suspicious transactions after the fact. Useful, but passive. The system still required a human or deterministic code to decide what to do next.

That is changing fast. Agentic AI emerged as the breakout technology of 2025, moving from demos into regulated payment workflows. The difference is not the model. It is the architecture. Agentic systems do not just classify or predict. They plan, execute multi-step workflows, and take action across external systems without a human in the loop for every step. In payments, that shift has real consequences for how infrastructure gets built and what developers need to understand.

What agentic AI actually means in a payments context

The term gets used loosely, so a working definition is worth establishing. An AI agent in a payment context is a system that receives a high-level goal, decides what sequence of API calls to make to achieve it, executes them, handles failures, and reports the outcome, with no human approving each individual step.

The IMF's May 2026 note on agentic AI in payments describes the scope of experimentation as expanding rapidly: from fraud detection and compliance monitoring to treasury optimization and cross-border payment orchestration. Fenwick's 2026 agentic payments analysis draws the line clearly: unlike traditional autopay automation, agentic AI makes decisions and takes actions to achieve goals. It is not executing a predefined script.

The practical difference for a developer is this: instead of writing code that calls get_balance, evaluates the result, and conditionally calls create_transaction, you expose those capabilities as tools and let the model decide the sequence based on a stated goal. The orchestration logic moves from your codebase to the model. The code you write shrinks. The capability surface expands.

Where agentic payment automation is already happening

A March 2026 analysis of earnings calls across 24 companies in the cross-border payments space found AI mentions surging significantly year over year. The themes were not hypothetical. NatWest said AI agents can "execute complex banking workflows" on behalf of customers. Remitly announced plans to deploy agentic technology across productivity, fraud reduction, and decision-making in 2026.

Agentic AI is moving toward anticipating intent, verifying identity, detecting fraud, and authorizing transactions in real time across platforms, all in a single autonomous workflow rather than across separate systems. Compliance teams are using agentic AI to shift from static rule-based watchlist screening to continuous, trigger-based monitoring. Watchlist screening currently generates 90 to 95 percent false positives, and agentic systems with richer contextual reasoning are actively pushing that number down.

For cross-border payment infrastructure specifically, the primary application is treasury optimization and payment orchestration. Cross-border flows hit $190 trillion annually and legacy systems still route most of that through multi-step correspondent banking chains. Agentic payment systems can evaluate multiple rail options in real time, select the optimal one for a given corridor and amount, monitor for settlement status, and escalate to a human only when a transaction falls outside expected parameters.

The architectural challenge this creates

The IMF note identifies what it calls a central architectural challenge: as AI agents gain the ability to initiate and execute payment transactions autonomously, the traditional assumption that a human authorizes each individual transaction breaks down. The legal and liability frameworks built around that assumption do not map cleanly onto autonomous agent behavior.

Existing financial and consumer protection laws built around human-decisioned transactions may not appropriately address the challenges raised by agentic payments. Companies building agentic payment automation need to navigate unsettled questions under AI laws, money transmitter regimes, and authorization frameworks simultaneously.

For developers, this creates two concrete requirements. First, every action an agent takes on behalf of a user must be logged with enough detail to reconstruct exactly what the agent decided, what information it had at the time, and what it executed. Immutable audit logs are not a nice-to-have in agentic payment systems. They are the primary mechanism for accountability. Second, agent scope must be explicitly bounded. An agent authorized to send payroll disbursements should not be able to initiate arbitrary transactions outside that context. Tool-level permission scoping, not just API key permissions, is the right model here.

What agentic orchestration requires from payment APIs

The shift toward autonomous payment systems changes the requirements for the payment APIs agents build on. These requirements are stricter than what human-driven integrations demand.

Tool descriptions carry the same weight as endpoint documentation. When a human developer integrates an API, they read the docs and write code. When an AI agent integrates a payment API, it reads the tool descriptions and decides what to call. An ambiguous tool description produces wrong agent behavior the same way an ambiguous endpoint contract produces bugs. Payment infrastructure providers who want their APIs used in agentic payment workflows need to treat tool descriptions as a first-class product concern.

Error responses need to be machine-interpretable, not just human-readable. An agent that receives "Something went wrong" cannot decide whether to retry, escalate, or abort. Structured error codes like INSUFFICIENT_BALANCE, FX_RATE_EXPIRED, and PAYMENT_METHOD_INVALID give the model the information it needs to make the right decision without human intervention.

Transaction status granularity matters more than it did before. In a human-driven integration, a developer can decide how to handle an ambiguous status. In an agentic payment workflow, the agent needs enough signal to act correctly on its own. A payment API that returns PENDING for multiple distinct states forces the agent to guess. A well-designed one surfaces the full status vocabulary the underlying network produces: PENDING, PROCESSING, IN_REVIEW, COMPLETED, FAILED, REJECTED, RETRY, REFUNDED. Each status maps to a different agent decision. IN_REVIEW means wait and poll. RETRY means the network is handling it. REJECTED means surface to a human. The Afriex Business API exposes exactly this vocabulary on every transaction, which is one reason it is well-suited as infrastructure for agentic payment automation.

Idempotency is non-negotiable. Agents retry. Networks fail. Without idempotency keys, payment APIs risk duplicate transactions that are costly and difficult to reverse. An autonomous payment system without idempotent operations is a double-payment incident waiting to happen. The Afriex SDK accepts an idempotency key on every transaction creation call, which means retrying a failed disbursement job is safe by design.

The African corridor context

For developers building agentic payment automation for African markets, the infrastructure complexity is higher than most global payment APIs assume, and the choice of payment API matters more as a result.

Mobile money is the dominant payment rail in East and West Africa, not cards and not bank transfers. FX volatility in corridors like NGN/USD means a rate that is valid at the moment an agent job is created may be meaningfully different at the moment of settlement. Transaction statuses like IN_REVIEW reflect real compliance holds that African payment networks produce, not just generic processing delays. An agent operating in this environment needs access to tools that reflect those realities rather than abstracting them away.

The Afriex Business API is built against this infrastructure directly. Mobile money, bank transfers, SWIFT, and local payment channels are all first-class integrations. Exchange rates are live across NGN, KES, GHS, GBP, and other African corridor pairs. The Afriex MCP server exposes the full API surface as 22 callable tools for agentic workflows: get_rates for live rates before committing to a disbursement, get_balance to verify funds before a payroll run starts, resolve_payment_method to verify a recipient account before attaching it, create_transaction with idempotency key support, and get_transaction for status polling after execution. The full transaction status vocabulary, including IN_REVIEW, RETRY, and REJECTED, is surfaced through webhooks so an agent always has enough signal to decide its next action correctly.

What to build now versus what to watch

Build now: agentic payroll disbursement. The use case is clear, the failure modes are well-understood, and the liability surface is bounded because a human approves the payroll run before the agent executes it. The agent's autonomy is scoped to execution, not authorization. This is the lowest-risk entry point for agentic payment automation and has the most direct ROI. The architecture for this, including how it integrates with the Afriex Business API, is covered in the companion architecture document.

Build now: agentic FX monitoring and settlement timing. An agent that watches a currency corridor, evaluates whether the current rate is within a threshold, and triggers settlement when conditions are met is straightforward to implement using the Afriex MCP server's get_rates tool on a schedule. It is immediately valuable for any business running frequent cross-border payment flows.

Watch: fully autonomous payment authorization. Agents that can initiate arbitrary payments based on their own assessment of conditions, without a human approving each batch, sit in genuinely unsettled legal territory. The legal framework for autonomous payment authorization is unresolved, and building ahead of regulatory clarity is a risk most developers should not take on without specific legal guidance.

Watch: multi-agent payment orchestration. Chains of agents handing off payment decisions to each other across organizational boundaries are one of the most technically and legally complex areas in agentic AI right now. The IMF note identifies this as a central challenge. The infrastructure protocols for secure multi-agent communication across payment networks are still being standardized.

The bottom line

Agentic AI does not change what cross-border payment infrastructure needs to do. It changes who is doing the orchestrating. The requirements for the underlying payment API layer get stricter as a result: machine-interpretable error codes, granular transaction status vocabularies, idempotent operations, and tool descriptions precise enough for a model to act on correctly without human clarification.

For developers, the opportunity in agentic payment automation is real and immediate in bounded use cases. The risk is real too, and proportional to how much autonomous authorization you give the agent. Start with execution autonomy, keep authorization human, and build the audit trail as if regulators will read it. Because eventually, they will.