VivaISV Client: Multi-Merchant ISV API Integration

The VivaISV client lets Independent Software Vendors manage merchant payments, connected accounts, and POS terminals across multiple merchants.

The VivaISV class is designed for Independent Software Vendors (ISVs) that manage payments and terminal operations on behalf of multiple merchants. It authenticates with ISV-scoped OAuth credentials for OAuth API calls and optionally accepts reseller credentials for Basic Auth endpoints that target specific merchant accounts.

Initialization

You have two setup options depending on which ISV endpoints you intend to use.

OAuth-only setup

Use this when you only need OAuth 2.0 endpoints such as connected-account creation, payment order creation, transaction lookup, or POS operations:

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

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

With reseller credentials

Add resellerId and resellerApiKey to enable ISV Basic Auth endpoints, such as retrieving or cancelling an order on behalf of a specific merchant:

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

clientId · string · required

Your ISV OAuth 2.0 Client ID.

clientSecret · string · required

Your ISV OAuth 2.0 Client Secret.

resellerId · string

Your Reseller ID, required for ISV Basic Auth endpoints. Used as the first part of the Basic Auth username.

resellerApiKey · string

Your Reseller API Key, used as the Basic Auth password for ISV Basic Auth endpoints.

sourceCode · string

Stored on the client for source helpers. Pass source codes in method options when an ISV payment or transaction endpoint requires one.

Available Modules

payments

Create, retrieve, and cancel payment orders on behalf of target merchants.

transactions

Retrieve ISV transactions, search Data Services transactions, cancel/refund payments, handle preauth, create recurring transactions, and run MOTO charges.

connectedAccounts

Create connected accounts and retrieve connected-account details.

source

Create and set source codes for ISV flows.

pos

Search POS devices, initiate/refund POS transactions, query action data, create terminal actions, and abort sessions.

webhook / webhooks

Create ISV webhooks and retrieve the ISV webhook verification key. Both property names point to the same module.

vivaIsv.webhooks and vivaIsv.webhook refer to the same underlying IsvWebhook instance. Both aliases are supported.

Targeting a Specific Merchant

Some ISV methods target a connected merchant account. OAuth endpoints usually pass that merchant as merchantId or targetMerchantId in the request options. Basic Auth ISV endpoints require reseller credentials and use targetMerchantId to build the composite Basic Auth username.

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

if (result.success) {
  console.log('Order cancelled successfully');
} else {
  console.error('Cancellation failed:', result.message);
}

Calls that use ISV Basic Auth require both resellerId and resellerApiKey to be set on the client. Omitting them returns a typed initerror failure response.

Cloud Terminal with ISV Credentials

When your ISV integration needs Cloud Terminal access, request a token with the ISV 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() returns VivaWallet’s full token response and does not cache it. Reuse the returned token until expires_in elapses, then request a new one.

Related Guides

ISV Payments

Create and manage payment orders across multiple merchant accounts.

ISV Connected Accounts

Onboard and retrieve merchants as connected accounts under your ISV.

ISV POS

Configure terminals and manage POS sessions for ISV-managed devices.