Ghana
Mobile money payments in GHS
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 |
|---|---|---|
GHS | GH | Mobile money: Airtel, AirtelTigo, MTN, Vodafone |
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: Airtel, AirtelTigo, MTN, Vodafone.
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, digits only with the country code: 233241234567 |
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 GH. 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": "GHS",
"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": "233241234567",
"email": "john.doe@example.com"
}
}Operators: Airtel, AirtelTigo, MTN, Vodafone.
The payer is redirected to paymentLink, the provider page, and confirms the payment there (some operators also send a confirmation to the phone).
Customer fields
| Field | Type | Required | Description |
|---|---|---|---|
phone | string | ✅ Yes | Payer phone number, digits only with the country code: 233241234567 |
firstName | string | ✅ Yes | First name |
lastName | string | ✅ Yes | Last name |
email | string | ✅ Yes | Payer email |
country | string | ❌ No | Country code GH. 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": "GHS",
"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": "233241234567",
"email": "john.doe@example.com"
}
}Send whole amounts in GHS: some methods do not accept fractional amounts.
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.