Create and Manage Payments via VivaWallet SmartCheckout

Create payment orders, redirect customers to SmartCheckout, retrieve fees, and manage the full order lifecycle using the VivaWallet payments and fees modules.

The standard payment flow has three steps: create a payment order on your server, redirect the customer to SmartCheckout with the returned orderCode, then confirm the outcome through webhooks or an order lookup. These operations live under vivawallet.payments.

All monetary amounts are expressed in the smallest currency unit. For EUR that means cents: pass 1000 for EUR 10.00.

Create a Payment Order

Call createOrder(orderData) to register a new payment intent with VivaWallet. On success, result.data.orderCode contains the code you need to build the checkout URL.

const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #1234',
  customer: {
    email: '[e-mail]',
    fullName: 'John Doe',
    phone: '[phone]',
    requestLang: 'en-GB',
  },
  sourceCode: 'DEFAULT',
  allowRecurring: false,
  maxInstallments: 0,
});

if (!result.success) {
  console.error(result.message);
  return;
}

const { orderCode } = result.data;

Common createOrder() fields:

Field	Required	Description
amount	Yes	Payment amount in the smallest currency unit.
customerTrns	No	Friendly payment description shown to the customer.
customer.email	No	Customer email address.
customer.fullName	No	Customer full name.
customer.phone	No	Customer phone number.
customer.requestLang	No	Checkout language/locale, for example en-GB.
sourceCode	No	Payment source code for this order.
allowRecurring	No	Allows recurring payments for the order.
maxInstallments	No	Maximum number of installments to offer.

Redirect to SmartCheckout

Once you have an orderCode, use the getSmartCheckout helper to build the hosted checkout URL and redirect your customer to it.

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

const checkoutUrl = getSmartCheckout({
  orderCode: String(orderCode),
  color: '0000FF', // Optional: hex color, without '#'
  dev: false,      // Set true to use the demo checkout URL
});

res.redirect(checkoutUrl);

getSmartCheckout() is a standalone helper exported from the package root. Its dev flag only affects the checkout URL it builds. API calls use demo endpoints when the client itself was constructed with dev: true.

Retrieve an Order

After the customer completes or abandons checkout, retrieve the order to inspect its current state. The SDK method takes the orderCode directly, not an options object.

const orderResult = await vivawallet.payments.getOrder(orderCode);

if (orderResult.success) {
  const order = orderResult.data;
  console.log(order.stateId);
  console.log(order.requestAmount);
}

Cancel a Payment Order

Cancel an unpaid order to prevent the customer from completing it. This is useful when your session expires or the cart contents change.

const cancelResult = await vivawallet.payments.cancelOrder(String(orderCode));

if (cancelResult.success) {
  console.log('Order cancelled');
}

Update a Payment Order

You can update certain fields on an existing unpaid order, such as amount or customer-facing text, using updateOrder(orderCode, options).

const updateResult = await vivawallet.payments.updateOrder(orderCode, {
  amount: 2000,
  customerTrns: 'Updated Order #1234',
});

if (!updateResult.success) {
  console.error(updateResult.message);
}

Retrieve Payment Fees

Use vivawallet.fees.retrieveFees(options) when you need Viva’s fee calculation for a payment order amount. This method uses the legacy Basic Auth fee endpoint, so the client must be initialized with merchantId and apikey.

const fees = await vivawallet.fees.retrieveFees({
  orderCode: String(orderCode),
  amount: 1000,
});

if (fees.success && fees.data) {
  console.log(fees.data.Fee);
  console.log(fees.data.ServiceFee);
  console.log(fees.data.TotalConversionFee);
}

VivaFeesReturn mirrors Viva’s response fields, including Fee, BillFee, ServiceFee, ResellerFee, CollectionFee, and TotalConversionFee when returned by the API.

Create a Legacy Payment Order

For older integrations that use VivaWallet’s Basic Auth payment API, use createLegacyOrder(orderData). This method targets the legacy endpoint and requires merchantId and apikey credentials on your client.

const legacyResult = await vivawallet.payments.createLegacyOrder({
  amount: 1000,
  customerTrns: 'Order #1234',
  email: '[e-mail]',
  fullName: 'John Doe',
  phone: '[phone]',
  requestLang: 'en-GB',
});

if (legacyResult.success) {
  const { orderCode } = legacyResult.data;
}

Prefer createOrder() for new integrations. It uses the OAuth-based Checkout v2 order endpoint and returns the SDK’s normalized { orderCode } response.