You pass the MSISDN (phone number), the mobile network operator (MNO), and the MNO’s country. DPO returns actionable customer instructions and (sometimes) a redirect URL requirement.

After the customer pays, the final status is delivered via BackURL and visible via verifyToken.

Endpoint

POST https://secure.3gdirectpay.com/API/v6/

Headers

Content-Type: application/xml; charset=utf-8
Accept: application/xml

Request

Required Fields

Field	Req	Description
`CompanyToken`	Yes	Your merchant token
`Request`	Yes	Must be `ChargeTokenMobile`
`TransactionToken`	Yes	Token from `createToken`
`PhoneNumber`	Yes	MSISDN to charge (numeric, country rules apply)
`MNO`	Yes	Mobile operator key (e.g., `mpesa`, `airtel`, `vodacom`)
`MNOcountry`	Yes	Operator country name (e.g., `kenya`, `tanzania`)

Tip: If you’re unsure of valid MNO values for your tenant, first fetch options with GetMobilePaymentOptions and map the provider names to the accepted keys.

Example Request (XML)

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <CompanyToken>YOUR_COMPANY_TOKEN</CompanyToken>
  <Request>ChargeTokenMobile</Request>
  <TransactionToken>9EF83250-B6A2-4FDD-A290-C4CE7EA6D447</TransactionToken>

  <!-- MSISDN: use local format DPO expects for the operator -->
  <PhoneNumber>254712345678</PhoneNumber>

  <!-- Operator & country must match your terminal configuration -->
  <MNO>mpesa</MNO>
  <MNOcountry>kenya</MNOcountry>
</API3G>

Response

Success (invoice/push created)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <StatusCode>130</StatusCode>
  <ResultExplanation>New invoice</ResultExplanation>
  <instructions>
    Dear Customer,
    <br/>Shortly you will receive an M-PESA prompt on your phone requesting you to enter your M-PESA PIN to complete your payment.
    <br/><br/>You can also pay using Lipa na MPESA:
    <br/>1. Go to the M-PESA menu
    <br/>2. Select Lipa na M-PESA
    <br/>3. Select Paybill
    <br/>4. Business number: 927633
    <br/>5. Account number: 2257FB0D1
    <br/>6. Amount: 1
    <br/>7. Enter PIN and confirm
  </instructions>
  <RedirectOption>0</RedirectOption>
</API3G>

▶️ Test in Postman

Fields

Field	Meaning
`StatusCode`	Mobile request status (e.g., `130` = New invoice; some tenants show `0130`)
`ResultExplanation`	Human-readable status
`instructions`	Steps for the customer (HTML line breaks often included)
`RedirectOption`	`1` = you must redirect the customer to an MNO URL (decode & open); `0` = no redirect required

When RedirectOption=1, DPO will typically include or return (via a follow-up) a URL you must open to complete the customer flow. Use the exact URL provided by DPO for your tenant.

Error Codes (examples)

Code	Meaning / Action
`801`	Missing `CompanyToken`
`802`	`CompanyToken` invalid
`803`	Bad or missing `Request` name
`804`	XML error — check tags/encoding
`950`	Missing mandatory fields
`951`	Data mismatch – `TransactionToken`
`952`	Missing `MNO`
`953`	Missing `MNOcountry`
`954`	Missing `PhoneNumber`
`955`	Invalid phone number (format/range)
`956`	Terminal not found (operator/country not enabled)

Recommended Flow

sequenceDiagram
  participant M as Merchant
  participant D as DPO API
  participant U as Customer
  participant O as Mobile Operator

  M->>D: createToken → TransactionToken
  M->>D: (optional) GetMobilePaymentOptions for guidance
  M->>D: ChargeTokenMobile (Token, MSISDN, MNO, country)
  D-->>M: StatusCode + instructions (+ RedirectOption)
  M-->>U: Show instructions / open MNO URL if required
  O-->>U: Push/STK prompt / USSD
  D-->>M: BackURL callback with final result
  M->>D: (optional) verifyToken for reconciliation

UX & Validation Tips

Validate MSISDN before sending (length/prefix by country).
Pre-fill the MNO based on your earlier GetMobilePaymentOptions list to reduce errors.
Render instructions exactly, preserving line breaks—this is customer-facing.
If RedirectOption=1, immediately open the provided URL (new tab or in-app webview).
For pending flows, show a friendly “Waiting for prompt…” state and allow cancel/try again.

Troubleshooting

Symptom	Likely Cause	Fix
`955 Invalid phone number`	Wrong length/format for operator	Normalize MSISDN (e.g., `2547…` for KE), remove spaces
`956 Terminal not found`	MNO/Country not enabled for your merchant	Confirm enablement with DPO; align `MNO` key & casing
No prompt on phone	Network delays or number not on operator	Let user retry; verify MSISDN; confirm coverage
Stuck “pending”	Awaiting customer action	Wait for BackURL; poll `verifyToken` for status