VivaWallet Node SDK: Overview, Clients, and Concepts

Understand the @nkhind/vivawallet-sdk architecture: choose between the Vivawallet, VivaISV, or Marketplace client and see how typed responses work.

The VivaWallet Node SDK (@nkhind/vivawallet-sdk) is a TypeScript-first wrapper that gives you a typed interface to the VivaWallet payment platform. It covers Standard payments, Marketplace, ISV, POS, webhook, wallet, transfer, and reporting modules through client classes that share the same MethodReturn result shape.

This is a community-maintained SDK and is not officially affiliated with Viva Payments S.A.

What is this SDK?

@nkhind/vivawallet-sdk is a non-official TypeScript wrapper for VivaWallet APIs. Rather than manually constructing HTTP requests and auth headers, you instantiate one of the SDK’s three public client classes with your credentials and call typed async methods directly.

The SDK handles three things for you:

• OAuth token requests — OAuth-based methods request a Bearer token with your client credentials before calling VivaWallet, so application code does not pass tokens manually.
• Basic Auth header construction — for legacy endpoints that use Merchant ID + API Key, the SDK builds and attaches the correct Authorization header automatically.
• Typed responses — every async method returns a MethodReturn<TData, TCode> discriminated union so you always check whether a call succeeded before touching the response data.

Client Classes

Choose the client that matches your integration model. You only need to instantiate the one that fits your use case.

Vivawallet

The standard merchant client. Use it for SmartCheckout payment orders, transaction management, webhooks, fees, bank transfers, wallets, data services, and POS helpers on a single merchant account.

VivaISV

The ISV / reseller client. Use it to manage connected merchant accounts, create payment orders on behalf of sub-merchants, and access ISV-specific POS and cloud terminal endpoints.

Marketplace

The multi-seller platform client. Use it to onboard marketplace sellers, route payments to multiple parties, and transfer funds between seller wallets.

Key Features

• Payment order creation and SmartCheckout redirect via getSmartCheckout()
• Transaction retrieval, cancellation, refund, MOTO, preauth, OCT, and payout operations
• Webhook subscriptions plus receiver helpers for verification responses, Data Services signatures, idempotency, and soft validation
• Fees, bank transfers, wallets, RF code payments, resellers, and data services
• Standard and ISV POS / Cloud Terminal helper modules
• ISV connected account, payment, transaction, source, webhook, and POS modules
• Marketplace sellers, payment orders, transactions, transfers, webhooks, and source management
• Cloud Terminal access-token helper
• TypeScript request and response types exported from the package root for the public SDK surface

TypeScript Support

Every async method in the SDK returns a MethodReturn<TData, TCode> discriminated union. When result.success is true, the result.data property is typed for that specific endpoint. When result.success is false, you get a structured error with a message and a typed code.

const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #42',
});

if (result.success) {
  // result.data is fully typed here
  console.log(result.data.orderCode);
} else {
  // result.message and result.code are available on failure
  console.error(result.message, result.code);
}

This pattern means you do not need to use try/catch for expected API failures. The SDK converts them into typed failure values in the discriminated union.

Environments

VivaWallet provides two environments:

Environment	Purpose
Production	Live transactions against real merchant accounts
Demo	Sandbox testing with test credentials and amounts

Pass dev: true when constructing a client to make that client use the VivaWallet demo endpoints for API calls.

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,
});

getSmartCheckout() also accepts dev: true, because the redirect URL is built independently from the client instance.

const checkoutUrl = getSmartCheckout({
  orderCode: String(orderCode),
  dev: true,
});