DR Congo
Mobile money payments in CDF
Before you start
Authorization
How to sign your requests with the API token.
Create payment
The base order request that this page extends.
This payment method is not enabled for all merchants. Check availability with your manager.
Overview
| Currency | Country code | Payment methods |
|---|---|---|
CDF / USD | CD | Mobile money: Africel, Airtel, Orange Money, Vodacom, Vodacom (M-Pesa) · card (USD) |
Two scenarios are available. Which scenario and which operator are enabled for your account is defined by your terminal settings.
Not sure which option you have? Ask your manager.
What is different from a regular order
The order is created through the standard POST /v1/orders endpoint. The base fields (amount, currency, successUrl, failUrl, callbackUrl, etc.) are the same as for a regular order; on top of them you pass the customer object with payer details.
| Field | Type | Description |
|---|---|---|
customer | object | Payer details. The required set is listed below |
The externalUserId field is required for this payment method.
Operators: Africel, Airtel, Orange Money, Vodacom, Vodacom (M-Pesa).
Send the payer to paymentLink: the payment request goes to the operator when the link is opened, and the payer confirms it on their phone (push notification or USSD prompt). The page waits for the result and shows it; the final status also comes to your callbackUrl.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | ✅ Yes | Payer phone number in international format 243812345678. It is converted to the operator format (with or without the leading 0) automatically |
firstName | string | ⚠️ Depends on the operator | First name |
lastName | string | ⚠️ Depends on the operator | Last name |
email | string | ⚠️ Depends on the operator | Payer email |
country | string | ❌ No | Country code CD. Optional: the country is defined by the method |
The required set depends on the operator enabled on your terminal. If a field it needs is missing or the phone does not match the country format, the order is rejected with 400 listing the fields. Send firstName, lastName, email and phone whenever you have them.
Request example
{
"purpose": "Payment for order #1234",
"amount": "1000",
"currency": "CDF",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "243812345678",
"email": "john.doe@example.com"
}
}Card: Mastercard, USD.
The payer is redirected to paymentLink, the provider card page, and pays there.
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | ⚠️ phone or email | Payer phone number in international format 243812345678. It is converted to the operator format (with or without the leading 0) automatically |
firstName | string | ❌ No | First name |
lastName | string | ❌ No | Last name |
email | string | ⚠️ phone or email | Payer email |
country | string | ❌ No | Country code CD. Optional: the country is defined by the method |
The required set depends on the operator enabled on your terminal. If a field it needs is missing or the phone does not match the country format, the order is rejected with 400 listing the fields. Send firstName, lastName, email and phone whenever you have them.
Request example
{
"purpose": "Payment for order #1234",
"amount": "10",
"currency": "USD",
"externalId": "external_id",
"externalUserId": "external_user_id",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments",
"isFeeOnUser": false,
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "243812345678",
"email": "john.doe@example.com"
}
}Some DR Congo methods work in USD instead of CDF; the currency of the order must match the method enabled on your terminal.
Response
The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.