Forem: 0xSonOfUri

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

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

Stablecoins are becoming core infrastructure for global payments.

But building with them usually means:

managing private keys
running indexers
tracking on-chain activity

That’s a lot of overhead.

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

What You’ll Build

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

The Mental Model

Stop thinking:

“I need to manage wallets”

Start thinking:

“I’m building on payment rails”

With Afriex:

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

Your job is to:

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

Step 0 — Setup API Access

Base URLs

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

Environment Variables

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

Example Request

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

Step 1 — Create Your Payment Object

Afriex does not create payment links for you.

You define your own invoice / payment intent:

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

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

Step 2 — Get Deposit Address

Endpoint

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

Example

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

Response

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

Backend Example

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

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

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

Important Note

This endpoint is:

Production only

It does not work in sandbox.

Step 3 — Display Payment Instructions

Your UI should show:

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

Also include:

Sending on the wrong network may result in lost funds

Step 4 — Confirm Payments (Webhooks)

This is the most important part.

Do NOT:

rely on user confirmation
rely on block explorers

Use Afriex webhooks.

Webhook Setup

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

Signature Verification

import crypto from "crypto"

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

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

Events

TRANSACTION.CREATED
TRANSACTION.UPDATED

Logic

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

Ensure this operation is idempotent.

Step 5 — Idempotency

Outbound

Use:

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

Inbound

Webhooks may retry.

Ensure:

no duplicate credits
safe re-processing

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

Step 6 — Reconciliation

Use Afriex APIs for support and debugging:

Get transaction
List transactions
Get balance

⚠️ Common Pitfalls

1. Crypto Wallet Not Working in Dev

→ It’s production only

2. Wrong Network Deposits

→ Only present one supported network

3. Webhook Verification Fails

→ Use raw body + correct public key

4. Duplicate Credits

→ Fix with idempotency

Why This Matters

Stablecoins are becoming:

Core rails for global payments

The real opportunity isn’t just using them.

It’s building systems on top of them.

Summary

With Afriex, you can:

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

Final Thought

Afriex gives you the rails.

You build the product.

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

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

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

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

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

What You’ll Do

By the end of this guide, you’ll:

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

Step 1: Create an Afriex Business Account

Head to:

https://business.afriex.com/

Step 2: Select Entity Type

Choose the entity that applies to you:

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

This determines the documents required during verification.

Step 3: Set Up Your Business

Fill in your details:

Phone number
Full name
Business name
Country of residence
Password

Step 4: Complete Verification

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

Provide company details
Upload documents
Add associated parties
Complete phone verification

This is required for compliance and security.

Step 5: Set Up Your Team (Optional)

From the dashboard, you can:

Add team members
Assign roles
Manage permissions

Useful if you're building with others.

Step 6: Generate Your API Key

Once your account is ready:

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

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

Step 7: Make Your First API Call

Now let’s test the API.

Create a Customer

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

Expected Response

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

Step 8: Process Your First Transaction

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

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

Important Notes

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

Explore the Docs

https://docs.afriex.com/

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

What Next?

Now that you have access, you can start building:

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

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

Final Thought

Afriex gives you the rails.

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

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

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

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

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

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

What This Guide Covers

This guide is about the Afriex API.

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

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

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

Afriex vs Your Application

Afriex provides the payment infrastructure.

You build the product layer.

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

System Architecture

Client → Backend → Afriex API → Payment Rails

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

Prerequisites

Before starting, you need:

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

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

Authentication

All Afriex API calls are made server-side.

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

Example:

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

Step 1: Create a Payment Link (Your Backend)

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

Store:

amount
currency
description
expiry
customerId
unique token

import crypto from "crypto";

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

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

Then generate:

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

Step 2: Generate Payment Instructions

When a user opens the link:

Load the payment request
Call Afriex
Return instructions

🇳🇬 Virtual Account (Bank Transfer)

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

Display:

Account number
Account name
Bank name

Crypto Wallet (USDC / USDT)

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

Response:

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

If USDC is unavailable, fallback to USDT.

Step 3: Choosing Payment Method

In your backend:

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

This logic is controlled by your application, not Afriex.

Step 4: Confirm Payment (Production)

Do NOT rely on:

Button clicks
User confirmation

Use Afriex webhooks:

Receive event
Verify signature
Match to payment record
Mark as paid

Always handle this idempotently.

Security Checklist

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

Why This Pattern Matters

This is the same pattern used by:

Stripe
Paystack
Flutterwave

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

Summary

To build payment links with Afriex:

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

Next Steps

Add webhook automation
Support more currencies
Build dashboards
Add notifications

Final Note

Afriex gives you the rails.

You build the product.