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:

2957 — 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:

556 — 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.

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
email	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
email	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

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
email	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
email	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.