Cloud Terminal and Standard POS Helpers

Use Cloud Terminal tokens and the standard Vivawallet POS helper modules to search devices, initiate POS transactions, retrieve sessions, and abort sessions.

The VivaWallet Cloud Terminal / ECR API lets a backend send card-present payment requests to physical POS terminals. The SDK exposes two layers for standard merchant integrations:

• getCloudTerminalAccessToken() returns Viva’s raw Cloud Terminal token response so you can manage caching yourself.
• vivawallet.pos wraps common Cloud Terminal operations and requests a Cloud Terminal token internally for each SDK call.

Cloud Terminal credentials are separate from SmartCheckout credentials in many Viva setups. Use the Client ID and Client Secret intended for POS / Cloud Terminal access when calling these helpers.

Get a Cloud Terminal Access Token

Call getCloudTerminalAccessToken() when you need to call a Cloud Terminal endpoint not yet wrapped by the SDK.

const tokenResult = await vivawallet.getCloudTerminalAccessToken();

if (tokenResult.success && tokenResult.data) {
  const { access_token, expires_in } = tokenResult.data;
  console.log(access_token, expires_in);
}

Internally, this calls POST /connect/token with grant_type=client_credentials. The SDK does not cache this token; reuse it until expires_in seconds have elapsed, then request a new one.

A simple token-caching wrapper:

let cachedToken: string | null = null;
let tokenExpiry = 0;

async function getActiveCloudTerminalToken(): Promise<string> {
  const now = Math.floor(Date.now() / 1000);

  if (cachedToken && now < tokenExpiry - 30) {
    return cachedToken;
  }

  const result = await vivawallet.getCloudTerminalAccessToken();

  if (!result.success || !result.data) {
    throw new Error(result.message);
  }

  cachedToken = result.data.access_token;
  tokenExpiry = now + result.data.expires_in;

  return cachedToken;
}

Standard POS Module

vivawallet.pos groups standard merchant Cloud Terminal helpers into three submodules:

Module	Methods
vivawallet.pos.devices	searchDevices(options?)
vivawallet.pos.transactions	initiateSaleRequest(), capturePreAuthRequest(), refundTransaction(), unreferencedRefund(), fastRefund(), rebate(), createAction(), getActionDetails()
vivawallet.pos.session	retrieveSessionById(), retrieveSessionInfoByDate(), abortSession()

Each wrapped method internally calls getCloudTerminalAccessToken() and returns the SDK’s normal MethodReturn result. These calls do not share a token cache; add your own wrapper if your application needs token reuse across many POS requests.

Search POS Devices

Use searchDevices(options?) to list terminals available to the merchant credentials. You can filter by statusId or sourceCode.

const devices = await vivawallet.pos.devices.searchDevices({
  statusId: 1,
  sourceCode: 'STORE-ATHENS',
});

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

Use terminalId from this response when creating sale, refund, action, or session-related requests.

Initiate a Sale Request

Use initiateSaleRequest(options) to send a payment request to a terminal. The SDK returns data: null when Viva accepts the asynchronous request; use session retrieval or webhooks to observe the final result.

const result = await vivawallet.pos.transactions.initiateSaleRequest({
  sessionId: 'session-1234',
  terminalId: 'terminal-1234',
  cashRegisterId: 'register-1',
  amount: 1000,
  currencyCode: '978',
  merchantReference: 'order-1234',
  customerTrns: 'Order #1234',
  showTransactionResult: true,
  showReceipt: true,
  tipAmount: 0,
});

if (!result.success) {
  throw new Error(result.message);
}

POS Transaction Operations

The transaction helpers share the same base POS request shape: sessionId, terminalId, cashRegisterId, amount, currencyCode, and merchantReference, plus operation-specific fields.

Method	Use
capturePreAuthRequest(options)	Capture a previous pre-authorization; pass parentSessionId.
refundTransaction(options)	Refund a referenced transaction; pass parentSessionId.
unreferencedRefund(options)	Send a refund request not tied to a previous session.
fastRefund(options)	Send a fast refund request through Cloud Terminal.
rebate(options)	Send a rebate request through Cloud Terminal.

await vivawallet.pos.transactions.refundTransaction({
  sessionId: 'refund-session-1234',
  parentSessionId: 'sale-session-1234',
  terminalId: 'terminal-1234',
  cashRegisterId: 'register-1',
  amount: 1000,
  currencyCode: '978',
  merchantReference: 'refund-order-1234',
});

Terminal Actions

Use createAction(options) for terminal actions such as aade-fim-control, then retrieve the action status with getActionDetails(options).

const action = await vivawallet.pos.transactions.createAction({
  terminalId: 'terminal-1234',
  cashRegisterId: 'register-1',
  actionType: 'aade-fim-control',
  request: {
    command: 'status',
  },
});

if (action.success && action.data) {
  const details = await vivawallet.pos.transactions.getActionDetails({
    actionId: action.data.actionId,
  });

  console.log(details.data?.successfullyProcessed);
}

Retrieve and Abort Sessions

Retrieve one POS session by ID:

const session = await vivawallet.pos.session.retrieveSessionById({
  sessionId: 'session-1234',
});

if (session.success && session.data) {
  console.log(session.data.transactionId, session.data.success);
}

List sessions for a date:

const sessions = await vivawallet.pos.session.retrieveSessionInfoByDate({
  date: '2026-07-03',
  AadeAutonomouslyOnly: false,
});

Abort an active session:

await vivawallet.pos.session.abortSession({
  sessionId: 'session-1234',
  cashRegisterId: 'register-1',
});

ISV POS

For ISV integrations, use the VivaISV POS module instead. See ISV POS for vivaIsv.pos.devices, vivaIsv.pos.transactions, and vivaIsv.pos.session examples.

Webhook Follow-up

Cloud Terminal sessions can be followed through POS session webhooks. Use validateVivaPosSessionWebhook() from the Webhook Helpers guide when processing POS ECR session created or failed notifications.