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.

To enable mobile wallet remittances as an MNO, including cash pick-ups, you can use these methods. If you are not an MNO, check out our Async Payments API

This API has three segments:

  1. First validating the account
  2. Then logging the transaction request
  3. 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

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

551

Get rate API

Available Methods

MethodDescriptionReturn value
account_requestUsed to check the existence and status of the receiving account on the destination platform.Account
cancel_transUsed to cancel a transaction.EResponse
cancel_voucherUsed to cancel a purchased cash pick-up voucher.EResponse
get_trans_statusUsed to query a transactions status.EResponse
get_voucher_statusUsed 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_statusUsed 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
to_country StringYesDestination country code (ISO 3166-2)
msisdn StringYesPassed 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

FieldTypeDescription
msisdn StringReturned in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
partner_code StringUnique reference for the destination partner on the MFS system
status
status_code StringThe 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 MFS 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.

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

FieldTypeRequiredDescription
corporate_codeStringYesUnique corporate code
PasswordStringYesSecure password, that will be separately provided via SMS
send_amount
amountNumericYesSend amount
currency_codeStringYesSend amount currency code (ISO 4217)
fee
amountNumericYesSending fee amount
currency_codeStringYesFee currency code (ISO 4217)
sender
addressStringNoSender’s address
cityStringNoSender’s city
date_of_birthdateNoSender’s date of birth; YYYY-MM-DD
document
id_numberStringNoSender’s ID number
id_typeStringNoPossible values:
"PP" - Passport
"ID" - National ID card
"DL" - Driver’s License, where accepted as legal identification
id_countryStringNoSender’s ID country/nationality (ISO 3166-2)
id_expirydateNoExpiry date of sender’s ID; YYYY-MM-DD
emailStringNoSender’s email
from_countryStringYesSend country (ISO 3166-2)
msisdnStringYesSender’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.
nameStringYesSender first name
postal_codeStringNoPostal code
stateStringNoState
surnameStringYesSender surname
recipient
addressStringNoRecipient address
cityStringNoCity
date_of_birthdateNoRecipient date of birth; YYYY-MM-DD
documentString
id_numberStringNoRecipient ID number
id_typeStringNoPossible values: Refer to Schedule 1.
id_countryStringNoRecipient ID country/nationality
id_expirydateNoExpiry date of Recipient ID; YYYY-MM-DD
emailStringNoRecipient email
msisdnStringYesRecipient mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
nameStringYesRecipient first name
postal_codeStringNoPostal code
stateStringNoState
status
status_codeStringYesLeave blank
surnameStringYesRecipient surname
to_countryStringYesDestination country (ISO 3166-2)
third_party_trans_idStringYesTransaction ID of the sending partner
referenceString (50 chars)NoA 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

FieldTypeRequiredDescription
fx_rateNumericYesRetail exchange rate applied to the customer, used to convert send amount to receive amount
mfs_trans_idStringYesMFS transaction ID
name_matchStringNoOptionally returned. Name match (fuzzy) of recipient name as provided by sending partner, with the registered name on receiving platform (where possible).
partner_codeStringYesReceiving partner code
receive_amountNumeric
amountNumericYesReceive amount
currency_codeStringYesReceive amount currency code (ISO 4217)
sanction_list_recipientStringNoOptionally returned where sender/recipient names have been provided for MFS to screen. Pass/Fail.
sanction_list_senderStringNoOptionally returned where sender/recipient names have been provided for MFS to screen. Pass/Fail.
third_party_trans_idStringYesPartner transaction ID
status
codeStringNoStatus code. See list of codes here.
messageStringNoStatus 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 MFS uses to calculate the Receive Amount, which the MFS 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.

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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
Password StringYesSecure password, that will be separately provided via SMS
send_amount
amount NumericYesSend amount
currency_code StringYesSend amount currency code (ISO 4217)
fee
amount NumericYesSending fee amount
currency_code StringYesFee currency code (ISO 4217)
sender
address StringNoSender’s address
city StringNoCity
date_of_birth dateNoSender’s date of birth; YYYY-MM-DD
document
id_number StringNoSender’s ID number
id_type StringNoPossible values:
"PP" - Passport
"ID" - National ID card
"DL" - Driver’s License, where accepted as legal identification
id_country StringNoSender’s ID country/nationality
id_expiry dateNoExpiry date of sender’s ID; YYYY-MM-DD
email StringNoSender’s email
from_country StringYesSend country (ISO 3166-2)
msisdn StringYesSender’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 StringYesSender first name
postal_code StringNoPostal code
state StringNoState
surname StringYesSender surname
recipient
address StringNoRecipient address
city StringNoCity
date_of_birth dateNoRecipient date of birth; YYYY-MM-DD
document
id_number StringNoRecipient ID number
id_type StringNoPossible values: Refer to Schedule 1.
id_country StringNoRecipient ID country/nationality
id_expiry dateNoExpiry date of Recipient ID; YYYY-MM-DD
email StringNoRecipient email
msisdn StringYesRecipient mobile number passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
name StringYesRecipient first name
postal_code StringNoPostal code
state StringNoState
status
status_code StringYesLeave blank
surname StringYesRecipient surname
to_country StringYesDestination country (ISO 3166-2)
third_party_trans_id StringYesTransaction ID of the sending partner
referenceString (50 chars)NoA 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

