Money Remittance
Overview
The Sync Money remittance API allows partners to send money or airtime to millions of mobile wallets across Africa and beyond. These transfers are real money and can be cashed out, or used to pay for goods and services available on the mobile wallet in the receiving market.
You can use these methods to enable mobile wallet remittances as an MNO, including cash pick-ups. If you are not an MNO, check out our Async Payouts product
This API has three segments:
- First, validating the account
- Then logging the transaction request
- Then committing the transaction.
Instruction as a Receive Amount
Parties who give API instruction as Receive Amount (typically MTOs and Banks) should implement the following call flows to send Money Remittances:
The diagrams below show these three transaction segments for Instruction as Receive Amount and Send Amount.
To mobile wallets:

MTO is Partner: Transaction flows - Money remittance to Mobile Wallet
Instruction as Send Amount
Parties who give API instruction as Send Amount (typically Mobile Money Operators) should implement the following call flows to send Money Remittances:
To mobile wallets:

MNO is Partner: Transaction call flows - Money remittance transaction segments.
If you want to get the exchange rate that will be used for your transaction, you can call the get_rate API method.

Get rate API
Available Methods
Method | Description | Return value |
---|---|---|
account_request | Used to check the existence and status of the receiving account on the destination platform. | Account |
cancel_trans | Used to cancel a transaction. | EResponse |
cancel_voucher | Used to cancel a purchased cash pick-up voucher. | EResponse |
get_trans_status | Used to query a transactions status. | EResponse |
get_voucher_status | Used to query the cash out status of a cash pick-up transaction. | EResponse |
get_rate | Used to query the prevailing forex rate for destination country and from/to currency, e.g. for Kenya and from USD to KES. This rate can be used by the partner to present back to the customer in a Transfer Proposal or similar. | Rate |
mm_remit_log | Used to initiate but not execute a money remittance to a mobile wallet providing the receive amount as the instruction. | TransactionWallet |
mm_trans_log | Used to initiate but not execute a money remittance to a mobile wallet providing the send amount as the instruction. | TransactionWallet |
trans_com | Used to execute a money transaction. | EResponse |
get_voucher_status | Used to query the cash out status of a cash pick-up transaction. | EResponse |
account_request
This method is used to validate a mobile wallet account on the destination platform. Call account_request once per transaction/MSISDN.
Note
This API cannot validate bank account numbers.
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:account_request>
<ws:login>
<xsd:corporate_code></xsd:corporate_code>
<xsd:password></xsd:password>
</ws:login>
<ws:to_country></ws:to_country>
<ws:msisdn></ws:msisdn>
</ws:account_request>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
corporate_code | String | Yes | Unique corporate code |
password | String | Yes | Secure password provided separately |
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 |
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:account_requestResponse xmlns:ns="http://ws.mfsafrica.com">
<ns:return xsi:type="ax21:Wallet" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:msisdn></ax21:msisdn>
<ax21:partner_code xsi:nil="true"/>
<ax21:status xsi:type="ax21:Status">
<ax21:status_code></ax21:status_code>
</ax21:status>
</ns:return>
</ns:account_requestResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Description |
---|---|---|
msisdn | String | Returned in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900 |
partner_code | String | Unique reference for the destination partner on the Onafriq system |
status | ||
status_code | String | The status of the account (if known). "Active", Not Active", "Not_MNO", "Suspended", "Ambiguous" |
mm_remit_log
This method is used by partners, typically MTOs, to initialize a remittance transaction to a mobile money wallet.
The partner's instruction is given as Receive Amount. The Onafriq Hub pays out the Receive Amount and depletes the partner's balance in the settlement currency.
Cash pick-up remittances are also covered by this method; such transfers should include the relevant reference value in the ‘’reference’’ field.
In the case of cash pick-up remittances, the relevant voucher number will be returned in the trans_com response.
Cash pickup reference values
Cash pick-up remittances are also covered by this method; such transfers should include the relevant reference value in the ‘’reference’’ field. See Cash Pickup References for the reference values to use.
In the case of cash pick-up remittances, the relevant voucher number will be returned in the trans_com response.
Note
Conditional fields may differ dependent on partners.
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:mm_remit_log>
<ws:login>
<xsd:corporate_code></xsd:corporate_code>
<xsd:password></xsd:password>
</ws:login>
<ws:receive_amount>
<xsd:amount></xsd:amount>
<xsd:currency_code></xsd:currency_code>
</ws:receive_amount>
<ws:sender>
<xsd:address></xsd:address>
<xsd:city></xsd:city>
<xsd:date_of_birth></xsd:date_of_birth>
<xsd:document>
<xsd:id_country></xsd:id_country>
<xsd:id_expiry></xsd:id_expiry>
<xsd:id_number></xsd:id_number>
<xsd:id_type></xsd:id_type>
</xsd:document>
<xsd:email></xsd:email>
<xsd:from_country></xsd:from_country>
<xsd:msisdn></xsd:msisdn>
<xsd:name></xsd:name>
<xsd:postal_code></xsd:postal_code>
<xsd:state></xsd:state>
<xsd:surname></xsd:surname>
</ws:sender>
<ws:recipient>
<xsd:address></xsd:address>
<xsd:city></xsd:city>
<xsd:date_of_birth></xsd:date_of_birth>
<xsd:document>
<xsd:id_country></xsd:id_country>
<xsd:id_expiry></xsd:id_expiry>
<xsd:id_number></xsd:id_number>
<xsd:id_type></xsd:id_type>
</xsd:document>
<xsd:email></xsd:email>
<xsd:msisdn></xsd:msisdn>
<xsd:name></xsd:name>
<xsd:postal_code></xsd:postal_code>
<xsd:state></xsd:state>
<xsd:status>
<xsd:status_code></xsd:status_code>
</xsd:status>
<xsd:surname></xsd:surname>
<xsd:to_country></xsd:to_country>
</ws:recipient>
<ws:third_party_trans_id></ws:third_party_trans_id>
<ws:reference></ws:reference>
</ws:mm_remit_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 | Yes | Send amount |
currency_code | String | Yes | Send amount currency code (ISO 4217) |
fee | |||
amount | Numeric | Yes | Sending fee amount |
currency_code | String | Yes | Fee currency code (ISO 4217) |
sender | |||
address | String | Conditional | Sender’s address |
city | String | Conditional | Sender’s city |
date_of_birth | date | Conditional | Sender’s date of birth; YYYY-MM-DD |
document | |||
id_number | String | Conditional | Sender’s ID number |
id_type | String | Conditional | Possible values: "PP" - Passport "ID" - National ID card "DL" - Driver’s License, where accepted as legal identification |
id_country | String | Conditional | Sender’s ID country/nationality (ISO 3166-2) |
id_expiry | date | Conditional | Expiry date of sender’s ID; YYYY-MM-DD |
String | No | Sender’s email | |
from_country | String | Yes | Send country (ISO 3166-2) |
msisdn | 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. |
name | String | Yes | Sender first name |
postal_code | String | No | Postal code |
state | String | No | State |
surname | String | Yes | Sender surname |
recipient | |||
address | String | No | Recipient address |
city | String | No | City |
date_of_birth | date | No | Recipient date of birth; YYYY-MM-DD |
document | String | ||
id_number | String | No | Recipient ID number |
id_type | String | No | Possible values: Refer to Schedule 1. |
id_country | String | No | Recipient ID country/nationality |
id_expiry | date | No | Expiry date of Recipient ID; YYYY-MM-DD |
String | No | Recipient email | |
msisdn | String | Yes | Recipient mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900 |
name | String | Yes | Recipient first name |
postal_code | String | No | Postal code |
state | String | No | State |
status | |||
status_code | String | Yes | Leave blank |
surname | String | Yes | Recipient surname |
to_country | String | Yes | Destination country (ISO 3166-2) |
third_party_trans_id | String | Yes | Transaction ID of the sending partner |
reference | String (50 chars) | No | A pass-through field that can be used to pass any other relevant detail. Supports comma-separated values, if multiple details are being passed. For cash pick-up remittances, insert relevant reference value in this field. |
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:mm_remit_logResponse xmlns:ns="http://ws.mfsafrica.com">
<ns:return xsi:type="ax21:TransactionWallet" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:fx_rate></ax21:fx_rate>
<ax21:mfs_trans_id></ax21:mfs_trans_id>
<ax21:name_match xsi:nil="true"/>
<ax21:partner_code></ax21:partner_code>
<ax21:receive_amount xsi:type="ax21:Money">
<ax21:amount></ax21:amount>
<ax21:currency_code></ax21:currency_code>
</ax21:receive_amount>
<ax21:sanction_list_recipient xsi:nil="true"/>
<ax21:sanction_list_sender xsi:nil="true"/>
<ax21:send_amount xsi:nil="true"/>
<ax21:third_party_trans_id></ax21:third_party_trans_id>
<ax21:status>
<ax21:code>
</code>
<ax21:message>
</message>
</ax21:status>
</ns:return>
</ns:mm_remit_logResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
fx_rate | Numeric | Yes | Retail exchange rate applied to the customer, used to convert send amount to receive amount |
mfs_trans_id | String | Yes | MFS transaction ID |
name_match | String | Conditional | Optionally returned. Name match (fuzzy) of recipient name as provided by sending partner, with the registered name on receiving platform (where possible). |
partner_code | String | Yes | Receiving partner code |
receive_amount | Numeric | ||
amount | Numeric | Yes | Receive amount |
currency_code | String | Yes | Receive amount currency code (ISO 4217) |
sanction_list_recipient | String | No | Optionally returned where sender/recipient names have been provided for Onafriq to screen. Pass/Fail. |
sanction_list_sender | String | No | Optionally returned where sender/recipient names have been provided for Onafriq to screen. Pass/Fail. |
third_party_trans_id | String | Yes | Partner transaction ID |
status | |||
code | String | No | Status code. See list of codes here. |
message | String | No | Status description |
mm_trans_log
This method is used by partners, typically MNOs, to initialize a remittance transaction to a mobile money wallet.
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.
The partner's instruction is given in the Send Amount, which Onafriq uses to calculate the Receive Amount, which the Onafriq Hub pays out and depletes the partner's balance in the settlement currency.
Cash pickup reference values
Cash pick-up remittances are also covered by this method; such transfers should include the relevant reference value in the ‘’reference’’ field. See Cash Pickup References for the reference values to use.
In the case of cash pick-up remittances, the relevant voucher number will be returned in the trans_com response.
Note
Conditional fields may differ dependent on partners.
Request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
<soap:Header/>
<soap:Body>
<ws:mm_trans_log>
<ws:login>
<xsd:corporate_code></xsd:corporate_code>
<xsd:password></xsd:password>
</ws:login>
<ws:send_amount>
<xsd:amount></xsd:amount>
<xsd:currency_code></xsd:currency_code>
</ws:send_amount>
<ws:fee>
<xsd:amount></xsd:amount>
<xsd:currency_code></xsd:currency_code>
</ws:fee>
<ws:sender>
<xsd:address></xsd:address>
<xsd:city></xsd:city>
<xsd:date_of_birth></xsd:date_of_birth>
<xsd:document>
<xsd:id_country></xsd:id_country>
<xsd:id_expiry></xsd:id_expiry>
<xsd:id_number></xsd:id_number>
<xsd:id_type></xsd:id_type>
</xsd:document>
<xsd:email></xsd:email>
<xsd:from_country></xsd:from_country>
<xsd:msisdn></xsd:msisdn>
<xsd:name></xsd:name>
<xsd:postal_code></xsd:postal_code>
<xsd:state></xsd:state>
<xsd:surname></xsd:surname>
</ws:sender>
<ws:recipient>
<xsd:address></xsd:address>
<xsd:city></xsd:city>
<xsd:date_of_birth></xsd:date_of_birth>
<xsd:document>
<xsd:id_country></xsd:id_country>
<xsd:id_expiry></xsd:id_expiry>
<xsd:id_number></xsd:id_number>
<xsd:id_type></xsd:id_type>
</xsd:document>
<xsd:email></xsd:email>
<xsd:msisdn></xsd:msisdn>
<xsd:name></xsd:name>
<xsd:postal_code></xsd:postal_code>
<xsd:state></xsd:state>
<xsd:status>
<xsd:status_code></xsd:status_code>
</xsd:status>
<xsd:surname></xsd:surname>
<xsd:to_country></xsd:to_country>
</ws:recipient>
<ws:third_party_trans_id></ws:third_party_trans_id>
<ws:reference></ws:reference>
</ws:mm_trans_log>
</soap:Body>
</soap: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 | Yes | Send amount |
currency_code | String | Yes | Send amount currency code (ISO 4217) |
fee | |||
amount | Numeric | Yes | Sending fee amount |
currency_code | String | Yes | Fee currency code (ISO 4217) |
sender | |||
address | String | Conditional | Sender’s address |
city | String | Conditional | City |
date_of_birth | date | Conditional | Sender’s date of birth; YYYY-MM-DD |
document | |||
id_number | String | Conditional | Sender’s ID number |
id_type | String | Conditional | Possible values: "PP" - Passport "ID" - National ID card "DL" - Driver’s License, where accepted as legal identification |
id_country | String | Conditional | Sender’s ID country/nationality |
id_expiry | date | Conditional | Expiry date of sender’s ID; YYYY-MM-DD |
String | No | Sender’s email | |
from_country | String | Yes | Send country (ISO 3166-2) |
msisdn | 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. |
name | String | Yes | Sender first name |
postal_code | String | No | Postal code |
state | String | No | State |
surname | String | Yes | Sender surname |
recipient | |||
address | String | No | Recipient address |
city | String | No | City |
date_of_birth | date | No | Recipient date of birth; YYYY-MM-DD |
document | |||
id_number | String | No | Recipient ID number |
id_type | String | No | Possible values: Refer to Schedule 1. |
id_country | String | No | Recipient ID country/nationality |
id_expiry | date | No | Expiry date of Recipient ID; YYYY-MM-DD |
String | No | Recipient email | |
msisdn | String | Yes | Recipient mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900 |
name | String | Yes | Recipient first name |
postal_code | String | No | Postal code |
state | String | No | State |
status | |||
status_code | String | Yes | Leave blank |
surname | String | Yes | Recipient surname |
to_country | String | Yes | Destination country (ISO 3166-2) |
third_party_trans_id | String | Yes | Transaction ID of the sending partner |
reference | String (50 chars) | No | A pass-through field that can be used to pass any other relevant detail. Supports comma-separated values, if multiple details are being passed. For cash pick-up remittances, insert relevant reference value in this field. |
Response
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Body>
<ns:mm_trans_logResponse xmlns:ns="http://ws.mfsafrica.com">
<ns:return xsi:type="ax21:TransactionWallet" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:fx_rate></ax21:fx_rate>
<ax21:mfs_trans_id></ax21:mfs_trans_id>
<ax21:name_match>Pass</ax21:name_match>
<ax21:partner_code/>
<ax21:receive_amount xsi:type="ax21:Money">
<ax21:amount></ax21:amount>
<ax21:currency_code/>
</ax21:receive_amount>
<ax21:sanction_list_recipient>Pass</ax21:sanction_list_recipient>
<ax21:sanction_list_sender>Pass</ax21:sanction_list_sender>
<ax21:third_party_trans_id></ax21:third_party_trans_id>
<ax21:status>
<ax21:code></code>
<ax21:message></message>
</ax21:status>
</ns:return>
</ns:mm_trans_logResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
fx_rate | Numeric | Yes | Retail exchange rate applied to the customer, used to convert send amount to receive amount |
mfs_trans_id | String | Yes | MFS transaction ID |
name_match | String | Conditional | Optionally returned. Name match (fuzzy) of recipient name as provided by sending partner, with the registered name on receiving platform (where possible). |
partner_code | String | Yes | Receiving partner code |
receive_amount | |||
amount | Numeric | Yes | Receive amount |
currency_code | String | Yes | Receive amount currency code (ISO 4217) |
sanction_list_recipient | String | No | Optionally returned where sender/recipient names have been provided for Onafriq to screen. Pass/Fail. |
sanction_list_sender | String | No | Optionally returned where sender/recipient names have been provided for Onafriq to screen. Pass/Fail. |
third_party_trans_id | String | Yes | Partner transaction ID |
status | |||
code | String | No | Status code. See list of codes here. |
message | String | No | Status description |
trans_com
Used by partners to execute a transaction 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.
In the case of cash pick-up remittances, the relevant voucher number will be returned in the trans_com response.
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:trans_com>
<ws:login>
<xsd:corporate_code></xsd:corporate_code>
<xsd:password></xsd:password>
</ws:login>
<ws: trans_id></ws: trans_id>
</ws: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 |
trans_id | String | Yes | Transaction ID on the Onafriq Hub or Transaction ID of the sending partner |
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns: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:mfs_trans_id xsi:nil="true"/>
<ax21:third_party_trans_id xsi:nil="true"/>
</ns:return>
</ns:trans_comResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
mfs_trans_id | String | Yes | MFS transaction ID |
code | String | Yes | Transaction status code. See list of codes here. |
e_trans_id | String | Yes | Transaction ID of the receiving platform In the case of cash pick-up remittances, this value will be the voucher number |
message | String | No | Where available, description of the transaction status. |
third_party_trans_id | String | Yes | Partner's transaction ID |
get_rate
This method is used to query the prevailing forex rate for a currency pair e.g. from GBP to KES, or KES to UGX.
The forex rate is expressed as 1 Sending currency unit equals X Receive currency units, e.g. a partner sending a transaction from the UK to Kenya would see the rate as 1 GBP = 140 KES.
get_rate should only be called a maximum of three times per day at 7am, 9am, 12pm GMT. We set rates once daily before 9am GMT.
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_rate>
<ws:login>
<xsd:corporate_code></xsd:corporate_code>
<xsd:password></xsd:password>
</ws:login>
<ws:to_country></ws:to_country>
<ws:from_currency></ws:from_currency>
<ws:to_currency></ws:to_currency>
</ws:get_rate>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
corporate_code | String | Yes | Unique corporate code |
password | String | Yes | Secure password provided separately |
to_country | String | Yes | Destination country (ISO 3166-2) |
from_currency | String | Yes | Send currency code (ISO 4217) |
to_currency | String | Yes | Receive currency code (ISO 4217) |
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:get_rateResponse xmlns:ns="http://ws.mfsafrica.com" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd">
<ns:return xsi:type="ax21:Rate" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:from_currency></ax21:from_currency>
<ax21:fx_rate></ax21:fx_rate>
<ax21:partner_code/>
<ax21:time_stamp/>
<ax21:to_currency></ax21:to_currency>
</ns:return>
</ns:get_rateResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Description |
---|---|---|
Per Partner | ||
from_currency | String | Send currency code (ISO 4217) |
fx_rate | Numeric | Value of the exchange rate |
partner_code | String | Unique reference code for the partner on the Onafriq system |
time_stamp | Datetime | Timestamp of the forex rate, in YYYY-MM-DD HH:MM:SS (GMT) |
to_currency | String | Receive currency code (ISO 4217) |
cancel_trans
A transaction that has been initiated but not yet executed can be canceled - 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 Onafriq 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 |
cancel_voucher
A cash-pick up voucher that has been purchased via the hub can be cancelled where the provider allows for cancellation - i.e. you can cancel a cash-pick up transaction that has been created and (mm_trans_log, mm_remit_log), and executed by trans_com.
Post successful cancellation a reversal transaction is created.
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_voucher>
<ws:login>
<xsd:corporate_code>xxxx</xsd:corporate_code>
<xsd:password>xxx</xsd:password>
</ws:login>
<ws:mfs_trans_id>6574623423</ws:mfs_trans_id>
<ws:third_party_trans_id>UID234523</ws:third_party_trans_id>
<ws:voucher_code>35E7</ws:voucher_code>
<ws:voucher_partner>Chaabi</ws:voucher_partner>
</ws:cancel_voucher>
</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 for the original voucher purchase transaction. |
third_party_trans_id | String | Yes | Partner Transaction ID for the cancellation instruction |
voucher_code | String | Yes | Voucher code to be cancelled |
voucher_partner | String | Yes | Voucher issuer, as per instruction i.e. Wari; Express etc. |
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:cancel_voucherResponse xmlns:ns="http://ws.mfsafrica.com">
<ns:return xsi:type="ax21:Voucher" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ws:mfs_trans_id>6574623423</ws:mfs_trans_id>
<ws:voucher_code>UID234523</ws:voucher_code>
<ax21:code xsi:type="ax21:Code">
<ax21:status_code>MR101</ax21:status_code>
</ax21:code>
<ax21:message>Cancellation of voucher is successful</ax21:message>
</ns:return>
</ns:cancel_voucherResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
mfs_trans_id | String | Yes | MFS Hub transaction ID for the cancellation request |
voucher_code | String | Yes | Voucher code that was cancelled |
status | |||
code | String | Yes | Status code |
message | String | Yes | Status description |
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 Onafriq 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 Onafriq 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 |
get_voucher_status
The get_voucher_status method allows for you to query the cash-out status of successfully executed cash pick-up instruction.
24 hours after successful execution of a cash pick-up instruction, call get_voucher_status. An immediate response will be returned providing the latest cash-pickup status. Where cash pick-up status is not complete, the response will be followed by a call back on the update of the cash-pickup status.
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_voucher_status>
<ws:login>
<xsd:corporate_code> </xsd:corporate_code>
<xsd:password> </xsd:password>
</ws:login>
<ws:mfs_trans_id></ws:mfs_trans_id>
<ws:voucher_code></ws:voucher_code>
<ws:voucher_partner> </ws:voucher_partner>
<ws:urlConfirmation> </ws:urlConfirmation>
</ws:get_voucher_status>
</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. |
voucher_code | String | Yes | Voucher code |
voucher partner | String | Yes | Voucher issuer, as per instruction i.e. Wari; Express etc. |
url | |||
urlConfirmation | String | Yes | This is the URL we call with the voucher cash pick up status. |
Cash pickup reference values
If doing a cash pick-up transaction, see Cash Pickup References for the reference values to use
Response
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:get_voucher_statusResponse xmlns:ns="http://ws.mfsafrica.com">
<ns:return xsi:type="ax21:Voucher" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ax21:code xsi:type="ax21:Code">
<ax21:status_code></ax21:status_code>
</ax21:code>
<ax21:message></ax21:message>
<ax21:mfs_trans_id></ax21:mfs_trans_id>
<ax21:receive_partner> </ax21:receive_partner>
<ax21:voucher_code></ax21:voucher_code>
</ns:return>
</ns:get_voucher_statusResponse>
</soapenv:Body>
</soapenv:Envelope>
Parameters
Field | Type | Required | Description |
---|---|---|---|
mfs_trans_id | String | Yes | MFS transaction id. |
voucher_code | String | Yes | Voucher code |
receive_partner | String | Yes | Voucher issuer |
status | |||
code | String | Yes | Status code |
message | String | Yes | Status description |
Callback
{
"mfs_trans_id":"1529809345626",
"receive_partner":"Wari",
"voucher_code":"156990679",
"status_code":"MR105",
"message":"Cash Pick Up Complete"
}
Status values
MR105 | Cash Pick Up Complete | The voucher cash pick up has been completed. | No further action is required. |
MR106 | Cash Pick Up Pending | The voucher cash pick up has not been completed. | No further action is required. |
MR107 | Cash Pick Up Cancelled | The voucher for cash pick up has been cancelled. | No further action is required. |
Updated 14 days ago