Airtime Top-up

This API allows partners to send airtime to mobile phones.

Before initiating the transfer, the partner should start by validating that the mobile number can receive airtime, using the validate_airtime_account.

Once that comes back successfully, then the partner can log the transfer with airtime_trans_log.

Finally, confirm the transaction with airtime_trans_com.

556556

Airtime topup API segments

❗️

Important Note

Topping up of airtime should not be confused with money remittance (real money). The former cannot be paid out while the latter can.

Available Methods

Method

Description

Return value

validate_airtime_account

Used to validate that a phone number can receive an airtime top-up.

Airtime

airtime_trans_log

Used to initiate but not execute an airtime top-up.

TransactionAirtime

airtime_trans_com

Used to execute an airtime top-up transaction.

EResponse

cancel_trans

Used to cancel a transaction.

EResponse

get_trans_status

Used to query a transactions status.

EResponse

validate_airtime_account

This method is used to validate that a phone number can receive an airtime top-up, and to obtain in response the operator it belongs to, available denominations or free range top-up values.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:validate_airtime_account>
         <ws:login>
            <xsd:corporate_code></xsd:corporate_code>
            <xsd:password></xsd:password>
         </ws:login>
         <ws:from_country></ws:from_country>
         <ws:send_currency_code></ws:send_currency_code>
         <ws:to_country></ws:to_country>
         <ws:msisdn></ws:msisdn>
      </ws:validate_airtime_account>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password provided separately

from_country

String

Yes

Send country (ISO 3166-2)

send_currency_code

String

Yes

Send country currency code (ISO 4217)

to_country

String

Yes

Destination country code (ISO 3166-2)

msisdn

String

Yes

Passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900

to_country

String

Yes

Destination country code (ISO 3166-2)

msisdn

String

Yes

Passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900 String Yes Passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:validate_airtime_accountResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax23:Airtime" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax23:airtime_mno_id/>
            <ax23:airtime_mno_name/>
            <ax23:country_code/>
            <ax23:country_name/>
            <ax23:denomination xsi:type="ax23:Denomination">
               <ax23:description/>
               <ax23:display_text/>
               <ax23:rec_amount_incl_tax>0.0</ax23:rec_amount_incl_tax>
               <ax23:receive_amount>0.0</ax23:receive_amount>
               <ax23:send_amount>0.0</ax23:send_amount>
               <ax23:validity_period/>
            </ax23:denomination>
            <ax23:free_range_values xsi:type="ax23:FreeRange">
               <ax23:max_receive_amount>0.0</ax23:max_receive_amount>
               <ax23:max_receive_amount_incl_tax>0.0</ax23:max_receive_amount_incl_tax>
               <ax23:max_send_amount>0.0</ax23:max_send_amount>
               <ax23:min_receive_amount>0.0</ax23:min_receive_amount>
               <ax23:min_receive_amount_incl_tax>0.0</ax23:min_receive_amount_incl_tax>
               <ax23:min_send_amount>0.0</ax23:min_send_amount>
            </ax23:free_range_values>
            <ax23:receive_currency_code/>
         </ns:return>
      </ns:validate_airtime_accountResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Description

airtime_mno_id

String

Unique reference for the receiving MNO on the MFS system

airtime_mno_name

String

MNO name

country_code

String

Country code of the destination MNO (ISO 3166-2)

country_name

String

Country name

denomination

description

String

Product description

display_text

String

Descriptive text made up of currencyISO + receive_amount or other product detail

rec_amount_incl_tax

String

Denominated receive amount before tax is applied at destination

receive_amount

Integer

Denominated receive amount; this amount is topped up

send_amount

Integer

Denominated send amount

validity_period

String

Validity duration of the quote (ISO 8601 Duration)

free_range_values

max_receive_amount

Numeric

Maximum amount that can be topped up as a free range amount

max_receive_amount_incl_tax

Numeric

Maximum amount that can be topped up as a free range amount, before tax is applied at destination

max_send_amount

Numeric

Maximum send amount that can be topped up as a free range amount

min_receive_amount

Numeric

Minimum amount that can be topped up as a free range amount

