Bank Transfers and Account Linking with VivaWallet

Link bank accounts, retrieve transfer options, create fee commands, and execute outgoing bank transfers using the bankTransfers module.

The bankTransfers module wraps Viva’s current bank transfer endpoints. Use it to link an IBAN, retrieve linked bank accounts, check available transfer options, create a fee command, and execute an outgoing transfer from a Viva wallet.

The current bank transfer methods use OAuth credentials internally. The legacyBankAccounts module is still available for older Basic Auth endpoints.

Link a bank account

Call linkBankAccount(options) with the IBAN and optional labels.

const result = await vivawallet.bankTransfers.linkBankAccount({
  iban: 'GR0000000000000000000000000',
  friendlyName: 'Primary payout account',
  beneficiaryName: 'Acme Ltd',
});

if (result.success && result.data) {
  console.log('Linked account ID:', result.data.bankAccountId);
  console.log('Viva IBAN:', result.data.isVivaIban);
}

Keep the returned bankAccountId; the transfer option, fee, and execution methods all receive it as their first argument.

Retrieve linked bank accounts

Use retrieveBankAccounts(query?) to list linked accounts. The query supports skip, maxResults, iban, isArchived, and bankAccountId.

const accountsResult = await vivawallet.bankTransfers.retrieveBankAccounts({
  maxResults: 20,
  isArchived: false,
});

if (accountsResult.success && accountsResult.data) {
  const accounts = Array.isArray(accountsResult.data)
    ? accountsResult.data
    : [accountsResult.data];

  for (const account of accounts) {
    console.log(account.bankAccountId, account.iban, account.isArchived);
  }
}

To retrieve one account directly, call retrieveBankAccountById(bankAccountId).

const accountResult = await vivawallet.bankTransfers.retrieveBankAccountById(
  'bank-account-id',
);

Update a bank account

Call updateBankAccount(bankAccountId, options) to archive or rename a linked account.

const updateResult = await vivawallet.bankTransfers.updateBankAccount(
  'bank-account-id',
  {
    archive: false,
    friendlyName: 'Primary payout account',
    beneficiaryName: 'Acme Ltd',
  },
);

if (updateResult.success && updateResult.data) {
  console.log(updateResult.data.friendlyName);
}

Retrieve transfer options

Use retrieveBankTransferOptions(bankAccountId, query) before creating a transfer fee command. The query currently requires the transfer amount.

const optionsResult = await vivawallet.bankTransfers.retrieveBankTransferOptions(
  'bank-account-id',
  { amount: 5000 },
);

if (optionsResult.success && optionsResult.data) {
  console.log(optionsResult.data.supportsInstant);
  console.log(optionsResult.data.instructionTypes); // 1 = shared, 2 = ours
}

instructionTypes uses Viva’s numeric values: 1 for shared charges and 2 when you pay all transfer charges.

Create a bank transfer fee command

Use createBankTransferFeeCommand(bankAccountId, options) to calculate and lock the transfer fee for a given wallet, amount, instruction type, and instant-transfer preference.

const feeResult = await vivawallet.bankTransfers.createBankTransferFeeCommand(
  'bank-account-id',
  {
    amount: 5000,
    walletId: 123456,
    instructionType: 1,
    isInstant: false,
  },
);

if (feeResult.success && feeResult.data) {
  console.log('Fee:', feeResult.data.fee);
  console.log('Bank command ID:', feeResult.data.bankCommandId);
}

Pass bankCommandId to executeBankTransfer() when you want to execute the transfer with that quoted fee.

Execute a bank transfer

Call executeBankTransfer(bankAccountId, options) with the source wallet and transfer amount.

const transferResult = await vivawallet.bankTransfers.executeBankTransfer(
  'bank-account-id',
  {
    amount: 5000,
    walletId: 123456,
    description: 'Monthly payout',
    bankCommandId: 'bank-command-id-from-fee-command',
  },
);

if (transferResult.success && transferResult.data) {
  console.log('Command ID:', transferResult.data.commandId);
  console.log('Wallet transaction:', transferResult.data.walletTransactionId);
}

For Viva IBAN destinations the response may include walletTransactionId; for non-Viva IBAN transfers it may include commandId.

Legacy bank accounts

Older integrations can use legacyBankAccounts, which targets Viva’s Basic Auth bank account endpoints. Use it only when maintaining a legacy flow.

const legacyLink = await vivawallet.legacyBankAccounts.linkBankAccount({
  iban: 'GR0000000000000000000000000',
  friendlyName: 'Legacy account',
  beneficiaryName: 'Acme Ltd',
});

const legacyAccounts = await vivawallet.legacyBankAccounts.retrieveBankAccounts();

const legacyTransfer = await vivawallet.legacyBankAccounts.outgoingBankTransfer(
  123456,
  'legacy-bank-account-id',
  {
    amount: 5000,
    description: 'Legacy monthly payout',
    instructionTypeId: 1,
  },
);

The legacy method names and payload casing follow the older Viva API, so keep them separate from the current bankTransfers module when migrating code.