DEV Community: Victory Lucky

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

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

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

This part fixes that, in both directions:

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

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

What you'll have at the end

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

Before you start

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

Let's look at the whole flow first

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

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

Let's create the checkout session

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

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

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

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

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

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

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

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

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

Three details to slow down on:

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

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

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

One webhook, two writes

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

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

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

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

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

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

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

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

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

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

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

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

Sale → earning → balance

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

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

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

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

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

  return earning;
}

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

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

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

Onboarding Amara for payout

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

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

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

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

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

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

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

Requesting and disbursing a withdrawal

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

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

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

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

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

The worker, and the one distinction that protects the money

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

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

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

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

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

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

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

Closing the loop

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

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

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

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

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

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

Where we are

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

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

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

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

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

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

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

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

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

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

This series keeps the halves apart on purpose:

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

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

What you'll have at the end

A running API where:

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

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

Before you start

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

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

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

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

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

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

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

Let's start from what the app has to do

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

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

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

The four tables

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

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

Decision 1: buyers and sellers live in separate tables

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

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

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

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

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

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

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

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

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

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

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

numeric stores digits exactly:

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

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

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

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

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

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

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

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

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

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

Decision 4: how to search an encrypted email column

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

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

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

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

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

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

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

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

Lookups then run against the hash, never the plaintext:

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

Three details that matter:

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

The products table

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

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

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

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

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

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

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

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

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

How a request travels through the app

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

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

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

  return app;
}

Here's what each layer is allowed to do:

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

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

The router: the access model in one screen

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

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

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

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

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

The controller, and a leak it prevents

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

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

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

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

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

Instead of what it should be:

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

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

The service: this is where the business rules live

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

Notice that both failures throw the same NotFoundError.

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

The repository: the only file that interacts with Drizzle

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

The orders table, where the storefront stops

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

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

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

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

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

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

The order row exists before any money moves

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

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

Creating an order looks like this:

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

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

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

Download access is a token, not a boolean

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

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

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

The delete rules encode what each row means

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

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

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

What this table deliberately doesn't know

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

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

Where we are

You now have a storefront that runs on its own:

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

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

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

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

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

How to Accept International Payments as an African Developer or Business

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

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

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

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

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

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

The Three Collection Methods

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

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

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

Method 1: Dedicated Virtual Accounts

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

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

This approach works especially well for:

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

Afriex supports two types of dedicated virtual accounts:

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

Creating a Static or Dynamic Virtual Account

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

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

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

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

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

Reusing Existing Accounts

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

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

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

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

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

NGN Requirements

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

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

Dynamic virtual accounts don't have this requirement.

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

Method 2: Pool Accounts

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

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

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

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

Retrieving a Pool Account

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

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

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

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

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

Store the Reference Before Sharing It

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

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

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

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

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

Country-Based Accounts

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

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

Method 3: Crypto Wallets (USDT / USDC)

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

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

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

Creating or Retrieving a Customer Wallet

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

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

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

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

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

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

Detecting Crypto Deposits

Crypto deposits work a little differently from bank transfers.

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

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

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

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

Knowing When a Deposit Has Landed

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

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

Handling Deposit Webhooks

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

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

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

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

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

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

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

A few implementation details are worth paying attention to:

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

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

Registering Your Webhook

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

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

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

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

Choosing the Right Collection Method

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

Use Dedicated Virtual Accounts if...

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

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

Use Pool Accounts if...

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

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

Use Crypto Wallets if...

Crypto wallets are ideal when your customers already hold USDT or USDC and prefer paying with stablecoins instead of making bank transfers.

Learn More

If you like to explore each payment method in more detail, these guides provide a deeper look at their individual integration flows:

*
How to accept USDT and USDC
Virtual accounts and pool accounts

You can also explore the Afriex Business platform and API documentation here:

Final Thoughts

There's no single payment collection method that's right for every product.

If your business relies on repeat customers, dedicated virtual accounts provide the simplest reconciliation experience. If speed matters more than individual account management, pool accounts let you start collecting payments with minimal setup. And if your customers already use stablecoins, crypto wallets offer a familiar way to pay while Afriex handles the conversion behind the scenes.

By offering multiple collection methods through a single API, you can support different customer preferences without maintaining separate payment integrations.

Whether you're building a SaaS platform, marketplace, fintech product, or any business that serves customers across borders, the Afriex Business API gives you the flexibility to accept payments in the way that best fits your users.

AI Agent observability with DriftWatch and SigNoz

Victory Lucky — Sun, 26 Jul 2026 14:36:01 +0000

In the agentic AI era, one of the major challenges is token and agent optimization, but then how can you truly optimize this without deep insights into the activities of your AI agent?
Those were my thoughts while exploring agentic AI and MCP servers (I recently built one for a Fintech),
I knew the problem exists but I never truly understood the best way to approach it nor the tools required to solve that problem, until recently when I came across this tweet on X
Coincidentally, I got an email from WeMakeDevs about the Signoz hackathon on the same day I saw the above tweet, then it clicked that this was the right time to solve this problem, so I built DriftWatch.

The Problem

Most agentic AI applications are built blindly without deep insight into,

What tools were called most
How long did it take (latency, throughput)
How much tokens were consumed for input and output
How much did it cost in USD?
Which prompts consumed the most tokens
Which model was used, and
When did the agent start drifting from the intended action.

This and more are the problems DriftWatch is solving.

So what is DriftWatch and how does it solve the problems

DriftWatch is a self-observing AI agent SDK that integrates with the Vercel AI SDK.
It traces every tool call and model step an agent makes as OpenTelemetry into SigNoz,

then let's a drift-judge watch that telemetry for behavioral drift by querying the SigNoz API, and detects shifts in tool-call mix, error rate, latency, or token spend.

import { detectBehavioralDrift } from '@driftwatch/sdk';

const report = await detectBehavioralDrift({
  modelClient: openai('gpt-4o-mini'),
  driftDetectionConfig: config.driftDetection, // SigNoz URL + API key
});

console.log(report.verdict);
// {
//   drift: true,
//   severity: 'medium',
//   reasons: ['error rate 1% → 8%', 'p95 latency 210ms → 680ms'],
//   recommended_action: 'Investigate the rising error rate before it spreads.'
// }

