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:

  1. First validating the bank account
  2. Then logging the transaction request
  3. Then committing the transaction.

The diagram below shows these three transaction segments.

550

Flow for specifying amount in send currency

Available Methods

MethodDescriptionReturn value
validate_bank_account Used to validate a bank account and validate the recipient’s nameBankAccount
bank_trans_logUsed to initiate but not execute a money remittance to a bank account providing the send amount as the instruction.TransactionBank
trans_comUsed to execute a money transaction.EResponse
cancel_transUsed to cancel a transaction.EResponse
get_trans_statusUsed 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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code
password StringYesSecure password provided separately
to_country StringYesDestination country code (ISO 3166-2)
payee
msisdn StringYesPassed in ITU-T E.164 GSM DCS 1800 format, e.g. 250700800900
name StringNoThe name of the recipient.
account
account_numberStringYesRecipient’s bank account number.
mfs_bank_code StringYesUnique 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

FieldTypeRequiredDescription
account_holder_name
StringNoThe name of the account holder, where obtained.
account*
account_number
StringYesRecipient’s bank account number.
mfs_bank_code StringYesUnique reference for the bank on the MFS system.
status
status_code StringYesThe 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

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: Refer to Schedule 1.
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)
account
account_number StringYesRecipient’s bank account number
mfs_bank_code StringYesUnique reference for the bank on the MFS system
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.

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

FieldTypeDescription
mfs_trans_id StringMFS transaction ID
third_party_trans_idStringPartner transaction ID
receive_amountMoneyReceive amount
fx_rate NumericRetail exchange rate applied to the customer, used to convert send amount to receive amount
status
code StringTransaction status code. See list of codes here.
message StringNo

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

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

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

FieldTypeDescription
code StringTransaction status code. See list of codes here.
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.
mfs_trans_id StringMFS transaction ID
third_party_trans_id StringPartner 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

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

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

FieldTypeRequiredDescription
corporate_code StringYesUnique corporate code of the requesting partner, assigned by MFS
password StringYesSecure password provided separately
to_country StringYesDestination 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

FieldTypeDescription
bank_limit
min_per_tx_limit NumericBank transfers: Minimum amount that can be received per transaction
max_per_tx_limit NumericBank transfers: Maximum amount that can be received per transaction
max_daily_value NumericBank transfers: Maximum aggregate value that can be received per 24-hr period
max_weekly_value NumericBank transfers: Maximum aggregate value that can be received per rolling 7 days week
max_monthly_value
NumericBank transfers: Maximum aggregate value that can be received per rolling 30 days
bank_name StringBank name
bicStringBank identifier code, this is the same as SWIFT code
country_codeStringCountry code of the bank (ISO 3166-2)
currency_code StringCurrency code of the bank ( ISO 4217)
dom_bank_code StringDomestic bank code, e.g. Nigerian Bank Code, or UK Sort Code
iban
StringWhere relevant, mainly for EU bank accounts
mfs_bank_code StringUnique 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

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_rate NumericValue 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)