DEV Community: Afriex

Afriex vs Flutterwave vs Paystack: Which One Should You Use for Payouts and Disbursements?

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.

Getting Started with Afriex MCP in Cursor

0xSonOfUri — Sat, 16 May 2026 15:17:52 +0000

AI coding tools are evolving quickly.

But the real shift starts when your editor can interact with infrastructure directly.

Instead of only generating code, AI tools can now:

query APIs
interact with services
retrieve live data
execute workflows

That’s where MCP comes in.

In this guide, you’ll learn how to:

set up Afriex MCP in Cursor
connect your Afriex account
verify your setup
understand how MCP changes the developer workflow

This is not a product demo.

This is a practical setup guide for developers getting started with Afriex MCP.

What is MCP?

MCP (Model Context Protocol) is a standardized way for AI tools to interact with external systems and services.

Instead of treating the AI editor as:

“just a code generator”

MCP allows it to become:

“an infrastructure-aware development environment”

With MCP, AI tools can:

access APIs
call external tools
retrieve live data
orchestrate workflows

directly from inside the editor.

Why This Matters

Normally, integrating financial infrastructure involves:

reading documentation
wiring SDKs manually
testing requests
switching between dashboards and terminals

With MCP:

the editor gains context
workflows become faster
AI can assist with infrastructure interactions directly

This creates a very different developer experience.

What is Afriex MCP?

Afriex MCP exposes Afriex infrastructure capabilities to AI-enabled developer tools like Cursor.

This allows Cursor to:

retrieve balances
understand payment workflows
scaffold integrations
interact with Afriex APIs through MCP tools

directly from natural language prompts.

Prerequisites

Before starting, you’ll need:

An Afriex Business account
Cursor installed
An Afriex API key

Useful links:

Step 1 — Log Into Afriex Business

Head to:

https://business.afriex.com/

Log into your Afriex Business account.

Step 2 — Open the Documentation

Inside the dashboard:

Navigate to:
- Developer
- API Documentation

Afriex provides detailed developer documentation including MCP setup instructions.

Step 3 — Open the MCP Guide

Inside the docs:

Open:
- MCP Server
- Connecting MCP Clients

This section contains:

supported MCP clients
setup instructions
recommended configurations

Step 4 — Select Cursor

Afriex supports multiple MCP-capable tools and IDEs.

In this guide, we’ll use:

Cursor

Copy the recommended Cursor MCP configuration from the docs.

Step 5 — Configure Cursor

Inside Cursor:

Open Settings
Navigate to:
- Tools & MCPs
Click:
- Add Custom MCP

Paste the configuration you copied from the Afriex documentation.

Step 6 — Update Your Credentials

Update the configuration with your credentials:

"x-afriex-api-key": "YOUR_API_KEY",
"x-afriex-environment": "production"

You can also use:

"x-afriex-environment": "sandbox"

for testing environments if supported in your workflow.

Step 7 — Verify the Connection

Now that Cursor is connected to Afriex MCP, try a simple prompt inside Cursor:

Use Afriex MCP to fetch my live balances

If everything is configured correctly, Cursor should retrieve:

NGN balances
USD balances
supported wallet balances

directly from Afriex.

At this point, your editor is no longer operating purely as a code assistant.

It can now interact with infrastructure through MCP.

What Makes This Interesting

The important shift here is not:

“AI generates code.”

The interesting part is:

“AI can now interact with systems.”

That changes the workflow significantly.

Instead of:

constantly context switching
manually wiring everything first
navigating infrastructure alone

developers can now work with AI tools that understand:

APIs
infrastructure
workflows
integrations

more directly.

Example MCP Workflow

Once connected, you can start using prompts like:

Fetch my Afriex balances

Help me scaffold an Afriex integration

Generate a Next.js API route for Afriex virtual accounts

Create a webhook handler for Afriex payment events

The AI editor now has context about:

the infrastructure
the available tools
the integration patterns

which makes the development experience much smoother.

Security Notes

When using MCP integrations:

never expose your API keys publicly
avoid committing credentials to Git repositories
use environment variables where possible
rotate keys periodically

Treat your MCP configuration with the same care as production infrastructure credentials.

Where This Goes Next

Afriex MCP opens up workflows around:

payments
virtual accounts
payouts
reconciliation
infrastructure automation
fintech developer tooling

And this is still early.

As MCP ecosystems evolve, developer tools will become increasingly:

infrastructure-aware
execution-aware
workflow-aware

Final Thoughts

Setting up Afriex MCP inside Cursor only takes a few minutes.

But the implications are much bigger.

We’re moving toward a world where AI editors:

understand infrastructure
interact with APIs
assist with integrations
help orchestrate real systems

not just generate snippets.

And honestly, that changes how software gets built.

Resources

Afriex Business

https://business.afriex.com/

Afriex Documentation

https://docs.afriex.com/

Cursor

https://cursor.com/

Build Cross-Border Payment AI Agents with the Afriex MCP Server

Victory Lucky — Sat, 02 May 2026 04:20:50 +0000

Payment integrations are straightforward until they are not. A single payout involves checking a balance, resolving a bank code, verifying an account number, looking up a live exchange rate, and then executing the transaction — each step a separate API call, each one requiring code you write and maintain.

The Afriex MCP server lets an AI agent handle that entire sequence through natural language. It exposes the complete Afriex Business API as 20+ callable tools — customers, transactions, payment methods, exchange rates, and balances — that any MCP-compatible client can discover and use without SDK wiring.

Connect it to Claude Desktop, Claude Code, or Cursor and your AI assistant can register customers, attach bank accounts and mobile money wallets, fetch live NGN/KES/GHS rates, and trigger cross-border payouts — all from a single prompt.

If you are not yet familiar with Model Context Protocol and how it works, this article covers the protocol, architecture, and security model before you continue here.

The 20+ tools

The server endpoint is https://mcp.afriex.com/mcp. Full reference at docs.afriex.com/mcp/introduction.

Authentication

Tool	What it does
`authenticate`	Sets your API key and environment for the session
`session_info`	Returns current session config — masked API key, environment, base URL

Customers

Tool	What it does
`create_customer`	Creates a customer with name, email, phone, and country code
`list_customers`	Returns a paginated list of customers
`get_customer`	Fetches a customer by ID
`delete_customer`	Deletes a customer by ID
`update_customer_kyc`	Updates KYC information for a customer

Transactions

Tool	What it does
`create_transaction`	Creates a `DEPOSIT`, `WITHDRAW`, or `SWAP` transaction
`list_transactions`	Returns a paginated list of transactions
`get_transaction`	Fetches a transaction by ID

Payment methods

Tool	What it does
`create_payment_method`	Creates a payment method: `BANK_ACCOUNT`, `SWIFT`, `MOBILE_MONEY`, `UPI`, `INTERAC`, `WE_CHAT`
`list_payment_methods`	Returns a paginated list of payment methods
`get_payment_method`	Fetches a payment method by ID
`delete_payment_method`	Deletes a payment method by ID
`list_institutions`	Lists banks and mobile money providers by country and channel
`resolve_institution_codes`	Resolves a SWIFT code or routing number to a bank name
`resolve_payment_method`	Resolves recipient info by account number or phone
`get_crypto_wallet`	Gets or creates a USDT/USDC crypto wallet (production only)
`get_virtual_account`	Gets or creates a virtual account (production only)

Organization

Tool	What it does
`get_balance`	Fetches wallet balances for specified currencies
`get_rates`	Gets live exchange rates across supported corridors
`topup_balance`	Tops up sandbox balance (development only)

Connecting your client

You will need an Afriex Business API key from the dashboard. Pass it via HTTP headers — this keeps credentials out of the conversation context and authenticates every tool call automatically.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Restart Claude Desktop. The Afriex tools will appear in the tools panel.

Claude Code

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Or via the CLI:

claude mcp add afriex --transport http https://mcp.afriex.com/mcp

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Or go to Cursor Settings → MCP → Add new MCP Server, set type to URL, and enter https://mcp.afriex.com/mcp.

Without HTTP headers

If your client does not support custom headers, connect to the server URL without them and use the authenticate tool as your first prompt:

"Authenticate with API key your-api-key in the production environment."

The server stores your credentials for the session and uses them for all subsequent tool calls.

What you can build

Cross-border payout agent

A complete payout as an MCP tool chain:

list_institutions — resolve the correct bank or mobile money code for the recipient's country
create_customer — register the recipient
update_customer_kyc — complete KYC
resolve_payment_method — verify the account number before attaching it
create_payment_method — attach the verified bank account or mobile wallet
get_rates — preview the live exchange rate
get_balance — confirm sufficient funds before committing
create_transaction with type: "WITHDRAW" — execute the payout
get_transaction — poll settlement status

The agent chains these in sequence and branches on results — it will not call create_transaction if get_balance returns insufficient funds. You state the intent, the model decides the sequence.

Payroll disbursement agent

