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.

550550

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)