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

# 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

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

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

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

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

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

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

```typescript theme={null}
const tokenResult = await vivaIsv.getCloudTerminalAccessToken();

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

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