Sync Bank Transfer API

This API is designed for enables Mobile Network Operators (MNOs) to send remittances into bank accounts.

Other types of partners wishing to send funds to bank accounts can utilize our Async Payments API or the Beyonic APIs.

Partners are advised of the success/failure of transactions through synchronous response codes.

This API has three transaction segments:

First validating the bank account
Then logging the transaction request
Then committing the transaction.

The diagram below shows these three transaction segments.

550 — Flow for specifying amount in send currency

Available Methods

Method	Description	Return value
validate_bank_account	Used to validate a bank account and validate the recipient’s name	BankAccount
bank_trans_log	Used to initiate but not execute a money remittance to a bank account providing the send amount as the instruction.	TransactionBank
trans_com	Used to execute a money transaction.	EResponse
cancel_trans	Used to cancel a transaction.	EResponse
get_trans_status	Used to query a transactions status.	EResponse
get_banks	Used for remittances to bank account. This method queries the available bank codes and any relevant rules.	Partner
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

validate_bank_account

This method is used to validate a bank account on the destination platform.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:validate_bank_account>
         <ws:login>
              <xsd:corporate_code>xxxx</xsd:corporate_code>
                 <xsd:password>xxxx</xsd:password>
         </ws:login>
         <ws:payee>
               <xsd:msisdn>xxx</xsd:msisdn>
               <xsd:name>xxx</xsd:name>
         </ws:payee>
         <ws:account>
               <xsd:account_number>xxx</xsd:account_number>
               <xsd:mfs_bank_code>xxx</xsd:mfs_bank_code>
         </ws:account>
         <ws:to_country>xx</ws:to_country>
      </ws:validate_bank_account>
   </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)
*payee*
msisdn	String	Yes	Passed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
name	String	No	The name of the recipient.
*account*
account_number	String	Yes	Recipient’s bank account number.
mfs_bank_code	String	Yes	Unique reference for the bank on the MFS Africa system.

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:validate_bank_accountResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax21:BankAccount" xmlns:ax21="http://mfs/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax21:account_holder_name>xxxxx</ax21:account_holder_name>
            <ax21:account_number>xxx</ax21:account_number>
            <ax21:mfs_bank_code>xxx</ax21:mfs_bank_code>
            <ax21:status xsi:type="ax21:Code">
               <ax21:status_code>MR105</ax21:status_code>
            </ax21:status>
         </ns:return>
      </ns:validate_bank_accountResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field	Type	Required	Description
account_holder_name	String	No	The name of the account holder, where obtained.
account*
account_number	String	Yes	Recipient’s bank account number.
mfs_bank_code	String	Yes	Unique reference for the bank on the MFS system.
*status*
status_code	String	Yes	The status of the enquiry (if known). "Active", Not Active", "Not_MNO", "Suspended", "Ambiguous"

bank_trans_log

This method is used by MNO partners to initialize a remittance transaction to a bank account.

The instruction is given as Send Amount, which MFS Africa uses to calculate Receive Amount which the MFS Africa Hub pays out and depletes the partner's balance in the settlement currency.

Initiated transfer proposals expire daily at 07:30 GMT (where a transfer proposal is aged >30 minutes).
Attempts to execute an expired proposal will trigger an error.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws:bank_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:account>
               <xsd:account_number></xsd:account_number>
               <xsd:mfs_bank_code></xsd:mfs_bank_code>
         </ws:account>
         <ws:third_party_trans_id></ws:third_party_trans_id>
         <ws:reference></ws:reference>
      </ws:bank_trans_log>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field	Type	Required	Description
corporate_code	String	Yes	Unique corporate code
Password	String	Yes	Secure password, that will be separately provided via SMS
*send_amount*
amount	Numeric	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: Refer to Schedule 1.
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)
*account*
account_number	String	Yes	Recipient’s bank account number
mfs_bank_code	String	Yes	Unique reference for the bank on the MFS system
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.

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:bank_trans_logResponse xmlns:ns="http://ws.mfsafrica.com">
         <ns:return xsi:type="ax21:TransactionBank" 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:receive_amount xsi:type="ax21:Money">
               <ax21:amount></ax21:amount>
               <ax21:currency_code/>
            </ax21:receive_amount>
            <ax21:send_amount xsi:type="ax21:Money">
               <ax21:amount></ax21:amount>
               <ax21:currency_code></ax21:currency_code>
            </ax21:send_amount>
            <ax21:third_party_trans_id></ax21:third_party_trans_id>