Along with this, DriftWatch also provides per-task guardrails, which lets you control the max token and cost of each task and what to do when that limit is met,

const result = await runAgentTask({
  prompt,
  modelClient: openai('gpt-4o-mini'),
  tools,
  maxSteps: config.agent.maxSteps,
  guardrails: {
    maxTokensPerTask: 40_000,   // 0 disables this check
    maxCostUsd: 0.5,            // 0 disables; derived from the prices below
    pricePer1kInput: 0.005,
    pricePer1kOutput: 0.015,
    onExceed: 'stop',           // 'stop' halts mid-loop; 'flag' finishes and marks it
  },
});

if (result.guardrailTriggered) {
  console.warn('guardrail hit:', result.guardrailReason);
}

How to use DriftWatch and connect to Signoz

Using DriftWatch and connecting it to SigNoz is straightforward, and can be done in a few ways.

Step 1

Install the SDK from npm, along with any ai provider of your choice

npm install @driftwatch/sdk ai zod
npm install @ai-sdk/openai   # or any AI SDK provider you already use

Step 2: Provide env variables and set up the telemetry

Connecting to SigNoz Cloud

# Ingestion: For pushing telemetry to SigNoz
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key>

# Query API: For pulling data for drift behaviour (create a key with at least the Viewer role)
SIGNOZ_URL=https://<your-team>.<region>.signoz.cloud
SIGNOZ_API_KEY=<your-api-key>

# Read by your provider package (@ai-sdk/openai), not by the SDK itself.
OPENAI_API_KEY=sk-...

Connecting to self-hosted SigNoz
Self-hosted SigNoz bundles the collector and query service, and needs no ingestion header:

git clone https://github.com/SigNoz/signoz && cd signoz/deploy/docker
docker compose up -d          # UI + query service on :8080, OTLP collector on :4318

# Ingestion: For pushing telemetry to SigNoz
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318     # collector (HTTP/proto)
OTEL_EXPORTER_OTLP_HEADERS=                            # none for self-hosted


# Query API: For pulling data for drift behaviour (create a key with at least the Viewer role)
SIGNOZ_URL=http://localhost:8080                       # query service / UI
SIGNOZ_API_KEY=<key from Settings → API Keys>

# Read by your provider package (@ai-sdk/openai), not by the SDK itself.
OPENAI_API_KEY=sk-...

Start telemetry, create a telemetry.ts file (you can name the file anything)

// telemetry.ts — preload; must run before anything else imports
import 'dotenv/config'; // load .env into process.env before anything reads it
import { bootstrapTelemetry, loadDriftWatchConfigFromEnv } from '@driftwatch/sdk';

bootstrapTelemetry(loadDriftWatchConfigFromEnv().telemetry);

bootstrapTelemetry starts OpenTelemetry and sends traces, metrics, and logs to SigNoz. It must run before your application code, in a
separate file, loaded with --import. This is not a style choice: OpenTelemetry instruments modules (fetch, http, …) by patching them the moment they load. If your application file has already imported those modules by the time bootstrapTelemetry runs, the patch is too late, and nothing is captured.

Step 3. Run an agent task

The runAgentTask function runs a traced tool-use loop. Give it a model and tools. It returns the result and a usage summary, and because telemetry.ts already started OpenTelemetry, it emits the agent.run trace and agent.tool.* metrics as it goes.

The example below is runnable. The tool calls Open-meteo's public API.

import 'dotenv/config'
import { runAgentTask, loadDriftWatchConfigFromEnv } from '@driftwatch/sdk';
import { openai } from '@ai-sdk/openai';
import { tool } from 'ai';
import { z } from 'zod';

