DEV Community: Victory Lucky

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.

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

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

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

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

What agentic AI actually means in a payments context

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

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

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

Where agentic payment automation is already happening

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

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

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

The architectural challenge this creates

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

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

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

What agentic orchestration requires from payment APIs

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

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

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

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

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

The African corridor context

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

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

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

What to build now versus what to watch

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

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

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

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

The bottom line

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

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

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

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

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

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

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

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

The 20+ tools

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

Authentication

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

Customers

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

Transactions

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

Payment methods

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

Organization

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

Connecting your client

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

Claude Desktop

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

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

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

Claude Code

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

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

Or via the CLI:

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

Cursor

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

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

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

Without HTTP headers

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

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

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

What you can build

Cross-border payout agent

A complete payout as an MCP tool chain:

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

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

Payroll disbursement agent

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

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

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

Operational queries from your IDE

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

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

FX rate monitoring agent

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

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

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

Sandbox and environment

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

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

MCP versus the Afriex SDK

They are not alternatives — they serve different layers.

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

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

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

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