Bank accounts API

Find out more about our API for transfers to external IBANs.

In order to create an outgoing bank transfer, first you need to create a “bank account”. The “bank account” entity is not an actual bank account, but a representation of a bank account, it represents a receiving beneficiary outside Viva Wallet. It consists of an IBAN (external to Viva Wallet), the name of the beneficiary and a friendly name.

Base URL

The live environment has a base URL of https://www.vivapayments.com/.

Authentication

The API calls below use basic auth.

API calls

Our API for managing bank account beneficiaries and performing external bank transfers consists of the following calls:

  1. Validate IBAN
  2. Create bank account
  3. Retrieve bank account details by ID
  4. Retrieve bank accounts
  5. Delete bank account
  6. Retrieve wallets
  7. Create outgoing bank transfer command

1. Validate IBAN

Use this method to ensure that an IBAN is valid.

Request information

get    /api/bankaccounts/ibans/{iban}/validate

URI parameterTypeDescription
ibanstringThe IBAN to validate
Example request
curl --location --request GET 'https://demo.vivapayments.com/api/bankaccounts/ibans/GB73VPAY04002491883585/validate' \
--header 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA=='

Response information

If the IBAN is valid, a JSON response is returned along with a 200 HTTP status code. In the case of an invalid IBAN, the API will return a 400 HTTP error.

{
    "iban": "string",
    "bankName": "string",
    "bankCode": "string",
    "countryCode": "string",
    "accountNumber": "string"
}
Example response (IBAN valid)
{
    "Iban": "GB73VPAY04002491883585",
    "BankName": "VIVA PAYMENTS S.A.",
    "BankCode": "VPAY",
    "BranchCode": "040024",
    "CountryCode": "GB",
    "AccountNumber": "91883585"
}

2. Create bank account

Use this method to create a new beneficiary using an external IBAN. It is recommended to first make sure that the IBAN is valid by using the Validate IBAN API call.

Request information

post    /api/bankaccounts

Example request
curl --location --request POST 'https://demo.vivapayments.com/api/bankaccounts' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "iban": "IBAN of external beneficiary",
    "friendlyName": "A friendly name of your choosing",
    "beneficiaryName": "A beneficiary name of your choosing"
}'

Response information

{
    "iban": "string",
    "bankId": "string",
    "isArchived": "bool",
    "bankAccountId": "uuid",
    "friendlyName": "string",
    "currencyCode": "string",
    "beneficiaryName": "string",
    "verificationRetries": "integer",
    "identificationState": "integer"
}
Example response
{
    "Iban": "GB74VPAY04136031593641",
    "BankId": "NET_VIVAGB",
    "IsArchived": false,
    "BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
    "FriendlyName": "A friendly name of your choosing",
    "CurrencyCode": "826",
    "BeneficiaryName": "A beneficiary name of your choosing",
    "VerificationRetries": 0,
    "IdentificationState": 0
}

3. Retrieve bank account details by ID

Use this method to retrieve a bank account (beneficiary using an external IBAN) by its ID.

Request information

get    /api/bankaccounts/{id}

URI parameterTypeDescription
iduuidThe unique identifier of the bank account.
Example request
curl --location --request GET 'https://demo.vivapayments.com/api/bankaccounts/176d131e-7271-4961-babe-cf6d0461a5ed' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response information

{
    "iban": "string",
    "bankId": "string",
    "isArchived": "bool",
    "bankAccountId": "uuid",
    "friendlyName": "string",
    "currencyCode": "string",
    "beneficiaryName": "string",
    "verificationRetries": "integer",
    "identificationState": "integer"
}
Example response
{
    "Iban": "GB74VPAY04136031593641",
    "BankId": "NET_VIVAGB",
    "IsArchived": false,
    "BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
    "FriendlyName": "A friendly name of your choosing",
    "CurrencyCode": "826",
    "BeneficiaryName": "A beneficiary name of your choosing",
    "VerificationRetries": 0,
    "IdentificationState": 0
}