An agent that reads a payroll file and disburses to each employee across multiple African corridors:

get_rates per currency corridor to confirm converted amounts upfront
get_balance to verify total funds before any disbursement starts
For each employee: list_customers to check if they exist, create_customer if not, create_payment_method if no payout method is on file
create_transaction per employee
get_transaction to confirm each settlement

If a customer already exists, the agent skips creation. If funds run short mid-run, it stops and reports before making the next call rather than failing silently.

Operational queries from your IDE

With the server connected in Claude Code or Cursor, you can query your Afriex account without leaving your editor:

"What is the current NGN to USD rate?" → get_rates
"List my last 10 transactions and flag any that failed" → list_transactions
"Check my USD and GBP balances" → get_balance
"What is GTBank Nigeria's institution code?" → list_institutions
"Top up my sandbox NGN balance by 500,000" → topup_balance

FX rate monitoring agent

An agent that watches a currency pair and acts when a target rate is hit:

get_rates on a schedule for a specific corridor
Compare against a configured threshold
When the rate crosses, trigger create_transaction or surface an alert

Useful for businesses that time cross-border settlements against rate movements rather than executing at arbitrary times.

Sandbox and environment

Set x-afriex-environment to development for sandbox testing. The topup_balance tool funds your sandbox wallet with any currency and amount, so you can test the full tool chain, customer creation through transaction settlement, without touching live funds.

Switch to production in the header when ready to go live.

MCP versus the Afriex SDK

They are not alternatives — they serve different layers.

Use the SDK for production applications: deterministic code paths, typed inputs and outputs, full error handling control, and integration with your own data layer. The freelancer payout platform tutorial is a complete walkthrough of that approach.

Use the MCP server when an AI model is doing the orchestrating: agentic workflows, internal natural language tools, IDE queries during development, and rapid prototyping before you formalize an integration.

Most production setups use both, the SDK for core application logic, the MCP server for the agentic layer on top.

Full tool reference and setup docs at docs.afriex.com/mcp.

Accept USDC / USDT Without Running Your Own Wallet Infrastructure (Afriex API)

0xSonOfUri — Mon, 20 Apr 2026 12:08:15 +0000

Stablecoins are becoming core infrastructure for global payments.

But building with them usually means:

managing private keys
running indexers
tracking on-chain activity

That’s a lot of overhead.

In this guide, you’ll learn how to accept USDC / USDT without running your own custody infrastructure, using the Afriex API.

What You’ll Build

A backend endpoint that returns deposit instructions (address + network)
A webhook system to confirm payments reliably
A production-ready flow using idempotency and retries-safe logic

The Mental Model

Stop thinking:

“I need to manage wallets”

Start thinking:

“I’m building on payment rails”

With Afriex:

You don’t generate private keys
You don’t run blockchain infrastructure
You rely on Afriex for:
- deposit attribution
- transaction state
- settlement

Your job is to:

create a payment / invoice object
show deposit instructions
confirm payments via webhooks

Step 0 — Setup API Access

Base URLs

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

Environment Variables

AFRIEX_API_BASE_URL="https://api.afriex.com"
AFRIEX_API_KEY="your-api-key"
AFRIEX_WEBHOOK_PUBLIC_KEY="your-public-key"

Example Request

curl -sS -G "https://api.afriex.com/api/v1/org/balance" \
  -H "x-api-key: YOUR_AFRIEX_API_KEY"

Step 1 — Create Your Payment Object

Afriex does not create payment links for you.

You define your own invoice / payment intent:

{
  id: "internal_id",
  reference: "unique_reference",
  asset: "USDC",
  amount: 100,
  status: "pending",
  expiresAt: Date
}

Tip: Make reference globally unique and reuse it across retries.

Step 2 — Get Deposit Address

Endpoint

GET /api/v1/payment-method/crypto-wallet

Example

curl -sS -G "https://api.afriex.com/api/v1/payment-method/crypto-wallet" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "asset=USDC"

Response

{
  "data": [
    { "address": "0x...", "network": "ETHEREUM_MAINNET" },
    { "address": "TY...", "network": "TRON_MAINNET" }
  ]
}

Backend Example

const wallet = await fetch(url).then(res => res.json())

const preferred =
  wallet.data.find(w => w.network === "ETHEREUM_MAINNET") ??
  wallet.data[0]

return {
  address: preferred.address,
  network: preferred.network,
  asset: "USDC"
}

Important Note

This endpoint is:

Production only

It does not work in sandbox.

Step 3 — Display Payment Instructions

Your UI should show:

Asset (USDC / USDT)
Network
Address (copy + QR)

Also include:

Sending on the wrong network may result in lost funds

Step 4 — Confirm Payments (Webhooks)

This is the most important part.

Do NOT:

rely on user confirmation
rely on block explorers

Use Afriex webhooks.

Webhook Setup

Configure your webhook URL in the dashboard
Copy your webhook public key
Allowlist Afriex IPs

Signature Verification

import crypto from "crypto"

function verifySignature(signature, rawBody, publicKey) {
  const verifier = crypto.createVerify("RSA-SHA256")
  verifier.update(rawBody)
  return verifier.verify(publicKey, signature, "base64")
}

Important: verify the raw request body, not parsed JSON.

Events

TRANSACTION.CREATED
TRANSACTION.UPDATED

Logic

if (event === "TRANSACTION.UPDATED" && status === "SUCCESS") {
  markInvoiceAsPaid()
}

Ensure this operation is idempotent.

Step 5 — Idempotency

Outbound

Use:

{
  "meta": {
    "reference": "invoice_123",
    "idempotencyKey": "idem_invoice_123"
  }
}

Inbound

Webhooks may retry.

Ensure:

no duplicate credits
safe re-processing

Use database constraints or “update-if-not-paid” logic.

Step 6 — Reconciliation

Use Afriex APIs for support and debugging:

Get transaction
List transactions
Get balance

⚠️ Common Pitfalls

1. Crypto Wallet Not Working in Dev

→ It’s production only

2. Wrong Network Deposits

→ Only present one supported network

3. Webhook Verification Fails

→ Use raw body + correct public key

4. Duplicate Credits

→ Fix with idempotency

Why This Matters

Stablecoins are becoming:

Core rails for global payments

The real opportunity isn’t just using them.

It’s building systems on top of them.

Summary

With Afriex, you can:

Accept USDC / USDT
Avoid custody complexity
Use webhooks for reliable confirmation
Build production-ready payment systems

Final Thought

Afriex gives you the rails.

You build the product.

What the African Fintech Infrastructure Stack Looks Like in 2026

Victory Lucky — Fri, 17 Apr 2026 10:02:42 +0000

A decade ago, the African fintech story was about access. Could you give someone a mobile wallet? Get them into the formal system? Those were the right questions. Africa now accounts for roughly 74 percent of global mobile transaction volumes, processing over $1.1 trillion in 2024. The access problem is largely solved.

The question in 2026 is about plumbing. What does the underlying infrastructure actually look like, where are the layers, and where are the gaps? This matters because the infrastructure you build against determines what is actually possible.

Here is a ground-level look at each layer of the stack.

The payment rails layer

Three types of payment rails coexist in Africa, and understanding how they relate is the first thing any developer building in this space needs to internalize.

Mobile money networks are the dominant rail. M-Pesa processes over 61 million transactions daily and serves more than 50 million active users in Kenya alone. MTN Mobile Money, Airtel Money, and Orange Money cover large parts of West and Central Africa. In many markets, these are not supplements to banking — they are the primary financial infrastructure.

Domestic instant payment systems handle bank-to-bank flows within countries. Nigeria's NIBSS Instant Payments (NIP) is the largest, processing more real-time transactions than many systems in more developed economies. Kenya has Pesalink, South Africa has PayShap. Each handles intra-country clearing well. None connects natively to the others.

PAPSS — the Pan-African Payment and Settlement System — is the cross-border layer. Launched in January 2022 by the African Union and Afreximbank, PAPSS had expanded to 19 countries with over 150 commercial banks and 14 payment switches connected as of 2025. It enables real-time cross-border payments in local currencies, bypassing the dollar and euro intermediaries that have historically made intra-African trade expensive.

Two major products launched in 2025. In June, PAPSSCARD launched as Africa's first continental card scheme — a joint venture between Afreximbank, PAPSS, and Mercury Payment Services that keeps card processing fees, data, and value within the continent. In July, PAPSS and Interstellar launched the PAPSS African Currency Marketplace (PACM) for direct peer-to-peer exchange of African currencies without converting through a third currency. Over 80 corporates transacted across 12 currency pairs during the pilot. The target is eliminating an estimated $5 billion per year in cross-border transaction costs.

PAPSS has not yet closed the fragmentation between regional systems. EAPS and COMESA's REPSS have existed for years but struggle with limited liquidity. PAPSS's stated ambition is to act as a "network of networks" for continental net settlement — but that integration is still in progress.

