Sync Bank Transfers

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

Other partners wishing to send funds to bank accounts can utilize our Async Payouts product that supports bank payments.

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 the Amount in the 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 transaction's status.	EResponse
get_banks	Used for remittances to bank accounts. 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. The partner can use this rate 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	Your secure password. It will be shared 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	A 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	A unique reference for the bank on the MFS system.
*status*
status_code	String	Yes	The status of the inquiry (if known). One of: - Active - Not Active - Not_MNO - Suspended - Ambiguous

bank_trans_log

MNO partners can use this method 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.

❗️
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: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	Your secure password. It will be shared separately.
*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: Refer to Schedule 1.
id_country	String	Conditional	Sender's ID country/nationality
id_expiry	date	Conditional	The expiry date of the 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. It can be passed as empty if the 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	The 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	A 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 values 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	Designates the retail exchange rate that will be used to convert the "send amount and currency" to the "receive amount and currency."
*status*
code	String	Transaction status code. See list of codes here.
message	String	No

trans_com

Partners can use this method 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	Your secure password. It will be shared 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, it contains a description of the transaction status.
third_party_trans_id	String	Yes	Partner transaction ID

cancel_trans

A transaction 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 transaction 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	Your secure password. It will be shared 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, it contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.
message	String	Where available, it contains a 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	Your secure password. It will be shared 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, it contains the transaction ID of the receiving platform. This is different from the MFS transaction ID.
message	String	Where available, it contains a description of the transaction status.
third_party_trans_id	String	Partner transaction ID

get_banks

Use this method to query available bank destinations and associated rules.

Among other things, get_banks loads the transaction limits 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 limits in "send-currency" (using the retail/client exchange rate) for limit validation.

A partner should call get_banks _infrequently (not per transaction) and store the provided bank destinations and associated rules in the output. We recommend once every six months.
_get_banks returns banks per tocountry. 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	Your secure password. It will be shared 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 seven 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	The bank identifier code. It is the same as the 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	A unique reference for the bank on the MFS system

get_rate

Use this method to query the prevailing forex rate for a currency pair, e.g., from GBP: KES; or KES: UGX.

The forex rate is expressed as one send-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 thrice daily at 7 am, 9 am, and 12 pm GMT. We set rates once daily before 9 am 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	Your secure password. It will be shared 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)

Available Methods

validate_bank_account

Request

Response

bank_trans_log

❗️Note

Request

Response

trans_com

Request

Response

cancel_trans

Request

Response

get_trans_status

Request

Response

get_banks

Request

Response

get_rate

Request

Response

❗️
Note