When you call the Direct Charge API for mobile money, provider behavior usually follows one of three flow types:
processing (USSD/STK prompt flow)redirect (provider-hosted completion flow)pre-otp (customer code required before request)
1) Processing Flow (USSD/STK Prompt)
Customer receives authorization prompt on mobile device and confirms with PIN.
What happens
- You initiate direct charge.
- Provider sends STK push/USSD prompt to customer.
- Customer authorizes on device.
- Transaction remains pending until provider final response.
How to detect
data.action is processing.
{
"data": {
"action": "processing",
"sessionId": "1031-4120-a98f-9357692945",
"provider": "safaricom-kenya",
"channel": "mobile-money",
"reference": "DDC20250812042317DIFMW",
"amount": 1000,
"status": "pending",
"charge": 5,
"statusDescription": "Awaiting Provider's Feedback"
},
"statusCode": 201
}
Merchant handling
- Show pending state to customer.
- Do not fulfill on initial response.
- Wait for webhook or verify by reference.
2) Redirect Flow
Provider returns a link; customer must complete payment on provider page/app.
What happens
- You initiate direct charge.
- API responds with redirect URL.
- Customer completes payment on provider channel.
- Customer may return to your app/site afterward.
How to detect
data.action is redirect and URL is typically in data.data.link.
{
"data": {
"action": "redirect",
"sessionId": "v1nadjww8lwfxxd7giumi3dyik7pzaxrxqmyvdeuunvixo25jhqf4o6wzuxhjdzg",
"provider": "orange-ivory-coast",
"channel": "mobile-money",
"reference": "DDC20250812042546ICXFC",
"amount": 10000,
"status": "pending",
"charge": 150,
"statusDescription": "Awaiting Provider's Feedback",
"data": {
"link": "https://mpayment.orange-money.com/sx/mpayment/abstract/...",
"message": "Click link to complete your payment",
"reference": "DDC20250812042546ICXFC"
}
},
"statusCode": 201
}
Merchant handling
- Redirect user to
data.data.link.
- On return, still verify final status server-side.
- Do not mark success from redirect alone.
3) Pre-OTP Flow
Some providers require customer to generate a provider code/OTP before you send the charge request.
What happens
- Customer generates code via provider USSD.
- Customer shares code with merchant.
- Merchant sends
customerInput.customerCode.
- Provider processes charge.
Common USSD codes
- Orange Ivory Coast:
#144*82#
- Orange Senegal:
#144#391#
- Orange Burkina Faso:
*144*4*6*Amount*PIN#
- Orange Mali:
#144#37#
Sample request
{
"reference": "ORDER-1002",
"amount": 50000,
"provider": "orange-senegal",
"webhook": "https://yourapp.com/webhooks/payfonte",
"narration": "Direct charge test",
"customerInput": {
"phoneNumber": "786175702",
"customerCode": "758610"
}
}
Merchant handling
- Collect OTP/customer code explicitly.
- Validate format before API call.
- Continue with normal webhook/verification completion flow.
Flow Decision Summary
| Action | Customer next step | Merchant next step |
|---|
processing | Approve on device (USSD/STK) | Wait for webhook/verify |
redirect | Complete payment on provider page | Redirect + wait for webhook/verify |
pre-otp request pattern | Generate and share code first | Send code in customerInput.customerCode |
Important Rules
Amount values must be integers in minor units. Decimals are not supported.
