> ## Documentation Index
> Fetch the complete documentation index at: https://vivawallet-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## Link a bank account

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

```typescript theme={null}
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`.

```typescript theme={null}
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)`.

```typescript theme={null}
const accountResult = await vivawallet.bankTransfers.retrieveBankAccountById(
  'bank-account-id',
);
```

## Update a bank account

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

```typescript theme={null}
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`.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.