Getting Started
Prerequisites
- Node.js 20 or later
- API key from business.afriex.com (Developer tab)
Installation
npm install @afriex/sdk
# or
pnpm add @afriex/sdk
# or
yarn add @afriex/sdkQuick Start
1. Import and initialize
import { AfriexSDK, Environment } from "@afriex/sdk";
const apiKey = process.env.AFRIEX_API_KEY;
if (!apiKey) throw new Error("AFRIEX_API_KEY is not set");
const afriex = new AfriexSDK({
apiKey,
environment: "staging", // or 'production'
});2. Make requests
// Create customer
const customer = await afriex.customers.create({
fullName: "John Doe",
email: "john@example.com",
phone: "+1234567890",
countryCode: "US",
});
// Check balance
const balances = await afriex.balance.getBalance({
currencies: ["USD", "NGN"],
});
console.log("Customer:", customer);
console.log("Balances:", balances);Configuration
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | Required | Your Afriex API key |
environment | string | 'production' | 'staging' or 'production' |
webhookPublicKey | string | - | Public key for webhook verification |
retryConfig | RetryConfig | { maxRetries: 0 } | Request retry configuration |
apiVersion | string | '2026-05-18' | Sent as the x-api-version header |
signRequest | function | - | Signs each request, when payload signing is enabled for your business |
Enable Retries
Retries are disabled by default. Enable them:
const afriex = new AfriexSDK({
apiKey: "...",
retryConfig: {
maxRetries: 3,
retryDelay: 1000, // milliseconds
retryableStatusCodes: [408, 429, 500, 502, 503, 504],
},
});Only GET, PUT, HEAD, DELETE, OPTIONS and TRACE requests are retried. POST and PATCH are sent once, because repeating one can repeat its effect: a second paymentBatches.withdraw() pays every recipient again. To retry other methods, list them in retryConfig.retryableMethods.
Sign Requests
If payload signing is enabled for your business, pass a function that returns the signature. It is sent in the x-api-signature header.
const afriex = new AfriexSDK({
apiKey: "...",
signRequest: ({ method, url, body }) => sign(body),
});body is the JSON exactly as it is sent. Afriex defines the signature scheme when it enables signing; sign stands for your implementation of it.
Environments
| Environment | URL |
|---|---|
| Staging | https://sandbox.api.afriex.com |
| Production | https://api.afriex.com |