ISV Payment Orders: Create and Cancel on Behalf of Merchants

Create and cancel VivaWallet payment orders on behalf of your connected merchants using the VivaISV payments module and your ISV credentials.

As an ISV, you can create and manage payment orders for merchants connected to your ISV account. The VivaISV client’s payments module exposes three public methods: createOrder(), getOrder(), and cancelOrder().

Setup

Instantiate VivaISV with your ISV OAuth credentials. Add reseller credentials when you need Basic Auth endpoints such as order retrieval or cancellation.

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

const vivaIsv = new VivaISV({
  clientId: 'your-isv-client-id',
  clientSecret: 'your-isv-client-secret',
  resellerId: 'your-reseller-id',
  resellerApiKey: 'your-reseller-api-key',
});

Create a payment order

Use vivaIsv.payments.createOrder(merchantId, orderData) to create a payment order on behalf of a connected merchant. The first argument is the target merchant ID. The second argument is the ISV payment-order payload.

const result = await vivaIsv.payments.createOrder('target-merchant-uuid', {
  amount: 2500,
  customerTrns: 'Invoice #456',
  customer: {
    email: '[e-mail]',
    fullName: 'Jane Smith',
    phone: '[phone]',
    requestLang: 'en-GB',
  },
});

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

const { orderCode } = result.data;

Use getSmartCheckout({ orderCode: String(orderCode) }) to build the redirect URL exactly as you would for a standard payment order.

Retrieve a payment order

getOrder() uses the ISV Basic Auth flow. Pass both the order code and targetMerchantId in the options object.

const result = await vivaIsv.payments.getOrder({
  orderCode: 1234567890123456,
  targetMerchantId: 'target-merchant-uuid',
});

if (result.success) {
  console.log('Order state:', result.data.StateId);
}

This call requires resellerId and resellerApiKey on the client.

Cancel a payment order

Use cancelOrder() to cancel an open payment order on a connected merchant account.

const result = await vivaIsv.payments.cancelOrder({
  orderCode: 1234567890123456,
  targetMerchantId: 'target-merchant-uuid',
});

if (result.success) {
  console.log('Order cancelled:', result.data);
}

For Basic Auth ISV endpoints, the SDK automatically builds the composite authentication header using:

• Username — {resellerId}:{targetMerchantId}
• Password — {resellerApiKey}

Ensure your ISV account has the necessary permissions granted by VivaWallet before performing operations on behalf of connected merchants. Authorization errors usually mean the merchant is not connected, permissions are missing, or the reseller credentials are not valid for that merchant.