There is also a blockchain layer emerging. Zone is Africa's first regulated blockchain payment network, licensed by the CBN. Its architecture routes transactions directly between institutions without a central intermediary. Zenith Bank, First Bank, and UBA joined the network in July 2024. By end of 2024, Zone had processed over ₦1 trillion in transactions. NIBSS subsequently joined as a regulatory node — the first time a major regulator has operated within a blockchain payment network at this scale.

The identity and KYC layer

Africa does not have a unified identity system. Nigeria has the BVN and NIN. Kenya has Huduma Namba. Ghana has the Ghana Card. These are nationally strong but do not connect across borders, which creates friction every time a service tries to onboard a user from another country.

A 2025 IMF report on digital payments in Sub-Saharan Africa found that as of 2021, only 65 percent of the region's population were enrolled in national identification systems, which was below other emerging market averages.

For developers, KYC is not a solved problem you can call one API for. Depending on which countries you are serving, you are either integrating with a national identity API where one exists, relying on document verification providers like Smile Identity or Youverify, or handling manual review for edge cases. The compliance burden scales non-linearly with each country you add.

Nigeria adds a hard constraint. The BVN and NIN are designated as Critical National Information Infrastructure under Nigeria's 2024 Designation Order, meaning data derived from them cannot be transferred outside Nigeria without specific NITDA approval. This is a constraint that must be resolved at the infrastructure level, not the application level.

The cross-border settlement layer

Only 12 percent of intra-African transactions are fully processed on the continent. The remaining 88 percent are routed through the US or Europe. Afreximbank's President Benedict Oramah has noted it is easier for a bank in an African country to finance trade with a European counterpart than with its neighbours.

This is the result of regulatory fragmentation, thin FX liquidity in many markets, and a correspondent banking system built around USD and EUR clearing. PAPSS, PAPSSCARD, and PACM are the formal responses. But two other forces are already reshaping settlement in ways the formal layer has not fully absorbed.

Stablecoins have moved from fringe to functional. Kenya ranks 5th globally for transactional stablecoin use. Nigeria received over $30 billion in DeFi value in 2024, making Sub-Saharan Africa the global leader in DeFi adoption. March 2025 alone saw $25 billion in on-chain volume in Nigeria driven by a currency devaluation window. Nigeria's Investment and Securities Act 2025 formally recognized digital assets as securities. South Africa had approved 248 crypto licenses by December 2024. Institutional flows are gradually shifting toward regulated stablecoins like USDC alongside USDT.

FX volatility is a core architectural constraint. Ola Oyetayo, CEO of Verto, described how Nigerian businesses now prioritize speed of settlement over rate optimization — the risk of being caught in a devaluation window during a slow settlement cycle often exceeds the cost of a slightly worse rate. Any payment infrastructure operating in these markets must be honest about settlement timing, not just the rate at the moment of quote.

The open banking and data layer

Nigeria and Kenya are the furthest along. BCG's 2026 fintech report identifies open banking reforms in both countries as the primary mechanism for expanding data portability and enabling data-driven credit infrastructure. The CBK has supported interoperability and risk-based KYC discussions. Nigeria's CBN is developing standardized APIs for licensed third-party account data access with user consent.

In practice today, open banking in Africa is market-specific. Mono covers Nigeria. Stitch covers Southern Africa. Continent-wide coverage does not yet exist as a stable surface to build against. The embedded finance market was valued at $11.9 billion in 2024 and is projected to reach $18 billion by 2030 — and a significant portion of that depends on open finance data rails maturing enough to support lending and insurance products priced against transaction history.

Data sovereignty remains a hard constraint in this layer. Nigeria's NDPA 2023 and NITDA's localisation guidelines mean transaction and identity data for Nigerian users cannot flow freely to infrastructure outside the country. Every architecture decision involving this data has a compliance dimension that has to be resolved upfront.

The compliance and RegTech layer

Fraud prevention has moved from a compliance checkbox to core infrastructure. Nikolai Barnwell, CEO of pawaPay, described 2025 as a year defined by regulatory and infrastructure maturity rather than headline innovation. In the same Techpoint Africa fintech leaders survey, Okpagu was direct: "If a fintech isn't investing in real-time, AI-led risk scoring that looks at the whole picture of a transaction, losses from sophisticated fraud will likely outpace growth."

Compliance-as-a-service is becoming its own infrastructure category. The trend is toward API-accessible KYC, AML screening, and sanctions checking that can be called at onboarding and transaction time — rather than each company building and maintaining these pipelines across multiple jurisdictions independently. Regulatory requirements update frequently and simultaneously across different markets. Maintaining this in-house is a significant ongoing engineering cost.

The deepest structural problem remains regulatory fragmentation. Licensing requirements for payment service providers differ by country. KYC standards are not harmonized. AML thresholds vary. Consonance Club's 2026 analysis notes the defining shift is toward compliance platforms precisely because the ecosystem spans 54 currencies and regulatory regimes.

The embedded finance layer

BCG projects African fintech revenues growing roughly 13x to approximately $65 billion by 2030, with embedded finance as a primary driver.

M-Pesa has expanded from P2P transfers into savings, investments, loans, BNPL, virtual cards, and insurance. MTN MoMo now spans payments, e-commerce, insurance, lending, and remittances. Moniepoint crossed unicorn status in October 2024 after its $110 million Series C and processes more than $22 billion in monthly transactions, having moved well beyond POS into full SME banking.

The B2B shift is the dominant investment thesis — away from consumer products and toward the rails other businesses build on. TechCabal's 2026 predictions document a 42 percent surge in expansions and a 72 percent spike in M&A in 2025, with Tier 1 market players acquiring competitors in neighbouring markets to build regional infrastructure positions rather than rebuilding from scratch. NALA's transformation from a consumer remittance app into Rafiki — a B2B payout infrastructure company — is the clearest example of where the sector is heading.

What this means if you are building on this stack

The stack has real depth. Mobile money coverage is extensive. Domestic instant payment systems work. PAPSS is expanding. Zone is proving a regulated blockchain payment layer is achievable. The identity and compliance layers are improving.

The gaps are equally real. 88 percent of intra-African transactions still route through foreign intermediaries. Identity infrastructure is nationally strong but not cross-border interoperable. Open banking APIs are market-specific. Regulatory requirements across 54 countries do not harmonize.

For a developer, your rails matter as much as your code. The payment API you choose determines which markets you can serve, how honest the rate information is, and whether the webhook events reflect how African payment networks actually behave — including IN_REVIEW holds, PROCESSING delays, and the difference between a FAILED and REJECTED status.

The Afriex Business API is built directly against this infrastructure reality. 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 market pairs. Webhooks cover every meaningful status transition in the African payment lifecycle. If you want to see how the full integration works end to end — KYC registration, payment method attachment, payout execution, and webhook handling — the freelancer payout platform tutorial walks through exactly that.

The stack is real. The gaps are known. Building on it well requires understanding both.

Why Most Payment APIs Fail Developers Building for African Markets

Victory Lucky — Wed, 15 Apr 2026 14:34:04 +0000

There is a version of this problem that does not get talked about enough. A developer somewhere in Lagos, Nairobi, or Accra opens the docs for a payment API they want to integrate. The quickstart looks clean. The sandbox spins up fast. The first test transaction goes through without a hitch. Three weeks later, they are deep in the actual integration and everything starts falling apart in ways the documentation did not warn them about.

This is not a capability problem. The infrastructure exists. Africa processed over $1.1 trillion in mobile money transactions in 2024, more than any other region in the world — a figure documented in the Payment APIs and Interoperability report on Africa's financial infrastructure. The rails are real. The problem is that most payment APIs were designed for a different developer, in a different market, and then shipped to everyone else with the expectation that it would just work.

It does not just work.

The documentation was written for a developer in San Francisco

This sounds harsh but it is just accurate. Open the getting started guide for most major payment APIs and you will find examples that create charges in USD, reference Stripe's ecosystem as a benchmark, and use webhook examples that assume a stable server with a static IP. The error codes are documented for card-based payments. The currency handling assumes floating-point precision does not matter much because dollar amounts are stable.

None of that maps to what you are actually building.

If you are building something that pays a contractor in Ghana via MTN Mobile Money, or routes a disbursement to a bank account in Kenya while your business collects in dollars, you will not find a worked example for that in most API docs. You will find a generic /transfers endpoint and a note that says "contact support for regional availability." That note is doing a lot of work.

A Finance in Africa analysis of the developer API ecosystem found that some providers still require extended approval processes or manual credentials before you can even access certain regional endpoints. Chipper Cash's Head of Payments, who is quoted in the same piece, also cited sandbox reliability and inadequate developer support as persistent gaps. You cannot prototype your way through a manual approval gate. So before you have written a line of production code, you are already blocked.

FX volatility is a runtime problem, not a business problem