const config = loadDriftWatchConfigFromEnv();
const modelClient= openai('gpt-5');
// Tools the agent can call. Both hit Open-Meteo's free, keyless API — https://open-meteo.com.
const tools = {
  get_weather: tool({
    description: 'Get current weather for a city',
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => {
      const geoRes = await fetch(
        `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`,
      );
      const geoData = await geoRes.json();
      const location = geoData.results?.[0];
      if (!location) {
        return { error: `No location found for "${city}"` };
      }

      const weatherRes = await fetch(
        `https://api.open-meteo.com/v1/forecast?latitude=${location.latitude}&longitude=${location.longitude}&current_weather=true`,
      );
      const weatherData = await weatherRes.json();
      return {
        city: location.name,
        country: location.country,
        tempC: weatherData.current_weather?.temperature,
        windSpeedKmh: weatherData.current_weather?.windspeed,
      };
    },
  }),

  search_docs: tool({
    description: 'Search the Open-Meteo API documentation for a query term',
    inputSchema: z.object({ query: z.string() }),
    execute: async ({ query }) => {
      const res = await fetch('https://open-meteo.com/en/docs');
      const html = await res.text();
      const text = html.replace(/<[^>]+>/g, ' ');
      const hits = text.split(new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')).length - 1;
      return { query, hits };
    },
  }),
};

const result = await runAgentTask({
  prompt: 'What is the weather in Lagos, and how many times does the Open-Meteo docs page mention "temperature"?',
  modelClient, // any AI SDK provider; needs its API key
  tools,
  maxSteps: config.agent.maxSteps,
});

console.log(result.responseText);
console.log(result.skillsUsed, result.tokenUsage);

Then run agent.ts with telemetry.ts preloaded ahead of it.

npx tsx --import ./telemetry.ts ./agent.ts

And that's it, You get the model's answer and the exact usage for that call:

The current weather in Lagos, Nigeria is **27°C** with a wind speed of **15 km/h**.

The Open-Meteo documentation mentions the word "temperature" **59 times**.
[ 'get_weather', 'search_docs' ] { inputTokens: 877, outputTokens: 254, totalTokens: 1131 }

Give it a few minutes, search service_name=driftwatch from the SigNoz dashboard, and watch the traces, logs and metrics show up,
if you need an already configured dashboard, import observability/signoz-dashboard.json
via SigNoz Dashboards → New dashboard → Import JSON — it contains all three panels below, pre-built.

Another way to use DriftWatch is through the withSkillExecutionSpan function,
Wrap a tool's execute in withSkillExecutionSpan. Every call then produces a
tool.<name> span and increments the agent.tool.calls and
agent.tool.duration metrics. These are the signals the drift detector reads.
Use this for any tool, whether it's a database lookup, an HTTP call, or a vector search:

import { withSkillExecutionSpan } from '@driftwatch/sdk';
import { tool } from 'ai';
import { z } from 'zod';

const get_repo = tool({
  description: 'Get public information about a GitHub repository',
  inputSchema: z.object({ owner: z.string(), repo: z.string() }),
  execute: (input) =>
    withSkillExecutionSpan({
      skillName: 'get_repo',
      skillInput: input,
      executeSkill: async () => {
        const res = await fetch(
          `https://api.github.com/repos/${input.owner}/${input.repo}`,
          { headers: { 'user-agent': 'driftwatch-demo' } },
        );
        const data = await res.json();
        return { stars: data.stargazers_count, language: data.language };
      },
    }),
});

What I learnt and challenges faced

While building DriftWatch, I encounter series of challenges and bugs,

Telemetry silently going nowhere While testing out DriftWatch, I had issues with my telemetry not showing up on the dashboard, and had to reach out to SigNoz's support through email, and Shivams response was truly helpful. After which I realized that part of the problem was that I loaded my .env file using dotenv/config inside the application's entry point, which runs after the preload. So when the preload tried to read OTEL_EXPORTER_OTLP_ENDPOINT, it got undefined.

2.Traces worked, but my metrics disappeared
After fixing the exporter, traces appeared almost immediately.
but the custom metrics did not.

Metrics such as:
agent.tokens,agent.tool.calls,agent.tool.duration were nowhere to be found, while runtime metrics like:
http.server.duration and nodejs.eventloop showed up perfectly.

This turned out to be a subtle OpenTelemetry JavaScript issue.

Originally, I created the metric instruments at module load time.

const meter = metrics.getMeter('driftwatch');

const tokenCounter = meter.createCounter('agent.tokens');

Unfortunately, that module was imported before my telemetry bootstrap registered the global MeterProvider.
When no provider exists, the Metrics API returns a no-op meter, so
every instrument created from that meter silently drops measurements forever.

The confusing part was that traces did not behave this way.

The solution was to create instruments lazily.

let tokenCounter: Counter | undefined;

function getTokenCounter() {
  return (
    tokenCounter ??=
      metrics
        .getMeter('driftwatch')
        .createCounter('agent.tokens')
  );
}

The first request now creates the counter after the provider has already been registered.

Calling the wrong Query Builder After fixing the telemetry flow, it was finally time to build the drift detector. The detector queries SigNoz through /api/v4/query_range but I was sending the older v3 query format:

aggregateOperator: "sum"

Meanwhile, the v4 expects aggregation to be split across separate fields:
temporality, timeAggregation, and spaceAggregation.

Once I updated my requests, counters started returning data.
But there was still one final mystery.

agent.tool.duration always returned an empty result.

The answer turned out to be hidden inside how SigNoz stores histograms.

Instead of storing a histogram under one metric name, SigNoz expands it into several related series:
.bucket .count, .sum, .min,.max

The base metric name itself is not directly queryable.

To calculate percentiles, you query the .bucket series instead.

{
  "dataSource": "metrics",
  "aggregateAttribute": {
    "key": "agent.tool.duration.bucket",
    "type": "Histogram"
  },
  "temporality": "Delta",
  "spaceAggregation": "p95"
}

Lessons learnt
but at the end I was able to learn a number of new things, which includes:

Deeper understanding of telemetry (this is my first time working with it), I now know what histograms and counters are, differences between span and meter.
How to create a dashboard using the UI or by importing a JSON.
A better understanding of Vercel AI SDK

Conclusion

DriftWatch SDK does more than what I talked about in this article, but I had to stop so as not to make it too long, Check out the documentation at drift-watch-docs.vercel.app/docs/sdk for the full details about DriftWatch capabilities, and other tools which I didn't mention in this post, including @driftwatch/autopilot which lets you setup schedulers and notifiers to get notify on Slack, Telegram or Webhook, whenever your agent drifts.

Driftwatch is also open-source and contributions are welcomed on the Github repo.

Detecting AI Agent Behavioral Drift with OpenTelemetry and SigNoz

Victory Lucky — Sun, 19 Jul 2026 22:35:39 +0000

Recently, I have been working on AI agents and MCPs (I just completed one for a Fintech)

and some of the challenges that kept showing up was,

how do I know what this agent is doing?
how do I know how much token it consumed?
what was the cost in USD?
how do I know when this agent drifts from the intended action?
and finally, how do I tell what the latency was, and when it spiked?

While still thinking through on how to solve this problem, I came across this tweet on X

In the noon of that same day, I got an email from WeMakeDevs about the SigNoz hackathon, I went through the details and saw that it was about telemetry, and that was all the cue I needed.

How the tool was born

The frustration I encountered trying to understand the processes of these agents,such as wondering what changed, what model was used? what was the thought process of the model and the skill before it arrived at the previous result? was what led me to build DriftWatch

The solution

Introducing DriftWatch: An AI agent that observes itself.

So what is DriftWatch?
DriftWatch is an AI agent SDK that observes itself. Every skill (tool)
call and LLM step is traced via OpenTelemetry into
SigNoz, and an AI layer on top of those traces flags
behavioral drift — shifts in tool-call mix, error rate, latency, or
token spend between two time windows.

DriftWatch does this by observing every process, tool calls, duration, drifts, as well as the model and/or skill used, and provides you with an Open telemetry records passed and analysed in SigNoz, which provides deep insights into the whats, whys and whens of every process.

How DriftWatch works

DriftWatch wraps tool calls, and use open telemetry elements to track every process from initiation to response. Concretely, that means every agent run gets one parent agent.run span, every tool call gets its own child span, and three custom metrics ride alongside them: agent.tool.calls (counter, labelled by tool + outcome), agent.tool.duration (histogram), and agent.tokens (counter, labelled by model/provider/type). None of this is SigNoz-specific yet — it's just the OpenTelemetry Node SDK, instrumented once at process startup:

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: telemetryConfig.serviceName,
    'agent.kind': 'driftwatch',
  }),
  traceExporter: new OTLPTraceExporter({
    url: `${telemetryConfig.otlpEndpoint}/v1/traces`,
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: `${telemetryConfig.otlpEndpoint}/v1/metrics`,
    }),
    exportIntervalMillis: 10_000,
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Point OTEL_EXPORTER_OTLP_ENDPOINT at a self-hosted SigNoz collector (http://localhost:4318 if you're running SigNoz's own docker compose up locally) and every span and metric above lands in SigNoz over OTLP/HTTP with zero extra glue code — this is the part that's genuinely "free": SigNoz's collector supports OTLP natively, so there's no translation layer to write.

That gets you visibility.
But here's the part I actually wanted, noticing when an agent's behavior quietly changes, I needed something SigNoz doesn't do out of the box: comparing two time windows and asking whether the difference means anything. So DriftWatch queries SigNoz's /api/v4/query_range builder API directly for two one-hour windows (baseline vs. current) and diffs them:

const requestBody = {
  start: startTimeMs,
  end: endTimeMs,
  step: 60,
  compositeQuery: {
    queryType: 'builder',
    panelType: 'table',
    builderQueries: {
      A: { dataSource: 'metrics', aggregateAttribute: { key: 'agent.tool.calls', dataType: 'float64' },
           aggregateOperator: 'sum', groupBy: [{ key: 'tool' }, { key: 'outcome' }], expression: 'A' },
      B: { dataSource: 'metrics', aggregateAttribute: { key: 'agent.tool.duration', dataType: 'float64' },
           aggregateOperator: 'p95', expression: 'B' },
      C: { dataSource: 'metrics', aggregateAttribute: { key: 'agent.tokens', dataType: 'float64' },
           aggregateOperator: 'sum', expression: 'C' },
    },
  },
};

await fetch(`${signozBaseUrl}/api/v4/query_range`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'SIGNOZ-API-KEY': signozApiKey },
  body: JSON.stringify(requestBody),
});

