Skip to main content
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

  1. You initiate direct charge.
  2. Provider sends STK push/USSD prompt to customer.
  3. Customer authorizes on device.
  4. 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

  1. You initiate direct charge.
  2. API responds with redirect URL.
  3. Customer completes payment on provider channel.
  4. 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

  1. Customer generates code via provider USSD.
  2. Customer shares code with merchant.
  3. Merchant sends customerInput.customerCode.
  4. 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

ActionCustomer next stepMerchant next step
processingApprove on device (USSD/STK)Wait for webhook/verify
redirectComplete payment on provider pageRedirect + wait for webhook/verify
pre-otp request patternGenerate and share code firstSend code in customerInput.customerCode

​
Important Rules

Amount values must be integers in minor units. Decimals are not supported.
See Amount Specification.

​
Related Docs

Direct Charge API

Endpoint usage and request field definitions.

Example Payloads

Provider-specific payload templates.

Webhooks

Confirm final transaction outcome asynchronously.