Every developer building for markets like Nigeria has had to think about exchange rates in a way that developers in stable currency markets never do. Between mid-2023 and late 2024, the naira went from roughly N460 to the dollar to nearly N1,740 — Bloomberg ranked it the worst-performing currency in 2024 after a 70 percent drop in one year. By early 2026 it had stabilized somewhere in the N1,350 to N1,450 range, but analysts documented businesses reporting FX losses in the hundreds of billions of naira across the cement, FMCG, and brewing sectors during the peak volatility window.

That is not a footnote. That is a core architectural constraint.

The problem is that most payment API docs treat exchange rates as a lookup, not a liability. You call a rates endpoint, you get a number, you show it to your user. What they do not tell you is what happens between the moment your user confirms the amount and the moment the transaction settles. In volatile markets, that spread can be meaningful.

Ola Oyetayo, CEO of Nigerian fintech Verto, explained in a Techpoint Africa interview on FX uncertainty that when the naira moves 5 to 10 percent in a matter of days, providers widen their spreads as a defensive move — not out of opportunism, but because they need to account for the slippage between the moment a customer initiates a transfer and the moment it actually settles in the global market. During high-volatility windows, pricing updates can happen minute by minute. If the API you integrated does not expose that to you, your users will see one number and receive another, and they will blame your product, not the underlying rails.

A payment API built for this market surfaces rate information that is honest about timing, expiry, and settlement risk. Most do not.

NITDA and the compliance layer most docs skip

Here is the part that catches international developers building for Nigerian users completely off guard.

Nigeria's data regulatory landscape is layered. NITDA has mandated since 2019 that subscriber and consumer data be hosted within Nigeria. The Nigeria Data Protection Act 2023 (NDPA), which supersedes the earlier NDPR, requires that organisations processing data for more than 200 Nigerian residents within a six-month period register as Data Controllers or Processors of Major Importance. As Banwo and Ighodalo's analysis of Nigeria's data localisation regime explains, the CBN's 2020 guidelines on electronic payment channels further require that domestic transactions be routed through a local switch.

This means the payment API you integrated, which is running on AWS us-east-1 and stores your transaction logs in a US-based database, may be putting you in technical breach of Nigerian data localisation rules the moment you launch with Nigerian users. A 2025 peer-reviewed study of Nigerian fintech software developers published in the Multidisciplinary Journal of Engineering, Technology and Sciences found that while engineers were generally aware of NDPR and GDPR concepts, the hardest part was implementing compliance in actual coding and system design — partly because of a lack of clear compliance documentation and region-specific toolkits.

That gap is where most payment API providers leave you. The technical documentation tells you how to make an API call. It does not tell you whether that call, and the data it generates, is compliant with the regulatory environment of the markets you are serving.

The fragmentation is not an accident

Africa is not one market. It is 54 countries with 178 different mobile money services, different currencies, different regulatory environments, and different payment rails. A payment that settles in seconds in Kenya via M-Pesa uses entirely different infrastructure than a bank transfer in South Africa or a mobile money disbursement in Ghana.

Chipper Cash's Adeeyo, quoted in the Finance in Africa developer ecosystem analysis, said publicly that fragmentation remains a major challenge both technically and institutionally, and that regulatory inconsistency across countries makes regional scaling harder. That is coming from someone operating in this market full-time. For a developer integrating a payment API, that fragmentation shows up as undocumented behaviour: a call that works in sandbox for one country silently returns a different response structure in production for another, error messages that are not granular enough to tell you whether a failure was a network issue, a KYC issue, or an FX liquidity issue.

Benjamin Fernandes, founder of NALA, documented this in a detailed post on why payments in emerging markets are still 1 percent built. Between May 2023 and January 2024, NALA averaged 25 payment partner issues per month. Webhook callbacks that did not fire. Incorrect reconciliation. APIs that confirmed delivery when the money had not moved. These are not edge cases. These are the operational reality of building on payment infrastructure that was not designed with African markets as the primary concern.

What a payment API built for this market actually looks like

It surfaces real-time exchange rates with honest settlement windows, not just a number. It handles mobile money, bank accounts, SWIFT, and local payment methods as first-class channels, not afterthoughts. It documents its regulatory posture explicitly — where data is stored, how transfers are handled under Nigerian or Kenyan data law, what compliance burden it takes on versus what it leaves with you.

It also designs its error responses for the failure modes that actually happen in these markets: FX liquidity gaps, KYC tier limitations, mobile network outages that interrupt but do not fail a transaction. The Afriex Business API is built around exactly these constraints. The exchange rates endpoint exposes live rates for supported currency pairs including NGN, KES, GHS, and GBP. The payment methods layer handles bank accounts, mobile money (including MTN Mobile Money), SWIFT, UPI, and Interac as fully supported channels, not beta features. The webhooks are signed, retried with exponential backoff, and documented for every transaction status that matters, including IN_REVIEW for compliance holds that are a real operational scenario in African markets.

That is what it looks like when the API was designed with this market in mind from the start, not retrofitted after the fact.

If you are building something that moves money across African borders and the payment API you are using does not talk about FX settlement windows, does not document its compliance posture for Nigerian or Kenyan data law, and does not have mobile money as a first-class channel, you are not using the wrong feature. You are using the wrong tool.

Build a Freelancer Payout Platform with the Afriex SDK and Next.js

Victory Lucky — Sun, 12 Apr 2026 08:32:31 +0000

Paying contractors across borders means dealing with different banking rails, payment channels, and currencies simultaneously — and most existing tools either lock you into USD-first payouts or require a separate integration per country. This article walks through a freelancer payout platform that handles all of that through a single Afriex SDK integration.

The platform is built with Next.js, Drizzle ORM, TiDB Cloud, and Better Auth. You'll clone the repo, set up your environment, and then we'll break down how everything works including the architecture, the Afriex SDK integration, webhooks, and the data flow from UI to payout execution. If you want context on what else you can build with the Afriex API, the previous article in this series covers five use cases worth reading.

By the end you'll understand how to:

Register freelancers as Afriex customers
Attach bank accounts and mobile money wallets as payout destinations
Fetch live exchange rates and trigger cross-border payouts
Receive real-time status updates via webhooks
Send email notifications when payouts are initiated or completed

The full source is on GitHub. This article covers the architecture and the interesting parts — not every line of code.

Prerequisites

Node.js v22.14+
An Afriex Business account — create one here and grab your sandbox API key from Settings > API Keys
A TiDB Serverless cluster (the free tier is sufficient for this project)
A Resend account with an API key (this is for sending emails, you can skip if you want)

Architecture

The app uses a layered architecture. Every layer has one job:

Browser  →  Hook  →  Service  →  API Route  →  Repository (DB)
                                            →  DAL (Afriex SDK)

Layer	What it does
Hook	React Query wrapper — caching, loading states, cache invalidation
Service	Thin HTTP client — calls your own API routes
API Route	Validates input, calls the repository and DAL, returns JSON
Repository	Reads/writes your database through Drizzle
Data Access Layer (DAL)	Calls the Afriex SDK — the only layer that touches the external API

This separation matters because your database is your source of truth for UI state, while the Afriex API is your source of truth for payout execution. The API route coordinates both.

Project Setup

Clone the repo and install dependencies:

git clone https://github.com/codewithveek/afriex-payout-platform.git
cd afriex-payout-platform
pnpm install

Copy the example environment file and fill in your credentials:

cp .env.example .env.local

DATABASE_URL=mysql://user:pass@gateway.tidbcloud.com:4000/payout_platform?ssl={"rejectUnauthorized":true}
BETTER_AUTH_SECRET=your-random-secret
BETTER_AUTH_URL=http://localhost:3200
AFRIEX_API_KEY=your-sandbox-api-key
AFRIEX_ENVIRONMENT=staging
AFRIEX_WEBHOOK_PUBLIC_KEY=your-webhook-public-key
RESEND_API_KEY=your-resend-api-key
EMAIL_FROM=Payouts <noreply@yourdomain.com>

Run the database migration and start the dev server:

pnpm run db:migrate
pnpm dev

The rest of this article walks through how the codebase works — starting from the database layer up to the Afriex SDK integration and webhooks.

Database Layer

Connection

TiDB Cloud provides a MySQL-compatible serverless database. Connect it with Drizzle:

// src/db/index.ts
import { connect } from "@tidbcloud/serverless";
import { drizzle } from "drizzle-orm/tidb-serverless";
import * as schema from "./schema";

const client = connect({ url: process.env.DATABASE_URL! });
export const db = drizzle(client, { schema });

Schema

The application tables mirror the Afriex domain model. Each record stores the Afriex-assigned ID so you can call the SDK later:

// src/db/schema.ts (application tables only — Better Auth tables omitted for brevity)

export const customers = mysqlTable("customers", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexCustomerId: varchar("afriex_customer_id", { length: 255 })
    .notNull()
    .unique(),
  fullName: varchar("full_name", { length: 255 }).notNull(),
  email: varchar("email", { length: 255 }).notNull(),
  phone: varchar("phone", { length: 50 }).notNull(),
  countryCode: varchar("country_code", { length: 2 }).notNull(),
  createdByUserId: varchar("created_by_user_id", { length: 36 })
    .notNull()
    .references(() => users.id),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().onUpdateNow().notNull(),
});