<ax21:status>
               <ax21:code></code>
               <ax21:message></message>
            </ax21:status>
         </ns:return>
      </ns:bank_trans_logResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field	Type	Description
mfs_trans_id	String	MFS transaction ID
third_party_trans_id	String	Partner transaction ID
receive_amount	Money	Receive amount
fx_rate	Numeric	Retail exchange rate applied to the customer, used to convert send amount to receive amount
*status*
code	String	Transaction status code. See list of codes here.
message	String	No

trans_com

This method is used by partners to execute a transaction for delivery to the destination account.

Initiated transfer proposals expire daily at 07:30 GMT (where a transfer proposal is aged >30 minutes).
Attempts to execute an expired proposal will trigger an error.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mfsafrica.com" xmlns:xsd="http://mfs/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ws: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>

Parameter

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 transaction ID

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, bank_trans_log and airtime_trans_log), but not if executed by trans_com or airtime_trans_com.

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: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:cancel_transResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field	Type	Description
code	String	Transaction status code. See list of codes here.
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.
mfs_trans_id	String	MFS transaction ID
third_party_trans_id	String	Partner transaction ID

get_trans_status

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.

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 here.
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_banks

This method is used in relation to remittances to bank accounts to query available bank destinations and associated rules.

Among other things, get_banks loads the transaction limits that the partner would use to screen its outbound transfers to bank accounts.

Limits are provided in receiving currency and the partner would need to express such limit in sending currency (using the retail/client exchange rate) for the purposes of limit validation.

A partner should call get_banks infrequently (not per transaction) and store the provided banks destinations and associated rules in the output. We recommend once every six months.
get_banks returns banks per to_country. A partner needs to call get_banks for each country it wants to query.

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_banks>
         <ws:login>
               <xsd:corporate_code></xsd:corporate_code>
               <xsd:password></xsd:password>
         </ws:login>
         <ws:to_country></ws:to_country>
      </ws:get_banks>
   </soapenv:Body>
</soapenv:Envelope>

Parameters

Field	Type	Required	Description
corporate_code	String	Yes	Unique corporate code of the requesting partner, assigned by MFS
password	String	Yes	Secure password provided separately
to_country	String	Yes	Destination country code (ISO 3166-2)

Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:get_banksResponse xmlns:ns="http://ws.mfsafrica.com" xmlns:ax21="http://mfs/xsd" xmlns:ax23="http://airtime/xsd">
         <ns:return xsi:type="ax21:Bank" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <ax21:bank_limit xsi:type="ax21:Limit">
               <ax21:max_daily_value>0.0</ax21:max_daily_value>
               <ax21:max_monthly_value>0.0</ax21:max_monthly_value>
               <ax21:max_per_tx_limit>0.0</ax21:max_per_tx_limit>
               <ax21:max_weekly_value>0.0</ax21:max_weekly_value>
               <ax21:min_per_tx_limit>0.0</ax21:min_per_tx_limit>
            </ax21:bank_limit>
            <ax21:bank_name/>
            <ax21:bic/>
            <ax21:country_code></ax21:country_code>
            <ax21:currency_code/>
            <ax21:dom_bank_code/>
            <ax21:iban/>
            <ax21:mfs_bank_code/>
         </ns:return>
      </ns:get_banksResponse>
   </soapenv:Body>
</soapenv:Envelope>

Parameter

Field	Type	Description
*bank_limit*
min_per_tx_limit	Numeric	Bank transfers: Minimum amount that can be received per transaction
max_per_tx_limit	Numeric	Bank transfers: Maximum amount that can be received per transaction
max_daily_value	Numeric	Bank transfers: Maximum aggregate value that can be received per 24-hr period
max_weekly_value	Numeric	Bank transfers: Maximum aggregate value that can be received per rolling 7 days week
max_monthly_value	Numeric	Bank transfers: Maximum aggregate value that can be received per rolling 30 days
bank_name	String	Bank name
bic	String	Bank identifier code, this is the same as SWIFT code
country_code	String	Country code of the bank (ISO 3166-2)
currency_code	String	Currency code of the bank ( ISO 4217)
dom_bank_code	String	Domestic bank code, e.g. Nigerian Bank Code, or UK Sort Code
iban	String	Where relevant, mainly for EU bank accounts
mfs_bank_code	String	Unique reference for the bank on the MFS system

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)