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.

The diagram below shows these three transaction segments.

556556

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.

551551

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

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

cancel_trans

Used to cancel a transaction.

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

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 MFS system

status

status_code

String

The status of the account (if known).
"Active", Not Active", "Not_MNO", "Suspended", "Ambiguous"

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

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

No

Sender’s address

city

String

No

City

date_of_birth

date

No

Sender’s date of birth; YYYY-MM-DD

document

id_number

String

No

Sender’s ID number

id_type

String

No

Possible values:
"PP" - Passport
"ID" - National ID card
"DL" - Driver’s License, where accepted as legal identification

id_country

String

No

Sender’s ID country/nationality

id_expiry

date

No

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

No

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 MFS to screen. Pass/Fail.

sanction_list_sender

String

No

Optionally returned where sender/recipient names have been provided for MFS 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 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

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 MFS 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 MFS Hub or Transaction ID of the sending partner

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>   
        <ns:cancel_transResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax21:EResponse" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax21:message xsi:nil="true"/>
            <ax21:third_party_trans_id xsi:nil="true"/>
         </ns:return>
      </ns:get_trans_statusResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field

Type

Description

mfs_trans_id

String

MFS transaction ID

code

String

Transaction status code of the MFS transaction ID queried. See list of codes.

e_trans_id

String

Where available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.

message

String

Where available, description of the transaction status.

third_party_trans_id

String

Partner transaction ID

get_trans_status

This method is used to query a transaction status.

Where you get an inconclusive result (MR102 or MR 103), you should wait for 10 seconds and call get_trans_status, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a second time, if the result remains MR102 or MR 103 then wait another 10 seconds and call get_trans_status a final third time.

After the third attempt, if still inconclusive (MR102 or MR103), stop calling and log a ticket with MFS Support.

Where you receive a queued transaction result (MR108), you should wait 60 minutes before calling get_trans_status, once per transaction ID. If the result remains MR108, call get_trans_status every 60 minutes, but only once per transaction ID, until you obtain an MR101 or ER response.

See the full list of codes here.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd"> 
   <soapenv:Header/> 
   <soapenv:Body> 
      <ws:get_trans_status> 
         <ws:login> 
            <xsd:corporate_code></xsd:corporate_code> 
            <xsd:password></xsd:password> 
         </ws:login> 
         <ws: trans_id></ws: trans_id> 
      </ws:get_trans_status> 
   </soapenv:Body> 
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

corporate_code

String

Yes

Unique corporate code

password

String

Yes

Secure password provided separately

trans_id

String

Yes

Transaction ID on the MFS Hub or Transaction ID of the sending partner

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> 
   <soapenv:Body> 
      <ns:get_trans_statusResponse xmlns:ns="http://ws.mfsafrica.com"> 
         <ns:return xsi:type="ax21:EResponse" xmlns:ax21="http://mfs/xsd"  
                    xmlns:ax23="http://airtime/xsd"   
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
<ax21:mfs_trans_id xsi:nil="true"/> 
            <ax21:code xsi:nil="true"/> 
            <ax21:e_trans_id xsi:nil="true"/> 
            <ax21:message xsi:nil="true"/> 
<ax21:third_party_trans_id xsi:nil="true"/> 
         </ns:return> 
      </ns:get_trans_statusResponse> 
   </soapenv:Body> 
</soapenv:Envelope>

Parameters

Field

Type

Required

Description

mfs_trans_id

String

Yes

MFS transaction id.

code

String

Yes

Transaction status code of the MFS transaction ID queried. See list of codes here.

e_trans_id

String

Yes

Where available, contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.

message

String

Yes

Status description

third_party_trans_id

String

Yes

Partner transaction ID

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.