VivaISV Class – ISV Integration API Client Reference

Complete reference for VivaISV: constructor options, ISV OAuth and reseller credentials, and the connected account, payment, transaction, source, webhook, and POS modules.

VivaISV is the client class for ISV integrations. It handles connected accounts, payment orders, transaction operations, source codes, POS operations, and webhooks across connected merchants.

Constructor

new VivaISV(options: {
  clientId: string;
  clientSecret: string;
  resellerId?: string;
  resellerApiKey?: string;
  sourceCode?: string | null;
  dev?: boolean;
  logs?: boolean;
})

Import and instantiate the ISV client with your ISV credentials:

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

const vivaIsv = new VivaISV({
  clientId: 'your-isv-client-id',
  clientSecret: 'your-isv-client-secret',
  resellerId: 'your-reseller-id',
  resellerApiKey: 'your-reseller-key',
  dev: false,
});

clientId · string · required

ISV OAuth 2.0 Client ID used to obtain Bearer tokens for ISV API calls.

clientSecret · string · required

ISV OAuth 2.0 Client Secret paired with clientId for token requests.

resellerId · string

Reseller ID used in Viva Basic Auth requests for ISV endpoints that require reseller-level authentication.

resellerApiKey · string

Reseller API Key used as the Basic Auth password. Required alongside resellerId for Basic Auth ISV endpoints.

sourceCode · string | null

Stored on the client for source-code helpers. Pass source codes in method options when an ISV endpoint requires one.

dev · boolean · default: "false"

When true, the client uses VivaWallet demo endpoints for API calls.

logs · boolean · default: "false"

Enables internal SDK error logging when true.

---

Sub-client Modules

Each module is available as a property on the VivaISV instance.

Module	Type	Description
payments	IsvPayments	Create, retrieve, and cancel payment orders on behalf of connected merchants
transactions	IsvTransactions	Retrieve transactions, search Data Services transactions, cancel/refund, payout, recurring, preauth, and MOTO operations
connectedAccounts	IsvConnectedAccounts	Create connected accounts and retrieve account data
source	IsvSourceCode	Create or set ISV source codes
pos	IsvPos	POS devices, transactions, actions, and sessions
webhook / webhooks	IsvWebhook	ISV webhook creation and webhook-key retrieval

webhook and webhooks are aliases for the same IsvWebhook instance.

---

Methods

getCloudTerminalAccessToken()

vivaIsv.getCloudTerminalAccessToken(): Promise<MethodReturn<{
  access_token: string;
  expires_in: number;
  token_type: string;
} | null, 'tokenerror'>>

Calls POST /connect/token with ISV credentials and grant_type=client_credentials, returning VivaWallet’s full token response. Use ISV credentials for ISV Cloud Terminal calls. The SDK does not cache this token.

getVivaWebhookCode()

vivaIsv.getVivaWebhookCode(): Promise<MethodReturn<string | null, 'webhookerror'>>

Deprecated compatibility helper. Prefer vivaIsv.webhook.retrieveWebhookKey().

---

Basic Auth for ISV

Some ISV endpoints require Viva Basic Auth using a Reseller ID and API Key. For these calls, VivaWallet expects:

• Username: resellerId:targetMerchantId
• Password: resellerApiKey

Because targetMerchantId identifies which connected merchant account the operation targets, it is passed per method rather than at construction time:

const result = await vivaIsv.payments.cancelOrder({
  orderCode: 1234567890123456,
  targetMerchantId: 'target-merchant-uuid',
});

Supply resellerId and resellerApiKey in the constructor to enable these Basic Auth calls.