Introduction
AfriRem provides a simple and secure API for businesses to accept payments from customers across Africa. Our API supports multiple payment methods including Mobile Money (MTN, Airtel) and Card Payments (Visa, Mastercard).
The API follows RESTful principles and returns JSON responses. All requests must be made over HTTPS.
Key Features
- Multiple payment methods (Mobile Money, Cards)
- Real-time payment status updates
- Webhook notifications
- Support for multiple currencies (RWF, USD, KES, TZS, UGX)
- Secure API key authentication
Authentication
All API requests require authentication using your API key. You can obtain your API key from your business dashboard after registration.
API Key Header
X-API-Key: your_api_key_here
Example Request with Authentication
curl -X POST https://api.afrirem.com/api/initiate-payment \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{...}'
Initiate Payment
Create a new payment and get a payment link to redirect your customer.
POST
/api/initiate-payment
Request Parameters
| Parameter | Type | Required | Description | \\
|---|---|---|---|
transaction_ref | string | Required | Your unique transaction reference |
amount | number | Required | Payment amount (positive number) |
currency | string | Required | Currency code (RWF, USD, KES, TZS, UGX) |
customer_name | string | Required | Customer's full name |
customer_email | string | Required | Customer's email address |
customer_phone | string | Required | Customer's phone number with country code |
description | string | Optional | Payment description or invoice number |
return_url | string | Optional | URL to redirect after successful payment |
Example Request
curl -X POST https://api.afrirem.com/api/initiate-payment \\
-H "X-API-Key: YOUR_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
"transaction_ref": "INV-2024-001",
"amount": 5000,
"currency": "RWF",
"customer_name": "Jean Paul",
"customer_email": "jean@example.com",
"customer_phone": "+250788123456",
"description": "Order #12345",
"return_url": "https://yourstore.com/thank-you"
}'
Success Response (201 Created)
{
"success": true,
"data": {
"payment_id": "abc123xyz789",
"payment_reference": "PAY_mt4a7f2g_8hj3k9lm",
"payment_link": "https://afrirem.com/pay/PAY_mt4a7f2g_8hj3k9lm",
"amount": 5000,
"currency": "RWF",
"status": "pending",
"expires_at": "2024-12-26T12:00:00.000Z",
"api_base_url": "https://api.afrirem.com"
}
}
Error Response (400 Bad Request)
{
"error": "Bad Request",
"message": "Missing required fields: customer_email, customer_phone"
}
Check Payment Status
Retrieve the current status of a payment using its reference.
GET
/api/payment/:reference
Path Parameters
| Parameter | Description |
|---|---|
reference | The payment reference returned from initiate payment |
Example Request
curl -X GET https://api.afrirem.com/api/payment/PAY_mt4a7f2g_8hj3k9lm \\ -H "X-API-Key: YOUR_API_KEY"
Success Response (200 OK)
{
"success": true,
"data": {
"payment_id": "abc123xyz789",
"payment_reference": "PAY_mt4a7f2g_8hj3k9lm",
"transaction_ref": "INV-2024-001",
"amount": 5000,
"currency": "RWF",
"status": "completed",
"customer": {
"name": "Jean Paul",
"email": "jean@example.com",
"phone": "+250788123456"
},
"payment_link": "https://afrirem.com/pay/PAY_mt4a7f2g_8hj3k9lm",
"created_at": "2024-12-25T10:30:00.000Z",
"completed_at": "2024-12-25T10:35:00.000Z"
}
}
Cancel Payment
Cancel a pending payment before it's completed.
POST
/api/payment/:reference/cancel
Example Request
curl -X POST https://api.afrirem.com/api/payment/PAY_mt4a7f2g_8hj3k9lm/cancel \\ -H "X-API-Key: YOUR_API_KEY"
Success Response (200 OK)
{
"success": true,
"message": "Payment cancelled successfully"
}
Webhook Notifications
Receive real-time payment status updates at your configured webhook URL.
Webhook Payload
{
"event": "payment.completed",
"payment_reference": "PAY_mt4a7f2g_8hj3k9lm",
"transaction_ref": "INV-2024-001",
"amount": 5000,
"currency": "RWF",
"status": "completed",
"customer": {
"name": "Jean Paul",
"email": "jean@example.com",
"phone": "+250788123456"
},
"timestamp": "2024-12-25T10:35:00.000Z"
}
Event Types
| Event | Description |
|---|---|
payment.initiated | Payment was created and is pending |
payment.completed | Payment was successfully completed |
payment.failed | Payment failed |
payment.expired | Payment expired without completion |
Note: Your webhook endpoint should respond with HTTP 200 within 10 seconds. We'll retry failed deliveries up to 3 times.
Error Handling
The API uses standard HTTP status codes to indicate success or failure of a request.
| Status Code | Description |
|---|---|
200 | Request successful |
201 | Resource created successfully |
400 | Bad request - missing or invalid parameters |
401 | Unauthorized - invalid or missing API key |
404 | Resource not found |
429 | Too many requests - rate limit exceeded |
500 | Internal server error |
Error Response Format
{
"error": "Error Type",
"message": "Detailed error message"
}
Rate Limits
To ensure fair usage, API requests are rate-limited per API key:
- 100 requests per minute for payment initiation
- 300 requests per minute for status checks
- Rate limit headers are included in all responses
Test Endpoint
Use the test endpoint to verify your API connection.
GET
/test
curl https://api.afrirem.com/test
Health Check
Check if the API is operational.
GET
/health
curl https://api.afrirem.com/health
Need Help?
Our support team is available 24/7 to assist you with any questions or issues.
- Email: support@afrirem.com
- Phone: +250 791 957 866
- Live Chat: Available on your dashboard