export const paymentMethods = mysqlTable("payment_methods", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexPaymentMethodId: varchar("afriex_payment_method_id", { length: 255 })
    .notNull()
    .unique(),
  customerId: varchar("customer_id", { length: 36 })
    .notNull()
    .references(() => customers.id, { onDelete: "cascade" }),
  channel: varchar("channel", { length: 50 }).notNull(),
  accountName: varchar("account_name", { length: 255 }).notNull(),
  accountNumber: varchar("account_number", { length: 255 }).notNull(),
  countryCode: varchar("country_code", { length: 2 }).notNull(),
  institutionName: varchar("institution_name", { length: 255 }),
  // ...timestamps
});

export const transactions = mysqlTable("transactions", {
  id: varchar("id", { length: 36 }).primaryKey(),
  afriexTransactionId: varchar("afriex_transaction_id", { length: 255 })
    .notNull()
    .unique(),
  customerId: varchar("customer_id", { length: 36 })
    .notNull()
    .references(() => customers.id),
  paymentMethodId: varchar("payment_method_id", { length: 36 })
    .notNull()
    .references(() => paymentMethods.id),
  reference: varchar("reference", { length: 64 }).notNull().unique(),
  sourceCurrency: varchar("source_currency", { length: 3 }).notNull(),
  destinationCurrency: varchar("destination_currency", { length: 3 }).notNull(),
  destinationAmount: decimal("destination_amount", { precision: 18, scale: 2 }),
  status: varchar("status", { length: 50 }).default("PENDING").notNull(),
  createdByUserId: varchar("created_by_user_id", { length: 36 })
    .notNull()
    .references(() => users.id),
  // ...timestamps
});

The key column is afriexCustomerId (and its equivalents on the other tables). When the Afriex API creates a resource, it returns an ID. You store that ID in your database so every subsequent SDK call uses it. Your own id column is for your UI and internal joins.

Afriex SDK Integration

This is the core of the application. The SDK is initialized once and used across four Data Access Layer (DAL) files.

SDK Initialization

// 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 SDK handles authentication, retries, and webhook signature verification. The webhookPublicKey is needed later for verifying incoming webhook payloads.

DAL: Customers

Each DAL file wraps one SDK namespace. They return { data, error } so the API route can decide how to respond without try/catching everywhere:

// src/lib/dal/customers.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";

