Installing the VivaWallet Node SDK in Your Project

Add @nkhind/vivawallet-sdk to your Node.js project with npm, yarn, or pnpm, then import client classes and TypeScript types from the package root.

@nkhind/vivawallet-sdk is published to the public npm registry and works in any Node.js project that supports TypeScript. Install it once, import the client you need, and you are ready to make authenticated API calls — no additional HTTP client or token-management setup required.

Requirements

Before installing, make sure your environment meets the following minimum versions:

Requirement	Minimum version
Node.js	16.x or later
TypeScript	4.x or later (recommended for full discriminated-union support)

Install

npm

npm install @nkhind/vivawallet-sdk

yarn add @nkhind/vivawallet-sdk

pnpm add @nkhind/vivawallet-sdk

NPM package

View the package on npm to check the latest published version, package metadata, and registry details.

Import the clients

The SDK exports each client class as a named export from the package root. Import only the clients you need:

import { Vivawallet } from '@nkhind/vivawallet-sdk';    // Standard merchant
import { VivaISV } from '@nkhind/vivawallet-sdk';        // ISV / reseller
import { Marketplace } from '@nkhind/vivawallet-sdk';    // Multi-seller platform

// Utility helper for building SmartCheckout redirect URLs
import { getSmartCheckout } from '@nkhind/vivawallet-sdk';

getSmartCheckout is a synchronous helper that builds the VivaWallet hosted-checkout redirect URL from a payment order code. It accepts an orderCode (string), an optional dev flag for the demo environment, and optional color and paymentMethod query parameters:

const checkoutUrl = getSmartCheckout({
  orderCode: String(result.data.orderCode), // returned by payments.createOrder()
  dev: false,                         // true → routes to demo checkout
  color: 'FF6600',                    // optional: brand colour (hex, no #)
  paymentMethod: 0,                   // optional: pre-select a payment method
});

// Redirect the user to this URL to complete payment
res.redirect(checkoutUrl);

Import TypeScript types

The SDK exports its public client classes, helper functions, and many public TypeScript types from the package root. Use those exports to type webhook payloads, method responses, and request bodies in your own code:

import type {
  VivaWebhookDatas,
  SmartCheckoutWebhookEventDatas,
  ConnectedAccountWebhookEventDatas,
} from '@nkhind/vivawallet-sdk';

// Type your Express (or any framework) webhook handler body directly:
app.post('/webhooks/viva', (req, res) => {
  const payload: VivaWebhookDatas<SmartCheckoutWebhookEventDatas> = req.body;

  console.log(payload.EventData.TransactionId);
  res.sendStatus(200);
});

Import public SDK types from @nkhind/vivawallet-sdk first. Avoid relying on internal package subpaths unless a type is intentionally exposed there by a future SDK release.

Verifying your setup

Create a minimal script to confirm the package is installed and your TypeScript configuration can resolve the module. No real API credentials or network calls are needed for this check:

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

// Instantiate the client — this does not make any network requests
const vivawallet = new Vivawallet({
  clientId: 'test-client-id',
  clientSecret: 'test-client-secret',
  merchantId: 'test-merchant-id',
  apikey: 'test-api-key',
});

console.log('VivaWallet SDK loaded successfully:', typeof vivawallet);
// → VivaWallet SDK loaded successfully: object

If this compiles and runs without errors, your installation is working correctly. Replace the placeholder strings with your real credentials (ideally from environment variables — see Authentication) when you are ready to make live or demo API calls.