FieldTypeRequiredDescription
fx_rate NumericYesRetail exchange rate applied to the customer, used to convert send amount to receive amount
mfs_trans_id StringYesMFS transaction ID
name_match StringNoOptionally returned. Name match (fuzzy) of recipient name as provided by sending partner, with the registered name on receiving platform (where possible).
partner_code StringYesReceiving partner code
receive_amount
amount NumericYesReceive amount
currency_code StringYesReceive amount currency code (ISO 4217)
sanction_list_recipient StringNoOptionally returned where sender/recipient names have been provided for MFS to screen. Pass/Fail.
sanction_list_sender StringNoOptionally returned where sender/recipient names have been provided for MFS to screen. Pass/Fail.
third_party_trans_id StringYesPartner transaction ID
status
code StringNoStatus code. See list of codes here.
message StringNoStatus 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
trans_id StringYesTransaction 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: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

FieldTypeRequiredDescription
mfs_trans_id StringYesMFS transaction ID
code StringYesTransaction status code. See list of codes here.
e_trans_id StringYesTransaction ID of the receiving platform
In the case of cash pick-up remittances, this value will be the voucher number
message StringNoWhere available, description of the transaction status.
third_party_trans_id StringYesPartner'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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
to_country StringYesDestination country (ISO 3166-2)
from_currency StringYesSend currency code (ISO 4217)
to_currency StringYesReceive 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

FieldTypeDescription
Per Partner
from_currency StringSend currency code (ISO 4217)
fx_rateNumericValue of the exchange rate
partner_code StringUnique reference code for the partner on the MFS system
time_stamp DatetimeTimestamp of the forex rate, in YYYY-MM-DD HH:MM:SS (GMT)
to_currency StringReceive 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
trans_id StringYesTransaction 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

FieldTypeDescription
mfs_trans_id StringMFS transaction ID
code StringTransaction status code of the MFS transaction ID queried. See list of codes.
e_trans_id StringWhere available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.
message StringWhere available, description of the transaction status.
third_party_trans_id StringPartner 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

FieldTypeRequiredDescription
corporate_codeStringYesUnique corporate code
passwordStringYesSecure password provided separately
mfs_trans_idStringYesMFS transaction ID for the original voucher purchase transaction.
third_party_trans_idStringYesPartner Transaction ID for the cancellation instruction
voucher_codeStringYesVoucher code to be cancelled
voucher_partnerStringYesVoucher 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

FieldTypeRequiredDescription
mfs_trans_idStringYesMFS Hub transaction ID for the cancellation request
voucher_codeStringYesVoucher code that was cancelled
status
codeStringYesStatus code
messageStringYesStatus 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 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
trans_idStringYesTransaction 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

FieldTypeRequiredDescription
mfs_trans_id StringYesMFS transaction id.
codeStringYesTransaction status code of the MFS transaction ID queried. See list of codes here.
e_trans_idStringYesWhere available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.
message StringYesStatus description
third_party_trans_idStringYesPartner 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
mfs_trans_id StringYesMFS transaction id.
voucher_code StringYesVoucher code
voucher partner StringYesVoucher issuer, as per instruction i.e. Wari; Express etc.
url
urlConfirmation StringYesThis 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

FieldTypeRequiredDescription
mfs_trans_id StringYesMFS transaction id.
voucher_codeStringYesVoucher code
receive_partnerStringYesVoucher issuer
status
code StringYesStatus code
message StringYesStatus description

Callback

{
  "mfs_trans_id":"1529809345626",
  "receive_partner":"Wari",
  "voucher_code":"156990679",
  "status_code":"MR105",
  "message":"Cash Pick Up Complete"
}

Status values

MR105Cash Pick Up CompleteThe voucher cash pick up has been completed.No further action is required.
MR106Cash Pick Up PendingThe voucher cash pick up has not been completed.No further action is required.
MR107Cash Pick Up CancelledThe voucher for cash pick up has been cancelled.No further action is required.