export async function createAfrexCustomer(input: CreateCustomerInput) {
  try {
    const customer = await afriex.customers.create(input);
    return { data: customer };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

DAL: Payment Methods

// src/lib/dal/payment-methods.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";
import type { CreatePaymentMethodInput } from "@/lib/schemas/payment-method.schema";

export async function createAfrexPaymentMethod(
  input: CreatePaymentMethodInput,
  afriexCustomerId: string
) {
  try {
    const pm = await afriex.paymentMethods.create({
      customerId: afriexCustomerId,
      channel: input.channel,
      accountName: input.accountName,
      accountNumber: input.accountNumber,
      countryCode: input.countryCode,
      institution: {
        institutionCode: input.institutionCode,
        institutionName: input.institutionName ?? input.institutionCode,
      },
    });
    return { data: pm };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

DAL: Transactions (Payouts)

This is where payouts actually happen. The SDK's transactions.create call with type: "WITHDRAW" sends money to the freelancer's payment method:

// src/lib/dal/transactions.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError, generateIdempotencyKey } from "@/lib/utils";

export async function createAfriexTransaction(params: {
  afriexCustomerId: string;
  afriexPaymentMethodId: string;
  destinationAmount: number;
  sourceCurrency: string;
  destinationCurrency: string;
  reference: string;
}) {
  try {
    const idempotencyKey = generateIdempotencyKey(params.reference);

    const tx = await afriex.transactions.create({
      type: "WITHDRAW",
      customerId: params.afriexCustomerId,
      destinationId: params.afriexPaymentMethodId,
      sourceAmount: `${params.destinationAmount}`,
      destinationAmount: `${params.destinationAmount}`,
      sourceCurrency: params.sourceCurrency,
      destinationCurrency: params.destinationCurrency,
      meta: {
        merchantId: params.reference,
        idempotencyKey,
        narration: `Payout — ${params.reference}`,
        reference: params.reference,
      },
    });

    return { data: tx };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

The idempotencyKey ensures that if a network error causes a retry, Afriex won't create a duplicate transaction. It's derived from the reference string so the same reference always produces the same key:

// src/lib/utils/index.ts
export function generateIdempotencyKey(seed?: string): string {
  if (seed) return `idem-${seed}`;
  return `idem-${crypto.randomUUID()}`;
}

DAL: Exchange Rates

Before sending a payout, you may want to see the current exchange rate:

// src/lib/dal/rates.dal.ts
import { afriex } from "@/lib/afriex";
import { formatApiError } from "@/lib/utils";

export async function getAfrexRate(from: string, to: string) {
  try {
    const result = await afriex.rates.getRates({
      fromSymbols: from,
      toSymbols: to,
    });
    const rate = result?.rates?.[from]?.[to];
    if (!rate) return { error: `Rate for ${from}/${to} not available` };
    return { data: { from, to, rate: parseFloat(rate) } };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

export async function convertAfrexCurrency(
  amount: number,
  from: string,
  to: string
) {
  try {
    const convertedAmount = await afriex.rates.convert(amount, from, to);
    const rateResult = await getAfrexRate(from, to);
    return {
      data: {
        from,
        to,
        rate: rateResult.data?.rate ?? 0,
        amount,
        convertedAmount,
      },
    };
  } catch (error) {
    return { error: formatApiError(error) };
  }
}

API Routes

API routes coordinate validation, database writes, and SDK calls. Here's the transaction (payout) route — the most complex one — to show the pattern:

// src/app/api/transactions/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createTransactionSchema } from "@/lib/schemas/transaction.schema";
import { createAfriexTransaction } from "@/lib/dal/transactions.dal";
import { insertTransaction } from "@/repositories/transaction.repository";
import { findCustomerById } from "@/repositories/customer.repository";
import { findPaymentMethodsByCustomer } from "@/repositories/payment-method.repository";
import { sendPayoutInitiatedEmail } from "@/lib/email";
import { getRequiredSession } from "@/lib/utils/auth";

export async function POST(req: NextRequest) {
  const session = await getRequiredSession();
  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const body = await req.json();
  const result = createTransactionSchema.safeParse(body);
  if (!result.success) {
    return NextResponse.json(
      { error: result.error.flatten().fieldErrors },
      { status: 400 }
    );
  }

  // 1. Look up the customer in the database to get their Afriex IDs
  const customer = await findCustomerById(result.data.customerId);
  if (!customer) {
    return NextResponse.json({ error: "Customer not found" }, { status: 404 });
  }

  const paymentMethods = await findPaymentMethodsByCustomer(customer.id);
  const paymentMethod = paymentMethods.find(
    (pm) => pm.id === result.data.paymentMethodId
  );
  if (!paymentMethod) {
    return NextResponse.json(
      { error: "Payment method not found" },
      { status: 404 }
    );
  }

  // 2. Create the payout in Afriex
  const afriexResult = await createAfriexTransaction({
    afriexCustomerId: customer.afriexCustomerId,
    afriexPaymentMethodId: paymentMethod.afriexPaymentMethodId,
    destinationAmount: result.data.destinationAmount,
    sourceCurrency: result.data.sourceCurrency,
    destinationCurrency: result.data.destinationCurrency,
    reference: result.data.reference,
  });

  if (afriexResult.error) {
    return NextResponse.json({ error: afriexResult.error }, { status: 502 });
  }

  // 3. Persist the transaction to the database
  const transaction = await insertTransaction({
    afriexTransactionId: afriexResult.data!.transactionId,
    customerId: customer.id,
    paymentMethodId: paymentMethod.id,
    reference: result.data.reference,
    sourceCurrency: result.data.sourceCurrency,
    destinationCurrency: result.data.destinationCurrency,
    destinationAmount: result.data.destinationAmount.toString(),
    createdByUserId: session.user.id,
  });

  // 4. Send a notification email
  await sendPayoutInitiatedEmail({
    to: session.user.email,
    freelancerName: customer.fullName,
    amount: result.data.destinationAmount.toString(),
    currency: result.data.destinationCurrency,
    reference: result.data.reference,
    transactionId: afriexResult.data!.transactionId,
  });

  return NextResponse.json({ data: transaction }, { status: 201 });
}

The pattern is always the same:

Authenticate — getRequiredSession()
Validate — Zod schema
Resolve — look up records in the database to get Afriex IDs
Call Afriex — through the DAL
Persist — save to your database
Side effects — email, logging, etc.

The customer and payment method routes follow this exact pattern. See src/app/api/customers/route.ts and src/app/api/payment-methods/route.ts in the repo.

Webhooks

Webhooks are how Afriex tells you what happened to a payout after you created it. A transaction's status moves through PENDING → PROCESSING → COMPLETED (or FAILED), and Afriex sends a signed HTTP POST for each transition.

The SDK provides a verifyAndParse method that checks the webhook signature and returns the parsed payload:

// src/app/api/webhooks/route.ts
import { NextRequest, NextResponse } from "next/server";
import { afriex } from "@/lib/afriex";
import {
  updateTransactionStatus,
  findTransactionForEmail,
} from "@/repositories/transaction.repository";
import { sendPayoutStatusEmail } from "@/lib/email";
import { WebhookPayload } from "@afriex/sdk";

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

  // 1. Verify the signature and parse the payload
  const rawBody = await req.text();
  let webhookPayload: WebhookPayload;
  try {
    webhookPayload = afriex.webhooks.verifyAndParse(rawBody, signature);
  } catch {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const eventType = webhookPayload.event;
  // 2. Handle transaction status updates
  if (
    eventType === "TRANSACTION.UPDATED" ||
    eventType === "TRANSACTION.CREATED"
  ) {
    const { transactionId, status } = event.data as {
      transactionId: string;
      status: string;
    };

    await updateTransactionStatus(transactionId, status);

    // Send email on terminal statuses
    const terminalStatuses = ["COMPLETED", "SUCCESS", "FAILED", "REJECTED"];
    if (terminalStatuses.includes(status)) {
      const tx = await findTransactionForEmail(transactionId);
      if (tx) {
        await sendPayoutStatusEmail({
          to: tx.userEmail,
          freelancerName: tx.customerName,
          amount: tx.destinationAmount,
          currency: tx.destinationCurrency,
          reference: tx.reference,
          status,
        });
      }
    }
  }

  // 3. Handle customer and payment method sync events
  if (eventType === "CUSTOMER.UPDATED") {
    // Sync name/email changes back to the DB
  }
  if (eventType === "CUSTOMER.DELETED") {
    // Remove from the DB
  }
  if (eventType === "PAYMENT_METHOD.DELETED") {
    // Remove from the DB
  }

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

Three things to note:

Raw body — you must read req.text(), not req.json(). The SDK verifies the signature against the raw string. Parsing first would change the byte representation.
Terminal statuses — only send a "payout completed/failed" email on final statuses. Intermediate statuses like PROCESSING are handled silently.
Customer/Payment Method sync — Afriex can update or delete these resources from its side. The webhook handler keeps your DB in sync.

To test webhooks locally, expose your dev server with ngrok:

npx ngrok http 3200

Copy the HTTPS URL + /api/webhooks into your Afriex dashboard under Developers > Webhooks. Paste the public key into .env.local as AFRIEX_WEBHOOK_PUBLIC_KEY.

Client Layer

The client layer follows a three-step chain: Hook → Service → API route. Each step does one thing.

Service (HTTP Client)

A thin wrapper around fetch that extracts .data from responses and throws on errors:

// src/services/api-client.ts
async function request<T>(
  method: string,
  url: string,
  body?: unknown
): Promise<T> {
  const res = await fetch(url, {
    method,
    headers: { "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) {
    throw new Error(
      typeof json.error === "string" ? json.error : "Request failed"
    );
  }
  return json.data as T;
}

export const http = {
  get: <T>(url: string) => request<T>("GET", url),
  post: <T>(url: string, body: unknown) => request<T>("POST", url, body),
  patch: <T>(url: string, body: unknown) => request<T>("PATCH", url, body),
  delete: <T>(url: string) => request<T>("DELETE", url),
};

Service Files

Each resource gets a service file that maps CRUD operations to API routes:

// src/services/customer.api.ts
import { http } from "./api-client";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";
import type { Customer } from "@/db/schema";

export const customerApi = {
  create: (data: CreateCustomerInput) =>
    http.post<Customer>("/api/customers", data),
  list: () => http.get<Customer[]>("/api/customers"),
  get: (id: string) => http.get<CustomerDetail>(`/api/customers/${id}`),
  delete: (id: string) => http.delete<void>(`/api/customers/${id}`),
};

The payment method, transaction, and rates services follow the same shape. See src/services/ in the repo.

Hooks (React Query)

Hooks wrap services with TanStack Query for caching, loading states, and cache invalidation:

// src/hooks/useCustomer.ts
"use client";

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { customerApi } from "@/services/customer.api";
import type { CreateCustomerInput } from "@/lib/schemas/customer.schema";

export function useCustomers() {
  return useQuery({
    queryKey: ["customers"],
    queryFn: () => customerApi.list(),
  });
}

export function useCreateCustomer() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: CreateCustomerInput) => customerApi.create(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["customers"] });
    },
  });
}

The onSuccess callback invalidates the query cache so the customer list refreshes automatically after a creation. Every mutation hook follows this pattern.

Authentication

The app uses Better Auth for email/password authentication. Setup involves three files:

Server — src/lib/auth.ts: Initializes Better Auth with the Drizzle adapter, pointing at the auth tables in your schema.

Client — src/lib/auth-client.ts: Exports signIn, signUp, signOut, and useSession for use in React components.

Middleware — src/proxy.ts: Redirects unauthenticated users away from /dashboard/* routes.

// src/proxy.ts
import { getSessionCookie } from "better-auth/cookies";
import { NextRequest, NextResponse } from "next/server";

export async function proxy(request: NextRequest) {
  const sessionCookie = getSessionCookie(request);
  if (!sessionCookie) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }
  return NextResponse.next();
}

export const config = { matcher: ["/dashboard/:path*"] };

Full auth setup including the sign-in/sign-up pages is in the repo.

Email Notifications

Payout notifications use Resend with React Email templates. Two emails are sent during a payout lifecycle:

Payout initiated — sent immediately after creating the transaction
Payout completed/failed — sent when the webhook receives a terminal status

// src/lib/email.ts
import { Resend } from "resend";
import { PayoutInitiated } from "@/emails/PayoutInitiated";
import { PayoutCompleted } from "@/emails/PayoutCompleted";

const resend = new Resend(process.env.RESEND_API_KEY!);
const FROM = process.env.EMAIL_FROM ?? "Payouts <noreply@example.com>";

export async function sendPayoutInitiatedEmail(params: {
  to: string;
  freelancerName: string;
  amount: string;
  currency: string;
  reference: string;
  transactionId: string;
}) {
  const { error } = await resend.emails.send({
    from: FROM,
    to: params.to,
    subject: `Payout initiated — ${params.reference}`,
    react: PayoutInitiated(params),
  });

  if (error) {
    console.error("[email] sendPayoutInitiatedEmail failed:", error);
  }
}

Note that email failures are logged but not thrown. A failed email should never block a successful payout.

The React Email templates are straightforward HTML-in-JSX. See src/emails/ for both templates.

Validation Schemas

All input validation uses Zod. The schemas are shared between the API route (server-side validation) and the form (client-side validation via @hookform/resolvers):

// src/lib/schemas/customer.schema.ts
import { z } from "zod";

export const createCustomerSchema = z.object({
  fullName: z.string().min(2).max(100),
  email: z.string().email(),
  phone: z
    .string()
    .regex(
      /^\+[1-9]\d{1,14}$/,
      "Phone must contain country code e.g. +2348012345678"
    ),
  countryCode: z.string().length(2),
});

export type CreateCustomerInput = z.infer<typeof createCustomerSchema>;

// src/lib/schemas/transaction.schema.ts
import { z } from "zod";

export const createTransactionSchema = z.object({
  customerId: z.string().min(1),
  paymentMethodId: z.string().min(1),
  destinationAmount: z.number().positive(),
  sourceCurrency: z.string().length(3),
  destinationCurrency: z.string().length(3),
  reference: z.string().min(1).max(64),
});

export type CreateTransactionInput = z.infer<typeof createTransactionSchema>;

The payment method schema is in the repo.

Repositories

Repositories handle all database reads and writes. They never call the Afriex SDK — that's the DAL's job. Here's the customer repository to show the pattern:

// src/repositories/customer.repository.ts
import { db } from "@/db";
import { customers } from "@/db/schema";
import { eq } from "drizzle-orm";
import { randomUUID } from "crypto";

export async function insertCustomer(data: {
  afriexCustomerId: string;
  fullName: string;
  email: string;
  phone: string;
  countryCode: string;
  createdByUserId: string;
}) {
  const id = randomUUID();
  await db.insert(customers).values({ id, ...data });

  const [customer] = await db
    .select()
    .from(customers)
    .where(eq(customers.id, id))
    .limit(1);

  return customer;
}

export async function findCustomersByUser(userId: string) {
  return db
    .select()
    .from(customers)
    .where(eq(customers.createdByUserId, userId));
}

export async function findCustomerById(id: string) {
  const [customer] = await db
    .select()
    .from(customers)
    .where(eq(customers.id, id))
    .limit(1);
  return customer ?? null;
}

The transaction and payment method repositories follow the same CRUD pattern. See src/repositories/.

The Dashboard

The UI consists of a sidebar shell, an overview page with metric cards and a transactions table, and a modal for the new payout flow. The modal consists of three steps: register a freelancer → attach a payment method → send the payout.

All form components use React Hook Form with the Zod schemas defined above, and the mutation hooks from the hooks layer. There's no direct fetch or useState for loading in any form — React Query handles all of that.

The full UI code is in the repo:

Dashboard layout + sidebar
Form components
Dashboard components (MetricCard, TransactionsTable, NewPayoutDrawer)

Deploying

vercel

Add your environment variables in Project > Settings > Environment Variables. Use production credentials for both Afriex and TiDB Cloud.

Update your Afriex webhook URL to the Vercel deployment URL (https://your-app.vercel.app/api/webhooks) and copy the webhook public key.

Wrapping Up

The architecture pattern in this article: your database owns the UI state, the Afriex SDK owns the payout execution, and the API route coordinates both — that's the key takeaway regardless of what you build on top of it.
It keeps each layer testable and replaceable, and it means that when Afriex adds a new payment channel or webhook event, you know exactly which file to touch.

The full project is on GitHub. The next article in this series covers the international payroll system — same architecture, significantly higher compliance requirements. If you have questions in the meantime, drop them in the comments or reach out on X @codewithveek.

Getting Started with the Afriex API: From Signup to Your First Request

0xSonOfUri — Tue, 07 Apr 2026 12:00:48 +0000

What if you could start building global payment systems in minutes?

Before you can build payment links, payouts, or crypto flows — you need access to the Afriex API.

This guide walks you through going from zero → your first API call.

What You’ll Do

By the end of this guide, you’ll:

Create an Afriex Business account
Complete onboarding and verification
Generate your API key
Make your first API request

Step 1: Create an Afriex Business Account

Head to:

https://business.afriex.com/

Step 2: Select Entity Type

Choose the entity that applies to you:

Sole Trader / Sole Proprietorship → if you're an individual
Registered Company / Corporate → if you're a company

This determines the documents required during verification.

Step 3: Set Up Your Business

Fill in your details:

Phone number
Full name
Business name
Country of residence
Password

Step 4: Complete Verification

To unlock full API access, you’ll go through verification:

Provide company details
Upload documents
Add associated parties
Complete phone verification

This is required for compliance and security.

Step 5: Set Up Your Team (Optional)

From the dashboard, you can:

Add team members
Assign roles
Manage permissions

Useful if you're building with others.

Step 6: Generate Your API Key

Once your account is ready:

Go to Settings → API Keys
Generate a new key
Store it securely

Never expose your API key in frontend code or public repositories.

Step 7: Make Your First API Call

Now let’s test the API.

Create a Customer

curl -X POST https://sandbox.api.afriex.com/api/v1/customer \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  }'

Expected Response

{
  "data": {
    "customerId": "69516dd0464b2213bd74cfad",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+2348192837465",
    "countryCode": "NG"
  }
}

Step 8: Process Your First Transaction

Once you have a customer, you can initiate a transaction:

curl -X POST https://sandbox.api.afriex.com/api/v1/transaction \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "CUSTOMER_ID",
    "type": "WITHDRAW",
    "sourceAmount": "10",
    "destinationAmount": 5000,
    "sourceCurrency": "USD",
    "destinationCurrency": "NGN",
    "destinationId": "PAYMENT_METHOD_ID"
  }'

Important Notes

Use the sandbox environment for testing
Switch to https://api.afriex.com for production
Keep your API key secure
Always make API calls from your backend

Explore the Docs

https://docs.afriex.com/

You can also fetch the full index here:
https://docs.afriex.com/llms.txt

What Next?

Now that you have access, you can start building:

Payment links
Cross-border payouts
Crypto integrations
Multi-currency systems

Next guide: Send a Link, Get Paid: Building Payment Links with the Afriex API

Final Thought

Afriex gives you the rails.

You just made your first step into building on top of them.

5 Products You Can Build with Afriex Cross-Border Payment API

Victory Lucky — Thu, 02 Apr 2026 02:09:31 +0000

Sending money across borders is still unnecessarily hard. Between fragmented banking rails, FX volatility, compliance overhead, and the constant managing of different payment channels per country, most businesses just give up and build the bare minimum. The Afriex cross-border payment API was built to abstract most of that complexity for you.

What you get is an international payout platform API which supports customer management with KYC integration, multi-channel payment methods (bank accounts, mobile money, SWIFT, UPI, Interac, WeChat Pay, and crypto wallets), a real-time FX rate API, deposits, withdrawals, and webhook-based event notifications — all in one integration. That is a wide enough surface to build serious products on top of.

Here are five products worth building on top of it.

1. A Cross-Border Freelancer Payout Platform

The problem it solves

A freelancer in Kenya finishing a project for a client in the UK still has to go through a painful process to get paid — wire transfers with high fees, days-long settlement times, or stablecoin workarounds that require crypto literacy. Platforms that manage remote teams and contractors across multiple countries deal with this at scale, and it is one of the most common reasons contractor retention drops. What most of these platforms are really missing is a solid contractor payment API underneath them.

How the Afriex API makes this work

The core flow is straightforward. When a freelancer signs up, you register them as a customer via the Create Customer endpoint, pass optional KYC details through the same request, and attach their preferred payment method. The built-in KYC integration means you are not stitching together a separate identity verification layer, it is part of the same customer object. The API supports bank accounts across supported markets in West Africa and Southern Africa, plus SWIFT for international bank transfers, mobile money (MTN and others in Ghana, for example), and even UPI for Indian recipients. You store the resulting paymentMethodId against their profile in your system.

When a client approves a project and triggers a payout, you call the Create Transaction endpoint with type: WITHDRAW, pass the freelancer's customerId and their destinationId (the stored payment method), specify the source and destination currencies, and the transfer goes through. Webhook events on transaction.completed or transaction.failed let you update the freelancer's dashboard in real time without polling.

Before processing, you can pull live rates from the Exchange Rates endpoint to show the freelancer exactly what they will receive before they confirm — no surprises at settlement.

Why it is a business

Platforms like this typically charge a percentage fee on every payout or mark up the exchange rate slightly. With the Afriex rates endpoint giving you real-time FX data, you have full visibility into your margin on every transaction.

2. A Global Creator Monetization Tool

The problem it solves

Content creators, newsletter writers, indie game developers, and digital artists increasingly have international audiences. Most monetization tools (Patreon, Gumroad, etc.) are built for USD-first payouts and do very little for a creator in Ghana trying to collect revenue from subscribers in the US, Germany, and Canada simultaneously, then cash out to a local mobile money wallet.

How the Afriex API makes this work

You build a lightweight "creator wallet" product. Each creator gets onboarded as a customer in your system via the Afriex API. When a subscriber makes a payment (through whatever checkout you have on your platform), you deposit into the creator's account balance. When the creator wants to cash out, they choose their preferred withdrawal method, which could be bank account, mobile money, or SWIFT, and you trigger a withdrawal transaction to the saved payment method.

The multi-channel nature of the payment methods endpoint is what makes this particularly powerful here. The same codebase handles a creator in South Africa withdrawing to a local bank account, a creator in Uganda withdrawing via mobile money, and a creator in India withdrawing via UPI. You are not building separate integrations per country, just one payment method creation flow, different channel values.

The crypto wallet support (USDT and USDC on Ethereum Mainnet and other supported networks) also opens up a path for creators who want stablecoin payouts, USDC payout in particular is a real preference in markets where local currency volatility makes holding fiat unattractive.

Why it is a business

Creator tools monetize on platform fees, subscription tiers for advanced analytics, or a small percentage on each payout. The fact that you can serve creators across Africa, India, the UK, and North America without per-country integrations is what makes the unit economics work at smaller scale.

3. An International Payroll Tool for Remote-First Companies

The problem it solves

Running remote team payroll is one of the more painful operational problems a company can have. Most existing global payroll API tools handle local compliance well but fall apart when a company has employees or contractors across multiple African countries, Southeast Asia, and Europe at the same time. The alternative is using a mix of different providers per region, which creates reconciliation nightmares.

How the Afriex API makes this work

You build a payroll orchestration layer on top of the Afriex API. HR admins define salary amounts and payment schedules. Employees register their payout preferences (bank account, mobile money, SWIFT). On payroll run day, your system iterates over the payroll records, calls the Create Transaction endpoint for each employee with the appropriate currencies, and fires them off. The meta field on the transaction lets you attach a reference (e.g. payroll-2026-04-employee-123) and an idempotency key, which is important for payroll as you do not want double-pays if a request is retried.

Webhook events handle the status updates. When a transaction completes or fails, the webhook fires and your system updates the payroll run record accordingly. Failed transactions can be flagged for manual review or automatic retry.

The balance endpoint lets you monitor your funding account in real time so payroll runs do not fail mid-flight because of insufficient balance, additionally you can build alerts that notify finance teams when the account drops below a threshold.

Why it is a business

This puts you in direct competition with tools like Deel or Remote in the contractor management and remote team payroll space, but built for companies with significant headcount in African and South/Southeast Asian markets specifically. The fact that the underlying contractor payment API handles mobile money, SWIFT, and bank accounts in the same integration is the differentiator. Pricing models here are typically per-employee per-month or a percentage of total payroll processed.

4. An FX Rate Tracker and Currency Conversion App

The problem it solves

Businesses that deal with cross-border transactions — importers, exporters, procurement teams, and travel agencies — need to monitor exchange rates across multiple currency pairs and make decisions based on them. Most FX rate API tools either cover major global pairs (USD/EUR/GBP) and largely ignore African currencies, or they provide rates that are not close to what you actually get when you execute a transaction.

How the Afriex API makes this work

The Exchange Rates endpoint returns real-time rates for supported currency pairs, see the example in the documentation which shows pairs including NGN, KES, GBP, EUR, CAD, and USD. You can filter to specific fromSymbols and toSymbols to only fetch the pairs your users care about.

Build a simple dashboard that polls this endpoint on a schedule, stores the historical data on your end, and surfaces rate trends over time. You can also include alerts so users get notified when a target rate is hit (e.g. "notify me when USD to NGN crosses 1500"). You could also add a conversion calculator that uses live rates, and if you connect this to an actual transaction execution flow, users can set rate targets and trigger a real transfer through the Afriex transactions API when the rate moves in their favour.

This is also a natural product to embed inside a larger B2B tool. An invoicing platform serving import/export businesses could surface live FX rates inline so clients can see the landed cost of an invoice before paying.

Why it is a business

Standalone FX tools monetize through premium alert tiers, API access for other developers, and affiliate or spread arrangements if they also execute transactions. The embedded version monetizes as a feature that justifies a higher tier of a broader product.

5. A Regional E-Commerce Checkout and Settlement Layer

The problem it solves

A merchant selling physical or digital products to customers across multiple African countries and the diaspora (UK, US, Canada) faces a fragmentation problem at checkout. Local customers in Ghana want to pay by mobile money. Customers in South Africa want bank transfers. The diaspora wants to pay in USD or GBP. Most off-the-shelf checkout tools force the merchant to either limit their market or manage multiple payment processors with separate dashboards and settlement cycles.

How the Afriex API makes this work

You build a unified checkout abstraction. When a customer initiates a purchase, your checkout flow creates them as an Afriex customer (or retrieves the existing record) and presents payment options based on their country. The supported channels in the payment method API include BANK_ACCOUNT, MOBILE_MONEY, SWIFT, INTERAC, UPI, and WE_CHAT, which then map neatly to the dominant payment preferences in each supported market.

For merchants who want to collect payments (rather than just disburse them), the virtual account API endpoint lets you provision a dedicated virtual bank account per customer or per transaction for supported currencies (USD, NGN, GBP, EUR). The customer pays into the virtual account, the deposit is detected, and your system triggers the order fulfillment flow via a webhook event.

For the merchant's settlement, you use the withdrawal flow to move funds to wherever they need them which could be local bank account, SWIFT, or a stablecoin payout to a USDT or USDC wallet if they prefer to hold in stable assets.

Why it is a business

Payment infrastructure products typically take a percentage of GMV, charge fixed fees per transaction, or both. The differentiation here is the breadth of payment methods in a single integration, which lets merchants who previously needed two or three different processors consolidate into one.

Getting Started

Everything you need to get started is in the Afriex Business API documentation. If you are building in TypeScript or JavaScript, there is also an official SDK that gives you full type definitions, built-in retry logic, and a clean interface over the REST API. You can create a business account here, and start building with the API in sandbox in a few minutes, then switch to production environment when you're ready.

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

const afriex = new AfriexSDK({
  apiKey: "YOUR_API_KEY",
  environment: "staging", // switch to 'production' when ready
});

Regardless of which product you are building, whether it's a freelancer payout platform, a remote team payroll tool, or a virtual account API integration, you are working with the same four core resources: Customers, Payment Methods, Transactions, and Webhooks. The use case changes; the primitives stay the same.

In the next article in this series we will walk through building the freelancer payout platform end to end, from customer onboarding and KYC to real-time transaction status on a dashboard. Keep an eye out for it.

Have any questions or need assistance with the API integration? Drop them in the comments or reach out to me on X @codewithveek and I will be glad to help.

Send a Link, Get Paid: Building Payment Links with Afriex

0xSonOfUri — Mon, 30 Mar 2026 17:45:56 +0000

Send a Link, Get Paid: Building Payment Links with the Afriex API

What if you could accept payments globally with just a link?

No checkout flows. No heavy integrations. Just a URL.

What This Guide Covers

This guide is about the Afriex API.

You’ll learn how to build a simple payment link system that allows you to:

Generate shareable payment links
Accept payments via bank transfer or crypto
Track payment status
Handle real payment confirmations

You do not need any specific framework. Your backend just needs to make secure HTTPS requests.

Afriex vs Your Application

Afriex provides the payment infrastructure.

You build the product layer.

Responsibility	Who
Virtual accounts, crypto wallets, settlement rails	Afriex
Payment link (URL), amount, expiry, status tracking	Your App
Confirming payments securely	Afriex Webhooks

System Architecture

Client → Backend → Afriex API → Payment Rails

Your backend stores payment requests
Afriex handles payment execution
Your frontend displays payment instructions

Prerequisites

Before starting, you need:

An Afriex account
Your API key
A customerId (Afriex identifier for the recipient)

Every payment instruction you generate should be tied to a customerId.

Authentication

All Afriex API calls are made server-side.

GET {BASE_URL}/... HTTP/1.1
x-api-key: YOUR_AFRIEX_API_KEY
Content-Type: application/json

Example:

curl -sS -G "{BASE_URL}/api/v1/payment-method/virtual-account" \
  -H "x-api-key: YOUR_AFRIEX_API_KEY" \
  --data-urlencode "currency=NGN" \
  --data-urlencode "amount=5000" \
  --data-urlencode "customerId=PAYEE_CUSTOMER_ID"

Step 1: Create a Payment Link (Your Backend)

Afriex does not create “payment links” for you — you implement this.

Store:

amount
currency
description
expiry
customerId
unique token

import crypto from "crypto";

const linkId = crypto.randomBytes(16).toString("hex");

await db.payment.create({
  linkId,
  amount: 5000,
  currency: "NGN",
  customerId,
  expiresAt: new Date(Date.now() + 30 * 60 * 1000),
});

Then generate:

https://yourapp.com/pay/{linkId}

Step 2: Generate Payment Instructions

When a user opens the link:

Load the payment request
Call Afriex
Return instructions

🇳🇬 Virtual Account (Bank Transfer)

curl -sS -G "{BASE_URL}/api/v1/payment-method/virtual-account" \
  -H "x-api-key: YOUR_AFRIEX_API_KEY" \
  --data-urlencode "currency=NGN" \
  --data-urlencode "amount=5000" \
  --data-urlencode "customerId=PAYEE_CUSTOMER_ID"

Display:

Account number
Account name
Bank name

Crypto Wallet (USDC / USDT)

curl -sS -G "{BASE_URL}/api/v1/payment-method/crypto-wallet" \
  -H "x-api-key: YOUR_AFRIEX_API_KEY" \
  --data-urlencode "asset=USDC" \
  --data-urlencode "customerId=PAYEE_CUSTOMER_ID"

Response:

{
  "data": [
    {
      "address": "0x...",
      "network": "ethereum"
    }
  ]
}

If USDC is unavailable, fallback to USDT.

Step 3: Choosing Payment Method

In your backend:

If currency = NGN → virtual account
If currency = USD → crypto wallet

This logic is controlled by your application, not Afriex.

Step 4: Confirm Payment (Production)

Do NOT rely on:

Button clicks
User confirmation

Use Afriex webhooks:

Receive event
Verify signature
Match to payment record
Mark as paid

Always handle this idempotently.

Security Checklist

Keep API keys server-side only
Use HTTPS
Use unguessable link tokens
Expire links
Verify webhooks

Why This Pattern Matters

This is the same pattern used by:

Stripe
Paystack
Flutterwave

Payment links are one of the fastest ways to start accepting payments globally.

Summary

To build payment links with Afriex:

Create a customer → get customerId
Store a payment request in your database
Generate a shareable link
Fetch payment instructions via Afriex
Confirm payments via webhooks

Next Steps

Add webhook automation
Support more currencies
Build dashboards
Add notifications

Final Note

Afriex gives you the rails.

You build the product.