VivaWallet Node SDK: Authentication and Credentials

Supply your VivaWallet OAuth 2.0 and Basic Auth credentials once at construction time and let the SDK handle all token fetching and header signing.

The SDK keeps authentication details inside the client instance. You provide credentials when you instantiate a client, then SDK methods request OAuth Bearer tokens or build Basic Auth headers as required by each VivaWallet endpoint.

OAuth access tokens are requested internally by OAuth-based methods. The current SDK does not expose or cache a reusable token manager for application code. Cloud Terminal tokens are returned to you explicitly so you can reuse them until expires_in.

Credential Types

VivaWallet uses two authentication mechanisms depending on the endpoint group:

1. OAuth 2.0 — Client ID + Client Secret

Used for SmartCheckout, Acquiring, ISV, Marketplace, Data Services, and POS calls. The SDK exchanges your Client ID and Client Secret for a short-lived Bearer token via POST /connect/token when an OAuth-based method runs.

2. Viva Basic Auth — Merchant ID + API Key

Used for legacy and payment-source endpoints. The SDK base64-encodes your Merchant ID and API Key and sends them as an HTTP Basic Authorization header on each relevant request.

Some ISV endpoints use a reseller-specific Basic Auth variant. For those calls, the username is composed from the Reseller ID and the target merchant ID.

Demo vs Production

Pass dev: true in the client constructor to route API calls through VivaWallet demo endpoints:

const vivawallet = new Vivawallet({
  clientId: process.env.VIVA_CLIENT_ID!,
  clientSecret: process.env.VIVA_CLIENT_SECRET!,
  merchantId: process.env.VIVA_MERCHANT_ID!,
  apikey: process.env.VIVA_API_KEY!,
  dev: true,
});

Use matching demo credentials with dev: true; live credentials and demo credentials are separate.

---

Vivawallet Client Credentials

Instantiate the standard Vivawallet client with merchant OAuth credentials and merchant Basic Auth credentials:

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

const vivawallet = new Vivawallet({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
  sourceCode: 'MY_SOURCE_CODE', // Optional: stored on the client for source helpers
  dev: false,                   // Optional: true uses demo endpoints
});

The required credential fields are:

Field	Description
clientId	OAuth 2.0 Client ID from your VivaWallet application.
clientSecret	OAuth 2.0 Client Secret paired with your clientId.
merchantId	Merchant account UUID, used as the username for Viva Basic Auth endpoints.
apikey	Merchant API key, used as the password for Viva Basic Auth endpoints.

Optional setup fields:

Field	Description
sourceCode	Stored on the client and used by the source-code helper when no source code is passed to that helper. Pass sourceCode in method options when a payment or transaction endpoint requires it.
dev	Uses demo endpoints when true.
logs	Enables internal SDK error logging when true.

---

ISV Client Credentials

The VivaISV client is used by resellers managing connected merchant accounts. It requires ISV OAuth credentials at minimum:

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

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

Add reseller credentials when you need ISV Basic Auth endpoints such as retrieving or cancelling an order on behalf of a target merchant:

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

For ISV endpoints that use Basic Auth, VivaWallet expects the Authorization header to encode Username = Reseller ID:Merchant ID and Password = Reseller API Key. The target merchant ID is passed per method because it identifies the merchant account being acted upon:

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

---

Marketplace Client Credentials

Instantiate the Marketplace client with your platform merchant account’s OAuth and Basic Auth credentials. These are the credentials for your marketplace operator account, not for individual sellers:

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

const marketplace = new Marketplace({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
  dev: false,
});

The Marketplace client uses platform OAuth credentials for Marketplace, Checkout, and Acquiring API calls, while keeping merchant credentials available for Basic Auth helpers such as payment sources and webhooks.

---

Storing Credentials Securely

Always load credentials from environment variables rather than writing them directly into your source code. A .env file excluded from version control, or your deployment platform’s secret manager, is the right place to store them:

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

const vivawallet = new Vivawallet({
  clientId: process.env.VIVA_CLIENT_ID!,
  clientSecret: process.env.VIVA_CLIENT_SECRET!,
  merchantId: process.env.VIVA_MERCHANT_ID!,
  apikey: process.env.VIVA_API_KEY!,
  dev: process.env.VIVA_ENV === 'demo',
});

A minimal .env file to match:

.env

VIVA_CLIENT_ID=your-smartcheckout-client-id
VIVA_CLIENT_SECRET=your-smartcheckout-client-secret
VIVA_MERCHANT_ID=your-merchant-uuid
VIVA_API_KEY=your-api-key
VIVA_ENV=demo

Never hardcode credentials in your source code or commit them to version control. Exposed credentials can be used to process unauthorized transactions or access sensitive financial data on your merchant account.

---

Where to Find Your Credentials

All credentials are available in your VivaWallet merchant dashboard:

• Client ID and Client Secret — Go to Settings → API Access → OAuth 2.0 Credentials and create the relevant application for your integration.
• Merchant ID and API Key — Go to Settings → API Access. Your Merchant ID and API Key are shown under the Basic Authentication section.
• ISV Client ID and Client Secret — Available in the ISV Partner Portal under your ISV application settings.
• Reseller ID and Reseller API Key — Provided by VivaWallet when your reseller account is activated in the ISV program.

If you do not yet have a VivaWallet merchant account, register at vivawallet.com and complete merchant verification before attempting to retrieve credentials.