Integration Guide

This guide covers best practices for integrating the Afriex Business API into your application.

Environments

The Afriex API provides two environments:

Environment	Base URL	Purpose
Staging	`https://staging.afx-server.com`	Testing and development
Production	`https://prod.afx-server.com`	Live transactions

Never use production API keys in your testing environment.

Authentication

All API requests require authentication using your API key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  https://staging.afx-server.com/api/v1/customer

Idempotency

For critical operations like creating transactions, use idempotency keys to prevent duplicate processing:

{
  "customerId": "CUSTOMER_ID",
  "destinationAmount": 5000,
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "destinationId": "PAYMENT_METHOD_ID",
  "meta": {
    "idempotencyKey": "unique-key-123",
    "merchantId": "MERCHANT_ID"
  }
}

Error Handling

The API uses standard HTTP status codes:

Status	Meaning
200	Success
201	Created
400	Bad Request - Check your request payload
401	Unauthorized - Invalid API key
404	Not Found - Resource doesn’t exist
500	Server Error - Contact support

Pagination

List endpoints support pagination with page and limit parameters:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://staging.afx-server.com/api/v1/customer?page=0&limit=10"

Webhook Integration

Set up webhooks to receive real-time event notifications:

Configure your webhook URL in the Dashboard
Verify webhook signatures using our public key
Return a 2xx status code to acknowledge receipt

Webhook Documentation

Learn more about webhook events and security.

Rate Limiting

Be mindful of rate limits when making API calls:

Implement exponential backoff for retries
Cache exchange rates and other static data
Use webhooks instead of polling for status updates

Testing Your Integration

Test in Staging

Use the staging environment to test all API calls without affecting live data.

Verify Webhooks

Test webhook handling with the staging environment events.

Go Live

Switch to production base URL and API keys when ready.

Support

Need help with your integration? Contact us at support@afriex.com.

Getting started