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

# Manage VivaWallet Merchant Wallets and Balance Transfers

> Retrieve merchant wallet balances, access legacy wallet data, and transfer funds between wallets using the wallets module.

Use `vivawallet.wallets` for wallet balance visibility and transfers between Viva wallets. The module exposes three methods: `retrieveMerchantWallets()`, `retrieveWallet()`, and `balanceTransfer(walletId, targetWalletId, options)`.

<Tip>
  For transaction-level reporting, MT940 data, and sale transaction exports, use `vivawallet.dataServices`. The `wallets` module focuses on wallet balances and inter-wallet fund movements.
</Tip>

## Retrieve merchant wallets

Call `retrieveMerchantWallets()` to retrieve wallets set up under the merchant profile through Viva's current OAuth-backed endpoint.

```typescript theme={null}
const result = await vivawallet.wallets.retrieveMerchantWallets();

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

  for (const wallet of wallets) {
    console.log(wallet.walletId, wallet.available, wallet.currencyCode);
  }
}
```

The response exposes lower-camel-case wallet fields such as `walletId`, `iban`, `amount`, `available`, `currencyCode`, and `friendlyName`.

## Retrieve the legacy wallet

Call `retrieveWallet()` for the older Basic Auth wallet endpoint. This is useful when maintaining an existing integration that still depends on the legacy Viva response shape.

```typescript theme={null}
const legacyResult = await vivawallet.wallets.retrieveWallet();

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

  for (const wallet of wallets) {
    console.log(wallet.WalletId, wallet.Available, wallet.CurrencyCode);
  }
}
```

Legacy responses use Viva's older PascalCase fields such as `WalletId`, `Iban`, `Available`, `CurrencyCode`, and `FriendlyName`.

## Transfer balance between wallets

Move funds from one wallet to another with `balanceTransfer(walletId, targetWalletId, options)`. Amounts are expressed in the currency's smallest unit.

```typescript theme={null}
const transferResult = await vivawallet.wallets.balanceTransfer(
  123456,
  789012,
  {
    amount: 1000,
    description: 'Move funds to operating wallet',
    customerTrns: 'Internal wallet transfer',
  },
);

if (transferResult.success && transferResult.data) {
  console.log('Debit transaction:', transferResult.data.DebitTransactionId);
  console.log('Credit transaction:', transferResult.data.CreditTransactionId);
}
```

`walletId` is the source wallet and `targetWalletId` is the destination wallet. Both can be strings or numbers, but they must refer to wallets available to the merchant credentials used by the client.

## Full example

The following pattern retrieves available wallets, picks two wallet IDs, and transfers funds between them.

```typescript theme={null}
import { Vivawallet } from '@nkhind/vivawallet-sdk';

const vivawallet = new Vivawallet({
  clientId: process.env.VIVA_CLIENT_ID!,
  clientSecret: process.env.VIVA_CLIENT_SECRET!,
  merchantId: process.env.VIVA_MERCHANT_ID!,
  apikey: process.env.VIVA_API_KEY!,
});

async function transferBetweenWallets(amount: number) {
  const walletResult = await vivawallet.wallets.retrieveMerchantWallets();

  if (!walletResult.success || !walletResult.data) {
    throw new Error('Failed to retrieve merchant wallets');
  }

  const wallets = Array.isArray(walletResult.data)
    ? walletResult.data
    : [walletResult.data];

  const [sourceWallet, targetWallet] = wallets;

  if (!sourceWallet || !targetWallet) {
    throw new Error('At least two wallets are required for this transfer');
  }

  const transferResult = await vivawallet.wallets.balanceTransfer(
    sourceWallet.walletId,
    targetWallet.walletId,
    { amount },
  );

  if (!transferResult.success) {
    throw new Error('Wallet balance transfer failed');
  }

  return transferResult.data;
}
```