Three builder queries in one request — tool-call counts (for tool mix and error rate), p95 tool latency, and total token spend — fanned out for both windows in parallel. The SIGNOZ-API-KEY header comes from SigNoz's own UI (Settings → API Keys), and the builder query shape took a few failed requests to get right, since the v4 API's aggregateAttribute/dataType fields aren't obvious from the dashboard alone — I ended up reverse-engineering the exact payload by watching the network tab while building a panel manually in the SigNoz UI, then copying that shape into code.

[Screenshot: SigNoz dashboard showing the agent.tool.calls, agent.tool.duration, and agent.tokens panels over a live run]

Once both windows come back as plain numbers (tool mix percentages, error rate, p95 latency, token spend), DriftWatch hands them to whatever model you've configured and asks it to judge the drift — with a strict JSON-only system prompt, retried up to a few times if the model wraps its answer in markdown:

You are an SRE copilot that classifies whether an AI agent's behavior
has drifted enough to warrant a human alert. Reply with a SINGLE raw
JSON object: {"drift": bool, "severity": "none"|"low"|"medium"|"high",
"reasons": string[], "recommended_action": string}.

That verdict, plus the raw baseline/current numbers is what shows up as the /drift endpoint response, and it's the same JSON the DriftWatch console renders as a human-readable card: severity, the specific metrics that moved, and a one-sentence recommendation.

[Screenshot: a drift verdict — e.g. "search_docs share went from 40% to 75%, error rate 2% → 9%", next to the SigNoz trace that shows the actual slow calls]

Seeing it in SigNoz

The whole loop is testable end-to-end without touching production traffic:

# bring up SigNoz locally
git clone https://github.com/SigNoz/signoz && cd signoz/deploy/docker && docker compose up -d

# run DriftWatch pointed at it, then generate some load
git clone https://github.com/codewithveek/driftwatch &&
cd drift-watch && pnpm dev
BASE_URL=http://localhost:3000 pnpm seed 40

# pull a live drift verdict computed from SigNoz data
curl localhost:3000/drift

pnpm seed 40 fires 40 mixed requests through the agent, which is enough to populate both the baseline and current windows with real spans — open SigNoz at localhost:8080 right after and you can watch the agent.run traces stack up, click into any one, and see every tool call as a child span with its own duration and status. That trace view is honestly the most useful part for debugging: when the drift judge flags "search_docs share 40% → 75%," you don't have to take its word for it, you click through to the actual traces from that window and see which tool calls dominated.

[Screenshot: a single agent.run trace expanded, showing child spans for each tool call with duration and gen_ai.* attributes]

Autopilot: closing the loop

Once drift detection works, the obvious next question is "okay, now what"? so DriftWatch has a second, optional loop that turns a drift verdict into an action: pause the agent, roll it back to a known-good state, or just notify (Slack/Telegram/webhook), gated by policy rules and, for anything destructive, a human approval step. It's a thin layer on top of the same SigNoz-derived numbers, not a separate data source — I'm not going to detail it fully here since this post is about the SigNoz integration specifically, but it's what turns "we noticed the agent drifted" into something you can leave running unattended.

Takeaways

What worked: OpenTelemetry's auto-instrumentation for Fastify/HTTP meant I got baseline request tracing for free the moment sdk.start() ran, before I'd written a single custom span. Layering agent.run/tool spans and the three custom metrics on top of that was straightforward once I had the exporter pointed at SigNoz's collector correctly.

What was hard: there's no existing semantic convention for "AI agent behavior" the way there is for HTTP or DB spans, so I had to invent my own attribute names (agent.task_id, agent.skills_used, gen_ai.usage.*) and just be consistent about them. Getting SigNoz's v4 query builder payload shape right from code (rather than the UI) took real trial and error — the error messages from a malformed compositeQuery aren't always specific about which field is wrong. And getting a model to reliably return bare JSON for the drift verdict was less reliable than I expected; the retry-with-correction-prompt approach was a hack that turned out to work well enough for a weekend build.

Conclusion

DriftWatch turns SigNoz from "a place traces go to die" into an actual feedback loop for AI agents — instrument once with OpenTelemetry, query SigNoz's builder API for two time windows, and let a model tell you when something changed. Code: https://github.com/codewithveek/drift-watch — live instance: https://driftwatch.veek.me/console/.

