Charge Token Mobile

Request a mobile payment for a transaction created by createToken and display the returned operator instructions to the customer.

The ChargeTokenMobile request accepts a phone number, an MNO (Mobile Network Operator) name such as safaricom or mpesa, and the MNO country name. DPO returns payment instructions from the mobile operator.

After the customer completes payment, the transaction status is updated and should be checked with verifyToken. verifyToken also displays the status of the mobile request.

Version endpoints

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

Send requests using XML in the request body.

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

Request parameters

The request parameters are the same for API v6 and API v7.

Parameter	Data type	Description	Required
`Request`	Text	Must be `ChargeTokenMobile`.	Mandatory
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`TransactionToken`	Token	Transaction token received from `createToken`.	Mandatory
`PhoneNumber`	Text	Phone number to charge.	Mandatory
`MNO`	Text	Mobile Network Operator name according to your terminal settings in the system. Ask the Directpay team for the accepted value.	Mandatory
`MNOcountry`	Text	MNO country name according to your terminal settings in the system. Ask the Directpay team for the accepted value.	Mandatory

📱
If you are unsure which MNO or MNOcountry values are valid for your tenant, call GetMobilePaymentOptions first. Use the returned provider and country values according to your terminal configuration.
For more guidance about mobile network operator requirements, supported countries, and approval flows, see the MNO Advisory.

Request examples

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0C41A7F</CompanyToken>
  <Request>ChargeTokenMobile</Request>
  <TransactionToken>9EF83250-B6A2-4FDD-A290-C4CE7EA6D447</TransactionToken>
  <PhoneNumber>25412345678</PhoneNumber>
  <MNO>mpesa</MNO>
  <MNOcountry>kenya</MNOcountry>
</API3G>

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <CompanyToken>90EC1DA4-A7C5-432C-930C-098715D3130E</CompanyToken>
  <Request>ChargeTokenMobile</Request>
  <TransactionToken>F0C9D5A6-D130-44B7-896C-A0FD701FE132</TransactionToken>
  <PhoneNumber>25412345678</PhoneNumber>
  <MNO>SafaricomC2B</MNO>
  <MNOcountry>kenya</MNOcountry>
</API3G>

Response fields

The method returns payment instructions from the mobile operator.

Parameter	Data type	Description
`StatusCode`	3/4 digit code	Code sent with the result of the request.
`ResultExplanation`	Text	Free text result explanation.
`instructions`	Text	Payment instructions to display to the customer.
`RedirectOption`	Boolean	If the value is `1` (`true`), redirecting to the MNO URL is necessary to complete the payment. You need to decode the URL.

The method returns payment instructions from the mobile operator.

Parameter	Data type	Description
`Code`	3/4 digit code	Code sent with the result of the request.
`Explanation`	Text	Free text result explanation.
`Instructions`	Text	Payment instructions to display to the customer.
`RedirectOption`	Boolean	If the value is `1` (`true`), redirecting to the MNO URL is necessary to complete the payment. You need to decode the URL.
`BackUrl`	Text	Transaction `BackUrl` that you can set up on the `createToken` API.
`declinedUrl`	Text	Transaction `declinedUrl` that you can set up on the `createToken` API.
`RedirectUrl`	Text	Transaction `RedirectUrl` that you can set up on the `createToken` API.

📘
Display the returned instructions exactly as provided because they are customer-facing and may include transaction-specific business numbers, account references, STK prompts, or USSD guidance.

Response codes

Code	Explanation
`130`	New invoice.
`801`	Request missing company token.
`802`	Company token does not exist.
`803`	No request or error in request type name.
`804`	Error in XML.
`950`	Request missing transaction-level mandatory fields.
`951`	Data mismatch: `TransactionToken`.
`952`	Request missing mandatory field: `MNO` (Mobile Network Operator).
`953`	Request missing mandatory field: `MNOcountry` (Mobile Network Operator country name).
`954`	Request missing mandatory field: `PhoneNumber` (phone number of the payer / MSISDN).
`955`	Phone number is invalid.
`956`	Terminal not found.

Code	Explanation
`130`	New invoice.
`001`	Authorized.
`801`	Request missing company token.
`802`	Company token does not exist.
`803`	No request or error in request type name.
`804`	Error in XML.
`906`	Something went wrong on the charge process. Try again.
`950`	Request missing transaction-level mandatory fields.
`951`	Data mismatch: `TransactionToken`.
`952`	Request missing mandatory field: `MNO` (Mobile Network Operator).
`953`	Request missing mandatory field: `MNOcountry` (Mobile Network Operator country name).
`954`	Request missing mandatory field: `PhoneNumber` (phone number of the payer / MSISDN).
`955`	Phone number is invalid.
`956`	Terminal not found.

Response examples

<?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. Please ensure your phone is on and unlocked to enable you to complete the process. Thank you.
    <br>
    <br> You can also pay using Lipa na MPESA by using the following instructions:
    <br> 1.Go to the M-PESA menu
    <br> 2. Select Lipa na M-PESA
    <br> 3. Select the Paybill option
    <br> 4. Enter business number 927633
    <br> 5. Enter your account number 2257FB0D1
    <br> 6. Enter the amount 1
    <br> 7. Enter PIN and press OK to send
    <br> 8. You will receive a confirmation SMS with your payment reference number.
  </instructions>
  <RedirectOption>0</RedirectOption>
</API3G>

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>130</Code>
  <Explanation>New Invoice</Explanation>
  <RedirectUrl>https://redirect.com</RedirectUrl>
  <BackUrl></BackUrl>
  <declinedUrl></declinedUrl>
  <Instructions>1.Go to the M-PESA menu&lt;br&gt;2. Select Lipa na M-PESA&lt;br&gt;3. Select the Paybill option&lt;br&gt;4. Enter business number 927633&lt;br&gt;5. Enter your account number 1776F0C9D&lt;br&gt;6. Enter the amount 567&lt;br&gt;7. Press OK to send&lt;br&gt;8. You will receive a confirmation SMS with your payment reference number.</Instructions>
  <RedirectOption>0</RedirectOption>
</API3G>

Recommended flow

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

  M->>D: createToken → TransactionToken
  M->>D: GetMobilePaymentOptions for valid MNO values
  M->>D: ChargeTokenMobile with phone, MNO, and MNOcountry
  D-->>M: Payment instructions and RedirectOption
  M-->>U: Display instructions or redirect if required
  O-->>U: Mobile prompt or payment instructions
  U->>O: Completes mobile payment
  M->>D: verifyToken to check mobile request status

Usage notes

Validate the phone number before sending it. Format and length can vary by country and mobile operator.
Confirm MNO and MNOcountry values with the Directpay team or by using GetMobilePaymentOptions.
Show the customer a pending state while waiting for the mobile operator prompt or payment confirmation.
Use verifyToken after the customer completes payment to confirm the final transaction status and mobile request status.
If RedirectOption is 1, decode and open the MNO URL required to complete the payment.