> ## Documentation Index
> Fetch the complete documentation index at: https://vivawallet-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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.

```typescript theme={null}
const result = await vivaIsv.connectedAccounts.create({
  email: 'merchant@example.com',
  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)`:

```typescript theme={null}
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:

```typescript theme={null}
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);
```

<Note>
  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.
</Note>