Build a Remittance App with the Afriex Cross-border API

Victory Lucky — Tue, 30 Jun 2026 22:54:02 +0000

Sending money across borders involves more moving parts than most developers expect. You need to know the live exchange rate before the user confirms. You need to register the recipient correctly. You need to attach their bank account or mobile wallet. You need to trigger the transfer and then track it through to settlement. And you need to handle failures gracefully when something goes wrong in the corridor.

Most of that complexity is what the Afriex Cross-border API is built to handle. This article walks through the full remittance flow — from registering a sender to confirming delivery, using the Afriex SDK from start to finish.

Get your API key

Everything starts at business.afriex.com. Create a Business account if you do not have one. Once you are in:

Go to Developer then API Keys
Click Create new keys
Give it a name (e.g. "Remittance App")
Set the permissions your use case needs — for a remittance app, you need at minimum: View wallet balances, Initiate withdrawals, View payment methods, and Add or manage payment methods
Copy the key immediately. You cannot view it again after leaving the page.

Store it as an environment variable:

AFRIEX_API_KEY=your-api-key-here
AFRIEX_ENVIRONMENT=staging  # switch to production when you go live

Start in the staging environment so nothing real moves while you build.

Install and initialize the SDK

npm install @afriex/sdk

Initialize once and reuse the instance across your application:

// src/lib/afriex.ts
import { Afriex } from "@afriex/sdk";

export const afriex = new Afriex({
  apiKey: process.env.AFRIEX_API_KEY!,
  environment:
    (process.env.AFRIEX_ENVIRONMENT as "staging" | "production") ?? "staging",
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
  },
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
});

The retryConfig handles transient failures automatically. If the Afriex API returns a 429 or a 503, the SDK retries up to three times with a delay between attempts, so you do not have to write that logic yourself. The webhookPublicKey is used later for signature verification, you can get it from the Developers > Webhooks section of your dashboard.

Step 1: Show the live exchange rate

Before anything else, show the sender what rate they are getting. A remittance user deciding between providers makes that decision based on the rate they see. Never show a hardcoded or cached rate — always fetch live.

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

async function getRate(from: string, to: string) {
  const result = await afriex.rates.getRates({
    fromSymbols: from,
    toSymbols: to,
  });

  const rate = result?.rates?.[from]?.[to];

  if (!rate) {
    throw new Error(`Rate not available for ${from}/${to}`);
  }

  return parseFloat(rate);
}

// Usage: sender sends USD, recipient gets NGN
const rate = await getRate("USD", "NGN");
console.log(`1 USD = ${rate} NGN`);

This call returns the live mid-market rate for the currency pair. Show it to the user with a clear note about when it was fetched, since rates can shift between the moment they see it and the moment they confirm. The rate the user sees is informational — the actual conversion happens on Afriex's end when the transaction is created.

Step 2: Create the recipient as a customer

The recipient needs to exist in the Afriex system before you can attach a payment method or send them money. This is a one-time step per recipient.

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

async function registerRecipient(details: {
  fullName: string;
  email: string;
  phone: string;
  countryCode: string;
}) {
  const customer = await afriex.customers.create({
    fullName: details.fullName,
    email: details.email,
    phone: details.phone,         // E.164 format, e.g. +2348012345678
    countryCode: details.countryCode, // ISO 3166-1 alpha-2, e.g. NG, KE, GH
  });

  return customer;
}

const recipient = await registerRecipient({
  name: "Victory Lucky",
  email: "victory@example.com",
  phone: "+2348012345678",
  countryCode: "NG",
});

console.log(recipient.customerId); // store this — you need it in every subsequent call

Save the customerId that comes back. Every subsequent API call references this ID rather than the recipient's personal details.

If you are building a product where senders send to the same recipient repeatedly (for example, a diaspora parent sending to family), store the customerId against the recipient record in your own database on first creation and skip this step for future transfers.

Step 3: Attach the recipient's payment method

Now tell Afriex where to send the money — the recipient's bank account or mobile wallet.

Bank account

async function attachBankAccount(params: {
  customerId: string;
  accountName: string;
  accountNumber: string;
  institutionCode: string; // bank code, e.g. "058" for GTBank Nigeria
  institutionName: string;
  countryCode: string;
}) {
  const paymentMethod = await afriex.paymentMethods.create({
    customerId: params.customerId,
    channel: "BANK_ACCOUNT",
    accountName: params.accountName,
    accountNumber: params.accountNumber,
    countryCode: params.countryCode,
    institution: {
      institutionCode: params.institutionCode,
      institutionName: params.institutionName,
    },
  });

  return paymentMethod;
}

const bankMethod = await attachBankAccount({
  customerId: recipient.customerId,
  accountName: "Victory Lucky",
  accountNumber: "0123456789",
  institutionCode: "058",
  institutionName: "GTBank",
  countryCode: "NG",
});

console.log(bankMethod.paymentMethodId); // store this too

Mobile money

For recipients receiving on MTN, M-Pesa, Airtel, or similar networks, the channel changes but the pattern is the same:

const mobileMethod = await afriex.paymentMethods.create({
  customerId: recipient.customerId,
  channel: "MOBILE_MONEY",
  accountName: "Victory Lucky",
  accountNumber: "+2348012345678", // recipient's mobile number
  countryCode: "NG",
  institution: {
    institutionCode: "MTN",
    institutionName: "MTN Mobile Money",
  },
});

Not sure which institution code to use? Call afriex.paymentMethods.listInstitutions({ countryCode: "NG", channel: "BANK_ACCOUNT" }) to get the full list for any country and channel combination.

Like the customerId, save the paymentMethodId that comes back. This is what you pass when you create the transaction.

Step 4: Send the transfer

This is the call that actually moves money. Everything before this was set up, this is the execution.

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

async function sendRemittance(params: {
  customerId: string;
  paymentMethodId: string;
  amount: number;
  sourceCurrency: string;      // currency the sender is sending
  destinationCurrency: string; // currency the recipient receives
  reference: string;           // your internal reference for this transfer
}) {
  const idempotencyKey = `idem-${params.reference}`;

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

  return transaction;
}