min_receive_amount_incl_tax

Numeric

Minimum amount that can be topped up as a free range amount, before tax is applied at destination

min_send_amount

Numeric

Minimum send amount that can be topped up as a free range amount

receive_currency_code

String

Airtime top-up currency code (ISO 4217)

airtime_trans_log

This method is used to book an airtime top-up transfer, but not execute.

This transfer proposal will expire daily at 07:30 GMT (where a transfer proposal is aged >30 minutes). Attempts to execute an expired proposal will trigger an error.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:airtime_trans_log>
         <ws:login>
               <xsd:corporate_code></xsd:corporate_code>
               <xsd:password></xsd:password>
         </ws:login>
         <ws:send_amount>
               <xsd:amount>0.0</xsd:amount>
               <xsd:currency_code></xsd:currency_code>
         </ws:send_amount>
         <ws:fee>
               <xsd:amount>0.0</xsd:amount>
               <xsd:currency_code></xsd:currency_code>
         </ws:fee>
         <ws:receive_amount>
               <xsd:amount>0.0</xsd:amount>
               <xsd:currency_code></xsd:currency_code>
         </ws:receive_amount>
         <ws:recipient></ws:recipient>
         <ws:sender></ws:sender>
         <ws:reference></ws:reference>
         <ws:third_party_trans_id></ws:third_party_trans_id>
         <ws:airtime_mno_id></ws:airtime_mno_id>
      </ws:airtime_trans_log>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password, that will be separately provided via SMS

send_amount

amount

Numeric

No

Send amount

currency_code

String

No

Currency code of the send amount (ISO 4217).

fee

amount

Numeric

No

Sending fee amount (if any)

currency_code

String

No

Fee currency code (ISO 4217)

receive_amount

amount

Numeric

Yes

Receive amount

currency_code

String

Yes

Receive amount currency code (ISO 4217)

recipient

String

Yes

Recipient’s mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900

sender

String

Yes

Sender’s mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900. Can be passed as empty if sender has no mobile phone.

reference

String (50 chars)

No

A pass-through field that may be used by MFS to pass any other relevant detail.

third_party_trans_id

String

Yes

Transaction ID of the sending partner

airtime_mno_id

String

Yes

Unique code representing the airtime MNO on the MFS system

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:airtime_trans_logResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax23:TransactionAirtime" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <ax21:airtime_fx_rate>1.00502063642373</ax21:airtime_fx_rate>      
     <ax21:fee xsi:type="ax21:Money">
     <ax21:amount>0.0</ax21:amount>
     <ax21:currency_code>GHS</ax21:currency_code>
     </ax21:fee>
            <ax21:mfs_trans_id xsi:nil="true"/>
            <ax21:receive_amount xsi:nil="true"/>
            <ax21:amount>0.0</ax21:amount>
               <ax21:currency_code></ax21:currency_code>
            </ax21:receive_amount>
    <ax21:reference>nene</ax21:reference>
            <ax21:third_party_trans_id></ax23:third_party_trans_id>
         </ns:return>
      </ns:airtime_trans_logResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Description

airtime_fx_rate

String

Applicable forex rate

fee

amount

Numeric

Fee amount

currency_code

String

Fee amount currency code (ISO 4217)

mfs_trans_id

String

Transaction ID from the MFS Hub

receive_amount

amount

Numeric

Receive amount

currency_code

String

Receive amount currency code (ISO 4217)

reference

String

Partner reference value.

third_party_trans_id

String

Transaction ID of the sending partner

airtime_trans_com

Used to commit to execute a airtime_trans_log, triggering the airtime top-up for delivery to the destination account.

The transfer proposal must be committed before it expires. Proposals will expire daily at 07:30 GMT (where a transfer proposal is aged >30 minutes). Attempts to execute an expired proposal will trigger an error.

Where you get an inconclusive result (MR102 or MR 103), you should wait for 10 seconds and call get_trans_status, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a second time, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a final third time.

After the third attempt, if still inconclusive (MR102 or MR103), stop calling and log a ticket with MFS Support.

