Get Mobile Payment Options

Retrieve the available mobile payment options for a specific transaction token, including the provider, country, amount, currency, logo, and customer payment instructions.

Use GetMobilePaymentOptions after createToken and before displaying mobile money options to the customer. The response returns only the mobile payment options available for the merchant and transaction.

📱
Mobile money integrations are subject to country-specific requirements defined by Mobile Network Operators (MNOs), including supported networks, transaction limits, and approval flows.
See the MNO Advisory for detailed guidance before enabling mobile payment options.

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

▶️ Test in Postman

Request parameters

Parameter	Data type	Description	Required
`Request`	Text	Must be `GetMobilePaymentOptions`.	Mandatory
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`TransactionToken`	Token	Transaction token received from `createToken`.	Mandatory

Parameter	Data type	Description	Required
`CompanyToken`	Token	Token you received from 3G to operate this API.	Mandatory
`Request`	Text	Request reference. Use `GetMobilePaymentOptions`.	Mandatory
`TransactionToken`	Token	Transaction unique reference.	Mandatory

Request examples

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>57466282-EBD7-4ED5-B699-8659330A6996</CompanyToken>
  <Request>GetMobilePaymentOptions</Request>
  <TransactionToken>72983CAC-5DB1-4C7F-BD88-352066B71592</TransactionToken>
</API3G>

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyToken>68B90B5E-25F6-4146-8AB1-C7A3A0C41A7F</CompanyToken>
  <Request>GetMobilePaymentOptions</Request>
  <TransactionToken>6CDE6B83-AF0E-48E7-81A0-3C308BE62E9D</TransactionToken>
</API3G>

Response fields

The server responds to the GetMobilePaymentOptions request with one or more mobileoption items inside paymentoptions.

Parameter	Data type	Description
`country`	Text	Country.
`countryCode`	ISO code	Country ISO 2-letter code. See `http://en.wikipedia.org/wiki/ISO_3166-1`.
`paymentname`	Text	Provider name.
`logo`	Text	Provider logo URL.
`celluarprefix`	Number	Country prefix.
`amount`	Money	Total amount in the selected currency.
`currency`	Text	Currency from the table of options accepted by 3G.
`instructions`	Text	Payment instructions for mobile money.

The server responds with the original transaction amount and currency, then one or more mobileoption items inside paymentoptions. Version 7 also returns fee and total values for each mobile option.

Parameter	Data type	Description
`Code`	3-digit code	Response code.
`Explanation`	Text	Free text response explanation.
`originalCurrency`	Text	Original transaction currency.
`originalAmount`	Money	Original transaction amount.
`country`	Text	Country.
`countryCode`	ISO code	Country ISO 2-letter code.
`paymentname`	Text	Provider name.
`logo`	Text	Provider logo URL.
`celluarprefix`	Number	Country prefix.
`amount`	Money	Amount for this mobile payment option.
`currency`	Text	Currency for this mobile payment option.
`instructions`	Text	Payment instructions for mobile money.
`fee`	Money	Fee for this mobile payment option.
`total`	Money	Total amount for this mobile payment option.

📘
Display the instructions exactly as returned. Instructions can include business numbers, account references, STK prompts, or USSD steps that are specific to the transaction token.

API v6 response example

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <paymentoptions>
    <mobileoption>
      <country>kenya</country>
      <countryCode>KE</countryCode>
      <paymentname>airtel</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/airtel.png</logo>
      <celluarprefix>254</celluarprefix>
      <amount>120</amount>
      <currency>KES</currency>
      <instructions>1.Go to Airtel money Sim tool kit;2. Select Airtel money option;3. Select 'Make payments' option;4. Select 'Pay bill' option;5. Select 'Other' option;6. Enter the 'Business name' - 369369;7. Enter amount you want to pay - 200;8. Enter your Airtel money PIN;9. Enter your reference 676CC8;10. Press OK to send</instructions>
    </mobileoption>
    <mobileoption>
      <country>tanzania</country>
      <countryCode>TZ</countryCode>
      <paymentname>vodacom</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/vodacom.png</logo>
      <celluarprefix>255</celluarprefix>
      <amount>70</amount>
      <currency>TZS</currency>
      <instructions>1.Dial *150*00#;2. Select pay by MPESA;3. Select Enter business number;4. Enter 644644;5. Enter 676CC8;6. Enter amount - 4456.92;7. Enter pin;8. Press 1 to confirm 2 to decline. Payment of 4456.92 to utility 644644 for account 676CC8.</instructions>
    </mobileoption>
  </paymentoptions>
</API3G>

API v7 response examples