const transfer = await sendRemittance({
  customerId: recipient.customerId,
  paymentMethodId: bankMethod.paymentMethodId,
  amount: 100,
  sourceCurrency: "USD",
  destinationCurrency: "NGN",
  reference: "txn-478-001",
});

console.log(transfer.transactionId); // the Afriex transaction ID — store this
console.log(transfer.status);        // starts as PENDING

Two things worth understanding about this call.

The idempotencyKey is derived from your own reference. If this call fails due to a network error and your code retries it, the same key means Afriex will not create a duplicate transaction. It recognizes the key and returns the existing transaction instead of creating a new one.

The transaction comes back with a status of PENDING. That is not a failure — it is the expected starting state. The actual settlement happens asynchronously, and Afriex tells you what happened next through webhooks.

Step 5: Track the transfer through webhooks

You will not know the outcome of a transfer by polling the response from the create call. Afriex sends a signed HTTP POST to your webhook URL every time the transaction status changes. This is how you know when money has actually landed.

First, register your webhook URL in the Afriex dashboard under Developers > Webhooks. Copy the webhook public key from that page and add it to your environment:

AFRIEX_WEBHOOK_PUBLIC_KEY=your-webhook-public-key

Then use the built-in handler from the SDK:


// Signature verification
function verifySignature(
  signature: string,
  rawBody: string
): boolean {
  try {
     const event = afriex.webhooks.verifyAndParse(rawBody, signature);
return event
  } catch {
    return null
  }
}

// Webhook handler (Next.js route example)
export async function POST(req: Request) {
  const signature = req.headers.get("x-webhook-signature");

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

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

  const payload = verifySignature(
    signature,
    rawBody
  );

  if (!payload) {
    return Response.json({ error: "Invalid signature" }, { status: 401 });
  }
  if (
    event.event === "TRANSACTION.UPDATED" ||
    event.event === "TRANSACTION.CREATED"
  ) {
    const { transactionId, status } = event.data;

    // Update your database with the new status
    await updateTransferStatus(transactionId, status);

    switch (status) {
      case "SUCCESS":
        // Money has landed — notify the sender
        await notifySender(transactionId, "Your transfer was delivered.");
        break;

      case "IN_REVIEW":
        // Compliance hold — not a failure, just needs time
        await notifySender(transactionId, "Your transfer is under review.");
        break;

      case "RETRY":
        // The network is retrying automatically — no action needed
        break;

      case "FAILED":
      case "REJECTED":
        // Terminal failure — let the sender know and offer a retry
        await notifySender(transactionId, "Your transfer could not be completed.");
        break;
    }
  }

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

A few important things about how this handler is written.

It reads the raw body with req.text() before parsing anything. The SDK handles the RSA-SHA256 signature verification which was computed against those exact rawBody bytes. If you parse to JSON first and re-serialize, the verification will fail even if the payload is genuine.

It returns 200 immediately. Afriex expects a response within about five seconds. If your handler does slow work (database writes, email sending) before returning, put that work in a queue and return immediately. Afriex will retry delivery up to twelve times with exponential backoff if it does not get a success response.

IN_REVIEW and RETRY are not failures. IN_REVIEW means a compliance hold that will resolve into SUCCESS or REJECTED. RETRY means the payment network is handling it automatically. Treating either as a failure will cause you to alert users unnecessarily.

The full picture

Here is the complete flow in sequence:

1. Fetch live rate          →  afriex.rates.getRates()
2. Register recipient       →  afriex.customers.create()
3. Attach payment method    →  afriex.paymentMethods.create()
4. Send the transfer        →  afriex.transactions.create()
5. Receive status updates   →  afriex.webhooks.verifyAndParse()

Steps 2 and 3 are one-time per recipient. For a sender who sends to the same person repeatedly, you store the customerId and paymentMethodId and jump straight to step 4 on subsequent transfers.

Afriex handles the currency conversion, the corridor routing, and the settlement. Your application handles the user flow, the data storage, and the notification layer. The two concerns stay clean and separate.

The full API reference is at docs.afriex.com and the Business dashboard is at business.afriex.com. If you have questions, drop them in the comments or reach out on X @codewithveek.

How to Accept USDT and USDC Payments and Settle Automatically in USD with Afriex

Victory Lucky — Mon, 22 Jun 2026 11:16:12 +0000

Stablecoin payments are becoming a mainstream way for businesses across Africa and global markets to collect funds. USDT and USDC now account for a significant share of cryptocurrency transaction volume because they offer fast settlement, lower transaction costs, and predictable value compared to traditional cross-border payment methods.

For many businesses, however, accepting stablecoins introduces a new challenge: managing wallets, handling conversions, and moving funds into a usable currency.

The Afriex crypto wallet endpoint simplifies this process. You generate a wallet address for USDT or USDC, your customer sends funds to that address, and Afriex automatically converts the deposit into its USD equivalent in your business balance.

There is no manual conversion step, no separate swap operation, and no need to hold cryptocurrency after the payment is received.

Generate a USDT or USDC wallet address

Getting started requires a single API call and one required parameter:

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT", // or "USDC"
  customerId: "optional-customer-id",
});

If you omit customerId, the wallet belongs directly to your business account. This is useful when you want a single shared collection address for all incoming crypto payments.

If you provide a customerId, the wallet is associated with that specific customer. This approach is ideal when you need automatic payment attribution and want to know exactly which customer made a deposit without requiring payment references or manual reconciliation.

The endpoint is idempotent. Requesting a wallet for the same asset and customer multiple times returns the same wallet address each time.

{
  "data": {
    "id": "695271a3ba52c13b669fad2b",
    "addresses": [
      { "address": "0x1234567890123456789012345678901234567890", "network": "ETHEREUM_MAINNET" },
      { "address": "TYASr5UV6HEcXatwdFQfmLVUqQQQMUxHLS", "network": "TRON_MAINNET" }
    ]
  }
}

For USDT wallets, Afriex returns addresses on both Ethereum and Tron networks. You can share whichever network your customer prefers. In most cases, Tron offers lower transaction fees and is often the more economical option for senders.

How crypto deposits are converted to USD

Once USDT or USDC arrives at the generated wallet address, Afriex automatically converts the funds into their USD equivalent and records the transaction as a DEPOSIT in your account.

