Vivawallet Client: Standard Merchant API Integration

The Vivawallet client covers payments, transactions, webhooks, fees, bank transfers, wallets, data services, POS helpers, and more for standard merchants.

The Vivawallet class is the main entry point for standard merchant integrations. Once instantiated with your credentials, it exposes typed sub-clients for payments, transactions, webhooks, fees, bank transfers, wallets, data services, POS helpers, reseller flows, RF code payments, obligations, payment sources, and legacy bank-account operations.

Initialization

Pass your OAuth credentials together with your merchant Basic Auth credentials. The SDK uses the right authentication method for each API call.

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: used by source helpers
  dev: false,                   // Optional: true uses demo endpoints
});

clientId · string · required

Your OAuth 2.0 Client ID, used for Bearer-token API calls.

clientSecret · string · required

Your OAuth 2.0 Client Secret.

merchantId · string · required

Your merchant UUID, used as the username in Viva Basic Auth endpoints.

apikey · string · required

Your merchant API key, used as the password in Viva Basic Auth endpoints.

sourceCode · string

Stored on the client for source-code helpers. Pass sourceCode in method options when a payment or transaction endpoint requires one.

dev · boolean

When true, the client uses VivaWallet demo endpoints for API calls.

logs · boolean

Enables internal SDK error logging when true.

Available Modules

After instantiation, all sub-clients are available as properties of the Vivawallet instance:

payments

Create, retrieve, update, cancel, and create legacy payment orders.

transactions

Retrieve, cancel, refund, rebate, tokenize, MOTO, preauth, OCT, and legacy transaction operations.

webhooks

Add, update, delete, and list webhook subscriptions. Retrieve webhook verification keys.

fees

Retrieve fee amounts for payment orders through the Basic Auth fees endpoint.

bankTransfers

Link bank accounts, retrieve transfer options, create transfer fees, and execute outgoing transfers.

wallets

Merchant wallet balances and balance transfers between Viva accounts.

dataServices

Transaction search, MT940 exports, sale transaction exports, and account transaction search.

pos

Standard Cloud Terminal helpers for device search, POS transactions, terminal actions, and session management.

resellers

Reseller payment flows including cash, bill, OTP, and reseller order creation.

rfCodePayments

Generate RF code payment references.

obligations

Create payment obligations tied to specific amounts and references.

source

Create or set payment source codes associated with your merchant account.

legacyBankAccounts

Legacy bank account linking and outgoing transfer operations.

Usage Example

Each sub-client method returns a typed MethodReturn result object:

const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #42',
  customer: {
    email: '[e-mail]',
    requestLang: 'en-GB',
  },
  merchantTrns: 'internal-ref-42',
});

if (result.success) {
  console.log('Order code:', result.data.orderCode);
} else {
  console.error('Error:', result.message);
}

getSmartCheckout Helper

After creating a payment order, redirect your customer to the VivaWallet SmartCheckout page using the standalone getSmartCheckout() function. This function constructs the full redirect URL from the order code and optional display options.

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

const url = getSmartCheckout({
  orderCode: '1234567890123456',
  color: '0000FF', // Optional: hex color, without '#'
  dev: false,      // Optional: use demo checkout URL
});

res.redirect(url);

orderCode · string · required

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

color · string

Optional color value passed to VivaWallet for the checkout UI.

paymentMethod · number

Optional VivaWallet payment method identifier to pre-select on the checkout page.

dev · boolean

When true, the URL points to the VivaWallet demo checkout environment instead of production.

getSmartCheckout() returns the full SmartCheckout URL as a string.

Demo Environment

Pass dev: true when constructing the Vivawallet client to route API calls to VivaWallet demo endpoints. getSmartCheckout() also accepts dev: true, because the checkout redirect URL is built independently from the client instance.

const vivawallet = new Vivawallet({
  clientId: 'demo-client-id',
  clientSecret: 'demo-client-secret',
  merchantId: 'demo-merchant-id',
  apikey: 'demo-api-key',
  dev: true,
});

const url = getSmartCheckout({
  orderCode: '1234567890123456',
  dev: true,
});

Demo credentials are separate from live credentials. Use matching demo credentials when the client is created with dev: true.

Related Guides

Payments

Learn how to create, retrieve, update, and cancel payment orders.

Transactions

Cancel, refund, and inspect transaction details.

Webhooks

Manage webhook subscriptions and type incoming events.

Webhook Helpers

Verify, deduplicate, and soft-validate incoming webhook deliveries.

Cloud Terminal

Search POS devices, initiate terminal requests, and manage sessions.

Bank Transfers

Link bank accounts and execute outgoing fund transfers.

Wallets

Check balances and move funds between merchant wallets.