ISV POS Terminal Management and Sessions

Manage POS terminals and initiate Cloud Terminal sessions for connected merchants using the pos module of the VivaISV client and your ISV credentials.

The pos module in VivaISV groups the SDK’s ISV POS and Cloud Terminal helpers. It has three submodules: devices, transactions, and session.

Initialize the ISV client

import { VivaISV } from '@nkhind/vivawallet-sdk';

const vivaIsv = new VivaISV({
  clientId: 'your-isv-client-id',
  clientSecret: 'your-isv-client-secret',
});

The clientId and clientSecret are your ISV-level OAuth 2.0 credentials. POS methods use Bearer token authentication.

Module map

Module	Public methods
vivaIsv.pos.devices	searchDevices(options), deprecated alias getDevices(options)
vivaIsv.pos.transactions	initSale(options), refundTransaction(options), createAction(options), getActionDatas(options)
vivaIsv.pos.session	abortSession(options)

Search POS devices

Use searchDevices() to list devices for a merchant. Filter by device status or source code when needed.

const result = await vivaIsv.pos.devices.searchDevices({
  merchantId: 'target-merchant-uuid',
  statusId: 1,
});

if (result.success) {
  for (const device of result.data) {
    console.log(device.terminalId, device.sourceCode);
  }
}

Start a sale on a terminal

Use initSale() to initiate a POS card-reader sale request.

const result = await vivaIsv.pos.transactions.initSale({
  sessionId: 'session-id',
  terminalId: 'terminal-id',
  cashRegisterId: 'register-1',
  amount: 2500,
  currencyCode: '978',
  merchantReference: 'order-456',
  tipAmount: 0,
  isvDetails: {
    amount: 100,
    terminalMerchantId: 'terminal-merchant-uuid',
    merchantId: 'target-merchant-uuid',
  },
});

if (!result.success) {
  console.error(result.message);
}

Refund a POS transaction

Use refundTransaction() with the original parent session ID.

const result = await vivaIsv.pos.transactions.refundTransaction({
  sessionId: 'refund-session-id',
  parentSessionId: 'original-sale-session-id',
  terminalId: 'terminal-id',
  cashRegisterId: 'register-1',
  amount: 2500,
  currencyCode: '978',
  merchantReference: 'refund-456',
  isvDetails: {
    terminalMerchantId: 'terminal-merchant-uuid',
  },
});

Terminal actions

Use createAction() to schedule a terminal action, then getActionDatas() to retrieve its result.

const actionResult = await vivaIsv.pos.transactions.createAction({
  terminalId: 'terminal-id',
  cashRegisterId: 'register-1',
  actionType: 'aade-fim-control',
  isvDetails: {
    terminalMerchantId: 'terminal-merchant-uuid',
  },
  request: {
    token: 'control-token',
  },
});

if (actionResult.success) {
  const details = await vivaIsv.pos.transactions.getActionDatas({
    actionId: actionResult.data.actionId,
  });
}

Abort a session

Use vivaIsv.pos.session.abortSession() to abort an existing POS session.

const result = await vivaIsv.pos.session.abortSession({
  sessionId: 'session-id',
  cashRegisterId: 'register-1',
});

Cloud Terminal token

When your ISV integration needs Cloud Terminal access, request a token with the parent VivaISV client:

const tokenResult = await vivaIsv.getCloudTerminalAccessToken();

if (tokenResult.success) {
  const { access_token, expires_in } = tokenResult.data;
  console.log(`Token expires in ${expires_in} seconds`);
}

getCloudTerminalAccessToken() does not cache the token. Reuse the returned token until expires_in elapses, then request a new one.