Navigation:

Bank transfer API

Information about our Bank transfer API.

Overview
API calls
Get Support

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

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 isInstant parameter will be returned in the response and specify if the bank transfer is instant or not.
a fee parameter 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!