Validation modes

The six validation modes of direct payin: USSD OTP, USSD Push, Guided USSD, SMS OTP, LigdiCash redirect, Operator redirect. Understand the flows and adapt your UX.

With direct payin, the operator decides how the customer confirms their payment. This mechanism is called the validation mode. It defines the exact flow you must implement on the interface side: when to collect an OTP, when to display a waiting message, when to submit a second request, or when to redirect the customer to an external page.

These six modes are independent. Each operator uses one (sometimes two with a fallback). You only implement the mode matching the operator you are integrating. See the operator-specific pages to know which mode applies.

All modes use the same endpoint POST /pay/v01/straight/checkout-invoice/create. The difference is on the UX and flow side: whether to collect an OTP, show a waiting message, redirect to a URL returned in response_text. Do not confuse this with hosted payin, which uses a distinct endpoint (/redirect/...) and exposes a LigdiCash multi-operator payment page.

Details of each mode

USSD OTP

The customer generates an OTP by dialing a USSD code on their phone, before you call the API. You collect the number and the OTP at the same time in your form, then submit a single request with both.

Flow:

1. The customer dials the USSD code

   Before filling out your form, the customer dials their operator’s USSD code on their phone (e.g. *144*4*6# for Orange Burkina Faso). A one-time OTP appears on their screen.

2. The customer enters their information

   Your form collects the phone number and the OTP at the same time.

3. You submit the API request

   A single request with the number in customer and the OTP in otp. No second call needed.

4. Confirmation by callback

   LigdiCash notifies you of the result via your callback_url.

Recommended UX: show the USSD code to dial with clear instructions before the customer fills out the form.

The OTP generated via USSD has a short validity period. Encourage the customer to enter their OTP immediately after generating it.

Operators using this mode: Orange Burkina Faso.

USSD Push

After your API request, the operator pushes a USSD prompt directly to the customer’s phone. The customer validates with their PIN on that prompt. You do not need to resubmit any request.

Flow:

1. The customer enters their number

   Your form only collects the phone number. No OTP to collect.

2. You submit the API request

   Request with the number in customer and otp: "".

3. The operator sends the USSD push

   A USSD menu appears automatically on the customer’s phone. They validate the payment with their PIN.

4. Confirmation by callback

   LigdiCash notifies you of the result via your callback_url.

Recommended UX: after submitting the API request, show a message asking the customer to validate on their phone. Display a waiting indicator and switch to the result when the callback arrives (or via polling the confirm endpoint).

Operators using this mode: Moov Africa Burkina Faso, Moov Africa Benin, MTN Mobile Money Benin, Moov Africa Côte d’Ivoire, Vodacom DRC, Airtel DRC, Africell DRC, Airtel Niger, Moov Africa Niger, YAS Togo, Moov Africa Togo.

Guided USSD

After your API request, the operator sends an SMS to the customer with the instructions and the USSD code to dial. The customer dials this code on their phone to validate. You do not need to resubmit any request.

Flow:

1. The customer enters their number

   Your form only collects the phone number.

2. You submit the API request

   Request with the number in customer and otp: "".

3. The operator sends an SMS

   The customer receives an SMS with the instructions and the USSD code to dial.

4. The customer dials the USSD

   The customer follows the instructions in the SMS and validates the payment from their USSD menu.

5. Confirmation by callback

   LigdiCash notifies you of the result via your callback_url.

Recommended UX: after submitting the API request, show a message telling the customer they will receive an SMS with the instructions to follow.

Examples of SMS received by the customer:

MTN Côte d'Ivoire

Vous avez recu une demande de debit avec la reference 1692100357.
Tapez *133# puis choisissez l option retrait pour approuver.

This mode is sometimes used as a fallback to USSD Push when the push fails (e.g. Moov Africa Burkina Faso, Moov Africa Côte d’Ivoire).

Operators using this mode: MTN Côte d’Ivoire (primary), Zamani Niger (primary), Moov Africa Burkina Faso (fallback), Moov Africa Côte d’Ivoire (fallback).

SMS OTP

After your first API request, the operator sends an OTP code by SMS to the customer. The customer shares this code with you, and you submit a second API request with the OTP.

Flow:

1. The customer enters their number

   Your form collects the phone number. No OTP at this stage.

2. First API request

   Request with the number in customer and otp: "". LigdiCash triggers the OTP being sent by SMS.

3. The customer receives the OTP

   The operator sends an OTP code by SMS to the customer’s number.

4. The customer enters the OTP

   Your interface shows a second input field for the OTP received by SMS.

5. Second API request

   You submit the request again, this time with the OTP in the otp field.

6. Confirmation by callback

   LigdiCash notifies you of the result via your callback_url.

Recommended UX: use a two-step form — first the number, then the OTP after the SMS is received. Provide a “Resend code” button with a countdown.

This mode requires two separate API calls. Wait for the customer to enter the OTP received by SMS before sending the second request.

Operators using this mode: LigdiCash Wallet.

LigdiCash redirect

For some operators, the LigdiCash integration currently goes through a dedicated LigdiCash web page instead of direct API processing. You call the same /straight/checkout-invoice/create endpoint, pre-filling customer with the customer’s number. LigdiCash responds with a payment page URL where only the operator matching the number is offered and the number is pre-filled. You redirect the customer to that URL — they confirm from the LigdiCash page, and the payment proceeds following the operator’s own mode.

Pre-filling customer is mandatory for these operators. Without customer, the number-based filtering does not work and the payment page does not show the correct operator. Do not confuse this with the other direct payin modes, where customer is always provided but simply initiates the transaction without filtering.

Flow:

1. The customer enters their number

   Your form only collects the phone number. No OTP to collect.

2. You submit the API request

   Request to POST /pay/v01/straight/checkout-invoice/create with customer filled with the customer’s number and otp: "".

3. LigdiCash returns a payment page URL

   The response contains the transaction token, and the response_text field is filled with the URL of the LigdiCash payment page dedicated to this transaction.

4. You redirect the customer

   Redirect the customer’s browser to the returned URL. The LigdiCash payment page shows the pre-filled number and the operator already selected — the customer cannot change the number or the operator.

5. Confirmation by callback

   The customer confirms from the LigdiCash page, and the payment proceeds following the operator’s own mode (USSD push, OTP, etc.). LigdiCash notifies you of the final result via your callback_url.

Recommended UX: redirect the customer immediately to the URL returned in response_text. Set up a waiting state on the backend in parallel and switch to confirmation when the callback arrives.

This mode does use the /straight/checkout-invoice/create endpoint (direct payin). Do not confuse this with hosted payin, which uses a distinct endpoint (/redirect/...) and exposes a multi-operator payment page where the customer chooses their payment method.

Operators using this mode: Orange Money DRC, Orange Money Guinea (Conakry), MTN Mobile Money Guinea (Conakry), Orange Money Senegal, Wave Senegal, Free Senegal.

Operator redirect

For some operators, the LigdiCash integration goes through the operator’s web portal to authenticate the customer. After your API request, LigdiCash responds with the URL of an external portal (Orange Money, for example). You redirect the customer to that URL — they authenticate there and confirm the payment. The final result arrives by callback.

Flow:

1. The customer enters their number

   Your form only collects the phone number. No OTP to collect.

2. You submit the API request

   Request to POST /pay/v01/straight/checkout-invoice/create with the number in customer and otp: "".

3. LigdiCash returns a portal URL

   The response contains the transaction token, and the response_text field is filled with the URL of the operator’s portal (e.g. https://mpayment.orange-money.com/...).

4. You redirect the customer

   Redirect the customer’s browser to the returned URL. The customer authenticates on the operator’s portal and confirms the payment.

5. Confirmation by callback

   At the end of the portal journey, LigdiCash notifies you of the result via your callback_url. The browser-side return of the customer may be asynchronous — rely on the callback, not on the user-side return.

Example create response:

{
  "response_code": "00",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "response_text": "https://mpayment.orange-money.com/ml/mpayment/abstract/v1nd8lrkjniiezp3gus76kvmlgztvuylkcs2y5kiir6stko13emvuabrv95oaufb",
  "description": "",
  "custom_data": {
    "transaction_id": "59257c61dab04a70a009af019cd34040",
    "logfile": "202605111744086a021568f2037"
  },
  "wiki": "https://client.ligdicash.com/wiki/createInvoice"
}

Recommended UX: redirect the customer immediately to the URL returned in response_text. On the backend, set up a waiting state on the transaction in parallel and switch to confirmation when the callback arrives.

The customer’s browser-side return after the operator portal is not guaranteed — the user may close the tab, lose connectivity, or never return. The callback remains the only source of truth, as for the other modes. Never validate the payment based on the customer’s return alone.

This mode does use the /straight/checkout-invoice/create endpoint (direct payin), but the user journey includes an external redirect. Do not confuse this with hosted payin, which uses a distinct endpoint and exposes the LigdiCash payment page.

Operators using this mode: Orange Money Côte d’Ivoire, Orange Money Mali.

Summary

Mode	API requests	OTP collected	What the customer does
USSD OTP	1	Before calling the API (via USSD)	Dials a USSD, shares the OTP with the merchant
USSD Push	1	None	Validates on the USSD push received
Guided USSD	1	None	Dials a USSD after receiving an SMS
SMS OTP	2	After the first API request (via SMS)	Receives an OTP by SMS, shares it with the merchant
LigdiCash redirect	1	None	Is redirected to a pre-filtered LigdiCash page and confirms there
Operator redirect	1	None	Is redirected to the operator’s portal and confirms there

To know the validation mode of each operator, see its dedicated page in the Integration by operator section.