Forem: Afriex

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.