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.

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 |
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 |
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) |
Updated 10 months ago