Vivawallet Class – Payments API Client Reference

Complete reference for the Vivawallet class: constructor options, thirteen sub-client modules, and the standalone getSmartCheckout function.

Vivawallet is the primary client class for standard merchant integrations. It exposes typed sub-client modules for payments, transactions, webhooks, fees, wallets, bank transfers, data services, POS helpers, resellers, RF code payments, obligations, source codes, and legacy bank accounts.

Constructor

new Vivawallet(options: {
  clientId: string;
  clientSecret: string;
  merchantId: string;
  apikey: string;
  sourceCode?: string | null;
  dev?: boolean;
  logs?: boolean;
})

Import and instantiate the client with your VivaWallet 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',
  dev: false,
});

clientId · string · required

OAuth 2.0 Client ID used to request Bearer tokens.

clientSecret · string · required

OAuth 2.0 Client Secret paired with clientId for token requests.

merchantId · string · required

Merchant UUID used as the username in Viva Basic Auth requests.

apikey · string · required

API key used as the password in Viva Basic Auth requests.

sourceCode · string | null

Stored on the client for source-code helpers. Pass source codes in method options when a payment or transaction 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 Vivawallet instance and handles one domain of the VivaWallet API.

Module	Type	Description
payments	VivaPayments	Create, retrieve, update, cancel, and create legacy payment orders
transactions	VivaTransactions	Retrieve, create, cancel, refund, rebate, preauth, MOTO, OCT, and legacy transaction operations
webhooks	VivaWebhooks	Add, update, delete, list subscriptions, and retrieve webhook keys
fees	VivaFees	Retrieve fee amounts for payment orders through the Basic Auth fees endpoint
bankTransfers	VivaBankTransfers	Bank account linking, bank transfer options, fees, and outgoing transfers
wallets	VivaWallets	Merchant wallet balances and balance transfers
dataServices	VivaDataServices	Transaction search, MT940 data, sale exports, and account transaction search
pos	VivaPos	Standard Cloud Terminal device, transaction, action, and session helpers
resellers	VivaResellers	Reseller cash, bill, OTP, and order flows
rfCodePayments	VivaRFCodePayments	RF code payment references
obligations	VivaObligations	Payment obligations
source	VivaSourceCode	Payment source-code helpers
legacyBankAccounts	VivaLegacyBankAccounts	Legacy bank account operations

---

Methods

getCloudTerminalAccessToken()

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

Calls POST /connect/token with grant_type=client_credentials and returns VivaWallet’s full token response. The SDK does not cache this token; callers should reuse it until expires_in elapses.

getVivaWebhookCode()

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

Deprecated wrapper around webhooks.retrieveWebhookKey().

---

getSmartCheckout(options)

A standalone named export, not a method on the class. It builds the full SmartCheckout redirect URL for a given order code.

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

const url = getSmartCheckout({
  orderCode: '1234567890123456',
  color: 'FF6600',
  dev: false,
});

Signature:

function getSmartCheckout(options: {
  orderCode: string;
  color?: string;
  paymentMethod?: number;
  dev?: boolean;
}): string

orderCode · string · required

The order code returned by payments.createOrder(), converted to a string.

color · string

Optional color value appended to the SmartCheckout URL.

paymentMethod · number

Optional VivaWallet payment method identifier to pre-select on SmartCheckout.

dev · boolean · default: "false"

When true, constructs a URL pointing to the VivaWallet demo checkout environment.

Returns: string — the fully constructed SmartCheckout redirect URL.