> ## 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.

# VivaISV Client: Multi-Merchant ISV API Integration

> The VivaISV client lets Independent Software Vendors manage merchant payments, connected accounts, and POS terminals across multiple merchants.

The `VivaISV` class is designed for Independent Software Vendors (ISVs) that manage payments and terminal operations on behalf of multiple merchants. It authenticates with ISV-scoped OAuth credentials for OAuth API calls and optionally accepts reseller credentials for Basic Auth endpoints that target specific merchant accounts.

## Initialization

You have two setup options depending on which ISV endpoints you intend to use.

### OAuth-only setup

Use this when you only need OAuth 2.0 endpoints such as connected-account creation, payment order creation, transaction lookup, or POS operations:

```typescript theme={null}
import { VivaISV } from '@nkhind/vivawallet-sdk';

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

### With reseller credentials

Add `resellerId` and `resellerApiKey` to enable ISV Basic Auth endpoints, such as retrieving or cancelling an order on behalf of a specific merchant:

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

<ParamField body="clientId" type="string" required>
  Your ISV OAuth 2.0 Client ID.
</ParamField>

<ParamField body="clientSecret" type="string" required>
  Your ISV OAuth 2.0 Client Secret.
</ParamField>

<ParamField body="resellerId" type="string">
  Your Reseller ID, required for ISV Basic Auth endpoints. Used as the first part of the Basic Auth username.
</ParamField>

<ParamField body="resellerApiKey" type="string">
  Your Reseller API Key, used as the Basic Auth password for ISV Basic Auth endpoints.
</ParamField>

<ParamField body="sourceCode" type="string">
  Stored on the client for source helpers. Pass source codes in method options when an ISV payment or transaction endpoint requires one.
</ParamField>

## Available Modules

<CardGroup cols={2}>
  <Card title="payments" icon="credit-card">
    Create, retrieve, and cancel payment orders on behalf of target merchants.
  </Card>

  <Card title="transactions" icon="arrow-right-arrow-left">
    Retrieve ISV transactions, search Data Services transactions, cancel/refund payments, handle preauth, create recurring transactions, and run MOTO charges.
  </Card>

  <Card title="connectedAccounts" icon="link">
    Create connected accounts and retrieve connected-account details.
  </Card>

  <Card title="source" icon="code">
    Create and set source codes for ISV flows.
  </Card>

  <Card title="pos" icon="mobile-screen">
    Search POS devices, initiate/refund POS transactions, query action data, create terminal actions, and abort sessions.
  </Card>

  <Card title="webhook / webhooks" icon="webhook">
    Create ISV webhooks and retrieve the ISV webhook verification key. Both property names point to the same module.
  </Card>
</CardGroup>

<Info>
  `vivaIsv.webhooks` and `vivaIsv.webhook` refer to the same underlying `IsvWebhook` instance. Both aliases are supported.
</Info>

## Targeting a Specific Merchant

Some ISV methods target a connected merchant account. OAuth endpoints usually pass that merchant as `merchantId` or `targetMerchantId` in the request options. Basic Auth ISV endpoints require reseller credentials and use `targetMerchantId` to build the composite Basic Auth username.

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

if (result.success) {
  console.log('Order cancelled successfully');
} else {
  console.error('Cancellation failed:', result.message);
}
```

<Warning>
  Calls that use ISV Basic Auth require both `resellerId` and `resellerApiKey` to be set on the client. Omitting them returns a typed `initerror` failure response.
</Warning>

## Cloud Terminal with ISV Credentials

When your ISV integration needs Cloud Terminal access, request a token with the ISV client:

```typescript theme={null}
const tokenResult = await vivaIsv.getCloudTerminalAccessToken();

if (tokenResult.success) {
  const { access_token, expires_in } = tokenResult.data;
  console.log(`Token expires in ${expires_in} seconds`);
}
```

<Note>
  `getCloudTerminalAccessToken()` returns VivaWallet's full token response and does not cache it. Reuse the returned token until `expires_in` elapses, then request a new one.
</Note>

## Related Guides

<CardGroup cols={2}>
  <Card title="ISV Payments" icon="credit-card" href="/guides/isv-payments">
    Create and manage payment orders across multiple merchant accounts.
  </Card>

  <Card title="ISV Connected Accounts" icon="link" href="/guides/isv-connected-accounts">
    Onboard and retrieve merchants as connected accounts under your ISV.
  </Card>

  <Card title="ISV POS" icon="mobile-screen" href="/guides/isv-pos">
    Configure terminals and manage POS sessions for ISV-managed devices.
  </Card>
</CardGroup>