Bank transfer API
Information about our Bank transfer API.
Overview
Our Bank transfer API is powerful and efficient. You have the ability to link a bank account and validate the IBAN at the same time, and you have the ability to be informed of transfer options and associated fees.
To use these APIs, you will need to generate Account Transactions Credentials from your self-care account, as shown below (found in Settings > API Access):
API calls
- Link bank account
- Retrieve bank transfer options
- Create bank transfer fee command
- Execute bank transfer
In order to create a bank transfer to an IBAN, first you need to link the bank account where funds will be transferred to. The “linked bank account” entity consists of an IBAN, the name of the beneficiary and a friendly name
Our API for performing bank transfers consists of the below calls:
- API call “Link bank account” is mandatory, as you first need to link a bank account to execute a bank transfer
- API call “Retrieve bank transfer options” is mandatory only if you need to be informed of the available transfer options (instant or not, shared or ours)
- API call “Create bank transfer fee command” is mandatory only if you want to specify the transfer options or be informed of the fee associated with the bank transfer
The “Retrieve bank transfer options” and “Create bank transfer fee command” API calls are intended for external IBANs only.
They should therefore not be used if referring to a linked IBAN that is in fact an IBAN within Viva (meaning that it is essentially a wallet)
Before you begin
Before you can use some of these API calls you need to “allow transfers between accounts” in the viva banking app:
Sign in to Viva and select the required account.
Go to Settings > API Access.
Select the Allow transfers between accounts checkbox as shown below:
The new setting is saved automatically.
1. Link bank account
Use this API Call to link a bank account. There is no need to use a separate API to confirm the IBAN is valid, as this API will also validate the IBAN account.
The IBAN should belong to a bank account set up in the same currency as your Viva merchant account.
In this response it will be confirmed if the linked IBAN is a Viva account or not via the ‘isVivaIban’ parameter.
Find out more about the Link bank account API call and its parameters
2. Retrieve bank transfer options
Use this API Call to:
- a) Check if this bank account supports instant SEPA transfers
- b) Retrieve the cost options available, i.e. Shared or Ours:
- Shared (SHA) means you only pay your bank’s outgoing transfer charge
- Ours (OUR) instruction means you pay all transfer charges
This API call is intended for external IBANs only.
It should therefore not be used if referring to a linked IBAN that is in fact an IBAN within Viva (meaning that it is essentially a wallet)
Find out more about the Retrieve bank transfer options API call and its parameters
3. Create bank transfer fee command
Use this API Call to specify the transfer options (instant or not, shared or ours) and/or be informed of the fee associated with the bank transfer.
This API call is intended for external IBANs only.
It should therefore not be used if referring to a linked IBAN that is in fact an IBAN within Viva (meaning that it is essentially a wallet)
Find out more about the Create bank transfer fee command API call and its parameters
4. Execute bank transfer
Use this API Call to execute a bank transfer.
If the transfer options are not specified (i.e. ‘bankCommandId’ is not provided), then the transfer will be performed as ‘isInstant’=false and ‘instructionType’=shared.
Upon successful execution of the bank transfer:
- a ‘
commandId’ parameter will be returned in the response and can be used to track the command’s progress (executed, cancelled etc). - a
isInstantparameter will be returned in the response and specify if the bank transfer is instant or not. - a
feeparameter will be returned in the response and if the transaction has an associated fee, this value will be the fee paid by a merchant and does not include any fee the beneficiary of the transfer will pay.
The bank transfer will fail for any of the below indicative reasons:
- Τhe parameter ‘
walletId’ is missing or is not valid - The ‘
bankAccountId’ parameter is missing or is not valid - The currency of the ‘
bankAccountId’ and the currency of the ‘walletId’ are different - The ‘
amount’ parameter is not greater than zero (0) - Insufficient funds in ‘
walletId’. There should be at least as much money available in ‘walletId’ as the proposed transfer amount
The response will contain the ‘fee’ parameter. If the transaction has an associated fee, this value will be the fee paid by a merchant and does not include any fee the beneficiary of the transfer will pay
Find out more about the Execute bank transfer API call and its parameters
Get Support
If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!