See full code list here.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:airtime_trans_com>
         <ws:login>
               <xsd:corporate_code></xsd:corporate_code>
               <xsd:password></xsd:password>
         </ws:login>
         <ws:mfs_trans_id></ws:mfs_trans_id>
      </ws:airtime_trans_com>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password provided separately

mfs_trans_id

String

Yes

MFS transaction ID

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:airtime_trans_comResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax21:EResponse" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax21:code xsi:nil="true"/>
            <ax21:e_trans_id xsi:nil="true"/>
            <ax21:message xsi:nil="true"/>
            <ax21:third_party_trans_id xsi:nil="true"/>
         </ns:return>
      </ns:airtime_trans_comResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

code

String

Yes

Transaction status code. See list of codes here.

e_trans_id

String

Yes

Transaction ID of the receiving platform

message

String

No

Where available, description of the transaction status.

third_party_trans_id

String

Yes

Partner transaction ID

cancel_trans

A transaction that has been initiated but not yet executed can be cancelled - i.e. you can cancel a transaction that has been created (mm_trans_log ), but not if executed by trans_com.

To cancel a transaction, the partner should call this method once only per transaction it wishes to cancel.

A transaction that has been executed, but has a status of queued (MR108) may be canceled using this method, while the status remains queued MR108.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:cancel_trans>
         <ws:login>
            <xsd:corporate_code></xsd:corporate_code>
            <xsd:password></xsd:password>
         </ws:login>
         <ws:trans_id></ws:trans_id>
      </ws:cancel_trans>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password provided separately

trans_id

String

Yes

Transaction ID on the MFS Hub or Transaction ID of the sending partner

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>   
        <ns:cancel_transResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax21:EResponse" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax21:message xsi:nil="true"/>
            <ax21:third_party_trans_id xsi:nil="true"/>
         </ns:return>
      </ns:get_trans_statusResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Description

mfs_trans_id

String

MFS transaction ID

code

String

Transaction status code of the MFS transaction ID queried. See list of codes.

e_trans_id

String

Where available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.

message

String

Where available, description of the transaction status.

third_party_trans_id

String

Partner transaction ID

get_trans_status

This method is used to query a transaction status.

Where you get an inconclusive result (MR102 or MR 103), you should wait for 10 seconds and call get_trans_status, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a second time, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a final third time.

After the third attempt, if still inconclusive (MR102 or MR103), stop calling and log a ticket with MFS Support.

Where you receive a queued transaction result (MR108), you should wait 60 minutes before calling get_trans_status, once per transaction ID. If the result remains MR108, call get_trans_status every 60 minutes, but only once per transaction ID, until you obtain an MR101 or ER response.

See the full list of codes here.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd"> 
   <soapenv:Header/> 
   <soapenv:Body> 
      <ws:get_trans_status> 
         <ws:login> 
            <xsd:corporate_code></xsd:corporate_code> 
            <xsd:password></xsd:password> 
         </ws:login> 
         <ws: trans_id></ws: trans_id> 
      </ws:get_trans_status> 
   </soapenv:Body> 
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password provided separately

trans_id

String

Yes

Transaction ID on the MFS Hub or Transaction ID of the sending partner

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
   <soapenv:Body> 
      <ns:get_trans_statusResponse xmlns:ns="http://ws.mfsafrica.com"> 
         <ns:return xsi:type="ax21:EResponse" xmlns:ax21="http://mfs/xsd"  
                    xmlns:ax23="http://airtime/xsd"   
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<ax21:mfs_trans_id xsi:nil="true"/> 
            <ax21:code xsi:nil="true"/> 
            <ax21:e_trans_id xsi:nil="true"/> 
            <ax21:message xsi:nil="true"/> 
<ax21:third_party_trans_id xsi:nil="true"/> 
         </ns:return> 
      </ns:get_trans_statusResponse> 
   </soapenv:Body> 
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

mfs_trans_id

String

Yes

MFS transaction id.

code

String

Yes

Transaction status code of the MFS transaction ID queried. See list of codes here.

e_trans_id

String

Yes

Where available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.

message

String

Yes

Status description

third_party_trans_id

String

Yes

Partner transaction ID