Results found

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>000</Code>
  <Explanation>Results Found</Explanation>
  <originalCurrency>KES</originalCurrency>
  <originalAmount>100</originalAmount>
  <paymentoptions>
    <mobileoption>
      <country>uganda</country>
      <countryCode>UG</countryCode>
      <paymentname>MTNmobileMoney</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/mtn.png</logo>
      <celluarprefix>256</celluarprefix>
      <amount>3610</amount>
      <currency>UGX</currency>
      <instructions>1. MTN will send you a request to complete the payment.;2. You will be requested to select the transaction with the amount in UGX.;3. MTN will ask you to accept or reject the payment. Select Accept.;4. MTN will prompt you to enter the mobile money pin. Enter your service PIN.;5. You will receive an SMS confirmation of your transaction from MTN.;6. MTN online is a service that allows you to approve secure payments from your MTN mobile money account.</instructions>
      <fee>0.000</fee>
      <total>3610</total>
    </mobileoption>
    <mobileoption>
      <country>tanzania</country>
      <countryCode>TZ</countryCode>
      <paymentname>TIGOdebitMandate</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/tigo.png</logo>
      <celluarprefix>255</celluarprefix>
      <amount>2281</amount>
      <currency>TZS</currency>
      <instructions>Instructions for Tigo DB</instructions>
      <fee>0.000</fee>
      <total>2281</total>
    </mobileoption>
    <mobileoption>
      <country>kenya</country>
      <countryCode>KE</countryCode>
      <paymentname>SafaricomSTKv2</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/mpesa.png</logo>
      <celluarprefix>254</celluarprefix>
      <amount>100</amount>
      <currency>KES</currency>
      <instructions>Please insert your Pin to confirm you order if STK expires use this 174379 and Acc 66CDE6 to pay</instructions>
      <fee>0.000</fee>
      <total>100</total>
    </mobileoption>
    <mobileoption>
      <country>ivory coast</country>
      <countryCode>CI</countryCode>
      <paymentname>Orange_MoneyWebPay</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/orange.png</logo>
      <celluarprefix>225</celluarprefix>
      <amount>553</amount>
      <currency>XOF</currency>
      <instructions>1. Instructions for Orange Ivory Coast</instructions>
      <fee>0.000</fee>
      <total>553</total>
    </mobileoption>
    <mobileoption>
      <country>ivory coast</country>
      <countryCode>CI</countryCode>
      <paymentname>MTNbillmap</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/mtn.png</logo>
      <celluarprefix>225</celluarprefix>
      <amount>553</amount>
      <currency>XOF</currency>
      <instructions>1. Instructions for MTN Ivory Coast</instructions>
      <fee>0.000</fee>
      <total>553</total>
    </mobileoption>
    <mobileoption>
      <country>ghana</country>
      <countryCode>GH</countryCode>
      <paymentname>MTN</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/mtn.png</logo>
      <celluarprefix>233</celluarprefix>
      <amount>6</amount>
      <currency>GHS</currency>
      <instructions>1. Dial *170# select Option 6&amp;#8218 My Wallet;2. Select Option 3 for My Approvals..;3. Enter PIN to get your Pending Approval List.;4. Select pending transaction to approve.;5. Select Option 1 for YES to approve the transaction OR Option 2 for NO to reject the transaction.</instructions>
      <fee>0.000</fee>
      <total>6</total>
    </mobileoption>
    <mobileoption>
      <country>uganda</country>
      <countryCode>UG</countryCode>
      <paymentname>AirtelMobiquity_USSD</paymentname>
      <logo>https://s3-eu-west-1.amazonaws.com/directpaystorage/icons/airtelmoney.png</logo>
      <celluarprefix>256</celluarprefix>
      <amount>3610</amount>
      <currency>UGX</currency>
      <instructions>1. Instructions for Airtel Tigo</instructions>
      <fee>0.000</fee>
      <total>3610</total>
    </mobileoption>
  </paymentoptions>
</API3G>

Empty response

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>000</Code>
  <Explanation>No transactions found</Explanation>
  <paymentoptions />
</API3G>

Error response

<?xml version="1.0" encoding="UTF-8"?>
<API3G>
  <Code>950</Code>
  <Explanation>Request missing mandatory fields – TransactionToken</Explanation>
  <paymentoptions />
</API3G>

Response codes

Code	Explanation
`0130`	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.
`904`	Can’t MobilePay this transaction.
`950`	Request missing transaction-level mandatory fields.

Code	Description
`999`	Wrong request name.
`902`	Data mismatch.
`950`	Missing mandatory fields.

Usage notes

Call GetMobilePaymentOptions after createToken and before showing mobile money choices to the customer.
Render each option with logo, paymentname, country, amount, and currency.
Preserve the returned instructions exactly because they are customer-facing and may include token-specific references.
If you support multiple regions, filter or sort options by countryCode.
Treat an empty paymentoptions response as no available mobile payment options for that transaction.

Typical flow

sequenceDiagram
  participant M as Merchant Server
  participant D as DPO API
  participant U as Customer

  M->>D: createToken → TransactionToken
  M->>D: GetMobilePaymentOptions (TransactionToken)
  D-->>M: Mobile options and instructions
  M-->>U: Display available mobile payment options
  U->>D: Completes mobile payment flow
  D-->>M: Callback or status update
  M->>D: verifyToken for reconciliation