Manage ISV Connected Merchant Accounts

Onboard and manage connected merchant accounts under your VivaWallet ISV account using the connectedAccounts module of the VivaISV client.

Connected accounts represent merchants registered under your ISV umbrella. Use vivaIsv.connectedAccounts to create a new connected account and retrieve existing connected-account details with ISV OAuth credentials.

Initialize the ISV client

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

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

The clientId and clientSecret are your ISV-level OAuth 2.0 credentials. The connected-account methods use Bearer token authentication derived from these credentials.

Create a connected account

Use vivaIsv.connectedAccounts.create(options) to onboard a new merchant under your ISV account. The ISVCreateAccountOptions payload requires the merchant email and the return URL for the onboarding flow.

const result = await vivaIsv.connectedAccounts.create({
  email: '[e-mail]',
  returnurl: 'https://yourplatform.com/isv/onboarding-return',
  branding: {
    partnerName: 'Your ISV Platform',
    logoUrl: 'https://yourplatform.com/logo.png',
    primaryColor: '000000',
  },
});

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

console.log('Connected account ID:', result.data.accountId);
console.log('Invitation URL:', result.data.invitation.redirectUrl);

Store the returned accountId. You will use it to retrieve account data and to track onboarding progress.

Retrieve a connected account

Retrieve connected merchant account details by account ID with getAccountDatas(options):

const result = await vivaIsv.connectedAccounts.getAccountDatas({
  accountId: 'connected-account-id',
});

if (result.success) {
  const account = result.data;
  console.log('Merchant ID:', account.merchantId);
  console.log('Verified:', account.verified);
  console.log('Can accept payments:', account.acquiringEnabled);
}

The returned merchantId is the merchant identifier you use in other ISV flows, such as creating payment orders or targeting Basic Auth methods through targetMerchantId.

Connected account webhooks

VivaWallet sends webhook events when the status of a connected account changes. The SDK exports ConnectedAccountWebhookEventDatas to type these payloads in your webhook handler:

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

const event: VivaWebhookDatas<ConnectedAccountWebhookEventDatas> = req.body;

console.log('Event type:', event.EventTypeId);
console.log('Merchant ID:', event.EventData.MerchantId);
console.log('New status:', event.EventData.Status);

To receive connected-account webhook events, configure the webhook URL in your VivaWallet ISV dashboard or create it through vivaIsv.webhook.create(). The SDK exposes both vivaIsv.webhook and vivaIsv.webhooks as aliases for the same module.