No additional API calls are required.

The balance that appears in your business wallet is already denominated in USD, making it easier to manage accounting, payouts, and reporting without handling cryptocurrency directly.

This workflow is especially useful for businesses that want to accept stablecoin payments while operating entirely in USD.

Detecting successful crypto payments

One important operational detail is that there is currently no dedicated webhook event for crypto-to-USD conversion deposits.

If your application relies on real-time payment notifications, you should monitor incoming deposits by polling the transactions endpoint and looking for new DEPOSIT records associated with the wallet's payment method.

const transactions = await afriex.transactions.list({
  type: "DEPOSIT",
  // filter or sort by createdAt to catch new ones
});

A common production approach is to poll periodically, track the latest processed transaction, and reconcile new deposits as they appear.

This ensures your system can reliably identify successful payments and update customer records automatically.

Production requirements and limitations

Like Afriex virtual accounts and pool accounts, crypto wallet collection is available only in the production environment.

The endpoint is not available in staging or sandbox environments.

During development, you should test your payment processing logic using mocked responses and validate the end-to-end deposit flow after going live.

If you provide a customerId, the associated customer must be verified. Requests made with an unverified customer return a 400 validation error instead of a wallet address.

Crypto wallet vs virtual account

Both crypto wallets and virtual accounts ultimately create attributable deposits in your Afriex account, but they solve different payment collection problems.

Use a virtual account when:

Customers pay via local bank transfer
Customers prefer traditional banking rails
You are collecting fiat currency payments

Use a crypto wallet when:

Customers already hold USDT or USDC
You want to accept stablecoin payments
You serve freelancers, remote workers, diaspora customers, or crypto-native businesses
Customers prefer blockchain-based payment methods

Virtual accounts are covered in the virtual accounts guide.

The Afriex crypto wallet endpoint is designed for businesses that want the speed and accessibility of stablecoin payments while keeping settlement and accounting simple through automatic USD conversion.

Frequently Asked Questions

Does Afriex support USDT on Tron?

Yes. When you create a USDT wallet, Afriex returns wallet addresses for both the Ethereum and Tron networks.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT",
});

You can provide either address to your customer depending on the network they intend to use. In many cases, Tron is preferred because transaction fees are typically lower than Ethereum.

Does Afriex support USDC payments?

Yes. The crypto wallet endpoint supports both USDT and USDC.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDC",
});

Once funds are received, Afriex automatically converts the deposit into its USD equivalent and credits your business balance.

How are crypto deposits settled?

Crypto deposits are settled automatically in USD.

When a customer sends USDT or USDC to a generated wallet address:

The blockchain confirms the transaction.
Afriex receives the stablecoin deposit.
The deposit is automatically converted into USD.
A DEPOSIT transaction is created in your account.
Your USD balance is updated.

No separate conversion request or manual swap operation is required.

Can I receive payment notifications through webhooks?

Currently, Afriex does not emit a dedicated webhook event when a crypto deposit is converted into USD.

To detect new crypto payments, periodically query the Transactions API and look for newly created DEPOSIT transactions.

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

Many production systems poll this endpoint at regular intervals and reconcile newly discovered deposits automatically.

Can I create separate wallets for different customers?

Yes.

Pass a customerId when creating a wallet to generate a customer-scoped payment destination.

const wallet = await afriex.paymentMethods.getCryptoWallet({
  asset: "USDT",
  customerId: customer.id,
});

This makes payment attribution significantly easier because deposits can be associated directly with the customer who owns the wallet.

Is the crypto wallet endpoint available in sandbox mode?

No.

The crypto wallet endpoint is currently available only in production environments. During development, use mocked responses and test payment reconciliation workflows before validating against live deposits.

Depending on how your customers prefer to pay, you may need a combination of crypto payment collection, bank transfers, and payout infrastructure.

Afriex Virtual Accounts

Use virtual accounts when customers need to pay via local bank transfer rather than cryptocurrency.

Virtual accounts provide dedicated account details that make payment collection and reconciliation easier for fiat transactions.

Recommended for:

Local bank transfers
Customer deposits
Marketplace payments
Subscription collections

Afriex Pool Accounts

Pool accounts are useful when you want to collect payments into a shared account and attribute funds programmatically after receipt.

Recommended for:

High-volume payment collection
Marketplaces
Platforms with many users
Automated reconciliation workflows

Transactions API

The Transactions API is particularly important when working with crypto deposits because it allows you to:

Detect successful deposits
Reconcile incoming payments
Build internal payment ledgers
Trigger business workflows after settlement

If you plan to accept USDT or USDC payments in production, this endpoint will likely become a core part of your integration.

Customer Verification

When creating customer-scoped wallets, ensure the associated customer has completed verification requirements.

Unverified customers will receive validation errors when attempting to create crypto wallets tied to their account.

Customer verification is therefore an important prerequisite for customer-specific payment collection workflows.

Conclusion

The Afriex crypto wallet endpoint makes it easy to accept USDT and USDC payments without managing conversions yourself. Generate a wallet address, receive stablecoin payments, and have deposits automatically settled in USD.

If you're ready to start accepting stablecoin payments, create an Afriex account, complete your business setup, and begin collecting USDT and USDC with automatic USD settlement.

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

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

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

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

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

Two ways to collect: Dedicated accounts vs. pool accounts

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

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

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

A simple rule of thumb:

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

Important limitation: Production only

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

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

Dedicated virtual accounts

Static vs. dynamic accounts

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

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

Supported labels include:

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

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

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

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

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

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

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

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

NGN virtual accounts and BVN requirements

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

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

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

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

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

Per-customer account limits

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

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

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

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

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

A breaking change to be aware of

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

That behavior has been removed.

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

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

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

Pool accounts

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

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

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

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

There are several important differences compared to dedicated virtual accounts:

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

The most important field in the response is reference.

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

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

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

Supported currencies

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

Current country coverage is shown below:

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

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

Reconciliation pattern

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

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

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

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

Without persisting that reference beforehand, accurate reconciliation becomes impossible.

When should you use each option?

Use a dedicated virtual account when:

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

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

Use a pool account when:

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

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

Use an alternative payment method when:

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

