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] (#cancel_trans) | Used to cancel a transaction. | EResponse |
[get_trans_status] (#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 6 months ago