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

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.

Retrieve merchant wallets

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

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.

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.

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.

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;
}