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.

❗️
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.

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

❗️Important Note

Available Methods

validate_airtime_account

Request

Response

airtime_trans_log

Request

Response

airtime_trans_com

Request

Response

cancel_trans

Request

Response

get_trans_status

Request

Response

❗️
Important Note