4. Retrieve bank accounts

Retrieve the bank accounts (beneficiaries using external IBANs) set up under your Viva Wallet profile.

Request information

get    /api/bankaccounts

Example request
curl --location --request GET 'https://demo.vivapayments.com/api/bankaccounts' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response information

[{
    "iban": "string",
    "bankId": "string",
    "isArchived": "bool",
    "bankAccountId": "uuid",
    "friendlyName": "string",
    "currencyCode": "string",
    "beneficiaryName": "string",
    "verificationRetries": "integer",
    "identificationState": "integer"
}, ... ]
Example response
[
    {
        "Iban": "GB74VPAY04136031593641",
        "BankId": "NET_VIVAGB",
        "IsArchived": false,
        "BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
        "FriendlyName": "A friendly name of your choosing",
        "CurrencyCode": "826",
        "BeneficiaryName": "A beneficiary name of your choosing",
        "VerificationRetries": 0,
        "IdentificationState": 0
    },
    {
        "Iban": "GB73VPAY04002491883585",
        "BankId": "NET_VIVAGB",
        "IsArchived": false,
        "BankAccountId": "725ba43e-87a6-4c3f-a544-f250a26e8068",
        "FriendlyName": "Test",
        "CurrencyCode": "826",
        "BeneficiaryName": "Test",
        "VerificationRetries": 0,
        "IdentificationState": 0
    }
]

5. Delete bank account

Use this method to delete a bank account (beneficiary using an external IBAN) by ID.

Request information

delete    /api/bankaccounts/{id}

URI parameterTypeDescription
iduuidThe ID of the bank account.
Example request
curl --location --request DELETE 'https://demo.vivapayments.com/api/bankaccounts/725ba43e-87a6-4c3f-a544-f250a26e8068' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response information

Returns null if successful; 404 error if bank account does not exist to delete.

6. Retrieve wallets

Retrieve all wallets set up under your Viva Wallet profile.

Request information

get    /api/wallets

Example request
curl --location --request GET 'https://demo.vivapayments.com/api/wallets' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response information

[{
    "iban": "string",
    "walletId": "integer",
    "isPrimary": "bool",
    "ammount": "integer",
    "available": "integer",
    "overdraft": "integer",
    "friendlyName": "string",
    "currencyCode": "string"
}, ... ]
Example response
[
    {
        "Iban": "GB73VPAY04002491883585",
        "WalletId": 91883585,
        "IsPrimary": true,
        "Amount": 2.16,
        "Available": -0.29,
        "Overdraft": 0.00,
        "FriendlyName": "Primary",
        "CurrencyCode": "826"
    },
    {
        "Iban": "GB74VPAY04136031593641",
        "WalletId": 31593641,
        "IsPrimary": false,
        "Amount": 345.80,
        "Available": 345.80,
        "Overdraft": 0.00,
        "FriendlyName": "Test",
        "CurrencyCode": "826"
    }
]

7. Create outgoing bank transfer command

For a successful transfer to take place:

Before you can use this API call you need to enable transfers between accounts in the Viva Wallet banking app:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. Go to Settings > API Access.

  3. Select the Allow transfers between accounts checkbox as shown below:

    Allow Transfers
    The new setting is saved automatically.

    You need only do this for the source wallet.

Request information

post    /api/wallets/{walletId}/commands/banktransfer/{bankAccountId}

URI parameterTypeDescription
walletIdlongThe ID of the source wallet, funds will be taken out of this wallet.
bankAccountIdguidTarget beneficiary. This is the bank account created with the IBAN of the receiving party.
Example request
curl --location --request POST 'https://demo.vivapayments.com/api/wallets/197697272601/commands/banktransfer/6e8a43bb-3407-4047-a5e8-ae03c9b8260f' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "100",
    "description": "Bank Transfer"
}'

Response information

{
    "commandId": "uuid"
}