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.

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 |
Updated almost 2 years ago