Always verify availability before implementation using the supported currencies reference.

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

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

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

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

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

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

What Is Visa Direct?

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

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

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

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

How Afriex's Visa Direct Integration Changes International Transfers

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

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

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

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

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

The Important Caveat

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

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

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

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

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

Why Afriex Is Expanding Its Cross-Border Payment Infrastructure

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

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

The strategy is clear.

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

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

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

What the Afriex Visa Direct Partnership Means for Developers

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

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

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

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

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

The Bottom Line

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

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

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

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

Accept Payments in Minutes with Afriex Checkout Sessions

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

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

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

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

How It Works

The flow is four steps:

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

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

Prerequisites

Before you start, you'll need:

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

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

Setup

Using the SDK (Node.js / TypeScript)

Install the official Afriex SDK:

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

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

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

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

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

Enable retries for production resilience:

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

Using the REST API directly

Set your base URL depending on your environment:

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

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

Step 1: Create a Checkout Session

SDK (Node.js / TypeScript)

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

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

  return session.checkoutUrl;
}

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

REST API

cURL

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

Node.js (fetch)

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

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

Python (requests)

import requests
import os

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

Response

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

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

Request Reference

Required Fields

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

Customer Object

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

Optional Fields

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

Step 2: The Customer Completes Payment

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

Pay by Bank Transfer

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

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

Pay by Mobile Money

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

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

Step 3: Handle the Redirect

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

A typical return handler:

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

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

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

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

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

Step 4: Listen for the Webhook

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

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

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

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

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

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

Beyond the Basic Flow: Advanced Use Cases

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

Delayed Payment Collection

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

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

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

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

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

Embedded Checkout (Iframe / Webview)

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

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

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

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

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

Important Notes

Amounts are always in minor units

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

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

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

`merchantReference` must be unique

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

Sessions expire

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

Phone numbers must be E.164

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

Testing in Sandbox

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

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

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

Error Responses

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

What's Next

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

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

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

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

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

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

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

Here is how they actually compare.

What we are comparing

Three things matter for outbound disbursement:

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

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

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

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

Coverage

Paystack

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

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

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

Flutterwave

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

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

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

Afriex

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

The coverage table for African countries specifically:

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

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

Developer experience

How Paystack transfers work

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

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

How Flutterwave transfers work

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

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

How Afriex transfers work

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

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

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

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

Transaction types map cleanly to the three outbound flows:

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

For disbursement specifically, WITHDRAW is the one you use.

Status updates and webhooks

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

Paystack and Flutterwave

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

Afriex

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

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

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

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

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

When to use each one

This is the honest summary.

Use Paystack transfers if:

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

Use Flutterwave transfers if:

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

Use Afriex if:

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

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

Getting started with Afriex disbursements

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

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

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

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

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

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

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

What Afriex sends and when

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

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

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

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

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

There is also CHECKOUT_SESSION.CREATED for checkout flows.

Before you go live: allowlist the IP addresses

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

Environment	IP Address
Sandbox	`34.234.189.210`
Production	`34.197.33.100`

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

Setting up your endpoint

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

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

Signature verification

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

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

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

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

Here is the correct verification implementation:

import crypto from "crypto";

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

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

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

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

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

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

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

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

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

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

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

The payload structure

Every Afriex webhook follows the same envelope:

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

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

Transaction payload

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

Customer payload

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

Payment method payload

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

Building a production-grade handler

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

The pattern that holds up:

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

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

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

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

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

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

Handle each event correctly

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

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

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

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

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

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

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

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

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

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

Make your handler idempotent

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

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

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

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

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

  // Process the event
  await handleTransactionEvent(payload);

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

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

Handle customer and payment method events

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

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

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

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

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

Retry behavior

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

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

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

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

Testing locally

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

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

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

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

npx ngrok http 3000

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

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

Checklist before going live

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

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

DEV Community: Victory Lucky

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

What you'll have at the end

Before you start

Let's look at the whole flow first

Let's create the checkout session

One webhook, two writes

Sale → earning → balance

Onboarding Amara for payout

Requesting and disbursing a withdrawal

The worker, and the one distinction that protects the money

Closing the loop

Where we are

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

What you'll have at the end

Before you start

Let's start from what the app has to do

The four tables

Decision 1: buyers and sellers live in separate tables

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

Decision 3: currency is an enum, not a varchar

Decision 4: how to search an encrypted email column

The products table

How a request travels through the app

The router: the access model in one screen

The controller, and a leak it prevents

The service: this is where the business rules live

The repository: the only file that interacts with Drizzle

The orders table, where the storefront stops

The order row exists before any money moves

Download access is a token, not a boolean

The delete rules encode what each row means

What this table deliberately doesn't know

Where we are

How to Accept International Payments as an African Developer or Business

The Three Collection Methods

Method 1: Dedicated Virtual Accounts

Creating a Static or Dynamic Virtual Account

Reusing Existing Accounts

NGN Requirements

Method 2: Pool Accounts

Retrieving a Pool Account

Store the Reference Before Sharing It

Country-Based Accounts

Method 3: Crypto Wallets (USDT / USDC)

Creating or Retrieving a Customer Wallet

Detecting Crypto Deposits

Knowing When a Deposit Has Landed

Handling Deposit Webhooks

Registering Your Webhook

Choosing the Right Collection Method

Use Dedicated Virtual Accounts if...

Use Pool Accounts if...

Use Crypto Wallets if...

Learn More

Final Thoughts

AI Agent observability with DriftWatch and SigNoz

The Problem

So what is DriftWatch and how does it solve the problems

How to use DriftWatch and connect to Signoz

Step 1

Step 2: Provide env variables and set up the telemetry

Step 3. Run an agent task

What I learnt and challenges faced

Conclusion

Detecting AI Agent Behavioral Drift with OpenTelemetry and SigNoz

How the tool was born

The solution

How DriftWatch works

Seeing it in SigNoz

Autopilot: closing the loop

Takeaways

Conclusion

Build a Remittance App with the Afriex Cross-border API

Get your API key

Install and initialize the SDK

Step 1: Show the live exchange rate

Step 2: Create the recipient as a customer

Step 3: Attach the recipient's payment method

Bank account

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

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