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

# VivaWallet Node SDK: Authentication and Credentials

> Supply your VivaWallet OAuth 2.0 and Basic Auth credentials once at construction time and let the SDK handle all token fetching and header signing.

The SDK keeps authentication details inside the client instance. You provide credentials when you instantiate a client, then SDK methods request OAuth Bearer tokens or build Basic Auth headers as required by each VivaWallet endpoint.

<Info>
  OAuth access tokens are requested internally by OAuth-based methods. The current SDK does not expose or cache a reusable token manager for application code. Cloud Terminal tokens are returned to you explicitly so you can reuse them until `expires_in`.
</Info>

## Credential Types

VivaWallet uses two authentication mechanisms depending on the endpoint group:

**1. OAuth 2.0 — Client ID + Client Secret**

Used for SmartCheckout, Acquiring, ISV, Marketplace, Data Services, and POS calls. The SDK exchanges your Client ID and Client Secret for a short-lived Bearer token via `POST /connect/token` when an OAuth-based method runs.

**2. Viva Basic Auth — Merchant ID + API Key**

Used for legacy and payment-source endpoints. The SDK base64-encodes your Merchant ID and API Key and sends them as an HTTP Basic `Authorization` header on each relevant request.

Some ISV endpoints use a reseller-specific Basic Auth variant. For those calls, the username is composed from the Reseller ID and the target merchant ID.

## Demo vs Production

Pass `dev: true` in the client constructor to route API calls through VivaWallet demo endpoints:

```typescript theme={null}
const vivawallet = new Vivawallet({
  clientId: process.env.VIVA_CLIENT_ID!,
  clientSecret: process.env.VIVA_CLIENT_SECRET!,
  merchantId: process.env.VIVA_MERCHANT_ID!,
  apikey: process.env.VIVA_API_KEY!,
  dev: true,
});
```

Use matching demo credentials with `dev: true`; live credentials and demo credentials are separate.

***

## Vivawallet Client Credentials

Instantiate the standard `Vivawallet` client with merchant OAuth credentials and merchant Basic Auth credentials:

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

const vivawallet = new Vivawallet({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
  sourceCode: 'MY_SOURCE_CODE', // Optional: stored on the client for source helpers
  dev: false,                   // Optional: true uses demo endpoints
});
```

The required credential fields are:

| Field          | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| `clientId`     | OAuth 2.0 Client ID from your VivaWallet application.                      |
| `clientSecret` | OAuth 2.0 Client Secret paired with your `clientId`.                       |
| `merchantId`   | Merchant account UUID, used as the username for Viva Basic Auth endpoints. |
| `apikey`       | Merchant API key, used as the password for Viva Basic Auth endpoints.      |

Optional setup fields:

| Field        | Description                                                                                                                                                                                   |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sourceCode` | Stored on the client and used by the source-code helper when no source code is passed to that helper. Pass `sourceCode` in method options when a payment or transaction endpoint requires it. |
| `dev`        | Uses demo endpoints when `true`.                                                                                                                                                              |
| `logs`       | Enables internal SDK error logging when `true`.                                                                                                                                               |

***

## ISV Client Credentials

The `VivaISV` client is used by resellers managing connected merchant accounts. It requires ISV OAuth credentials at minimum:

```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,
});
```

Add reseller credentials when you need ISV Basic Auth endpoints such as retrieving or cancelling an order on behalf of a target merchant:

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

For ISV endpoints that use Basic Auth, VivaWallet expects the `Authorization` header to encode `Username = Reseller ID:Merchant ID` and `Password = Reseller API Key`. The target merchant ID is passed per method because it identifies the merchant account being acted upon:

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

***

## Marketplace Client Credentials

Instantiate the `Marketplace` client with your platform merchant account's OAuth and Basic Auth credentials. These are the credentials for your marketplace operator account, not for individual sellers:

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

const marketplace = new Marketplace({
  clientId: 'your-smartcheckout-client-id',
  clientSecret: 'your-smartcheckout-client-secret',
  merchantId: 'your-merchant-uuid',
  apikey: 'your-api-key',
  dev: false,
});
```

The `Marketplace` client uses platform OAuth credentials for Marketplace, Checkout, and Acquiring API calls, while keeping merchant credentials available for Basic Auth helpers such as payment sources and webhooks.

***

## Storing Credentials Securely

Always load credentials from environment variables rather than writing them directly into your source code. A `.env` file excluded from version control, or your deployment platform's secret manager, is the right place to store them:

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

const vivawallet = new Vivawallet({
  clientId: process.env.VIVA_CLIENT_ID!,
  clientSecret: process.env.VIVA_CLIENT_SECRET!,
  merchantId: process.env.VIVA_MERCHANT_ID!,
  apikey: process.env.VIVA_API_KEY!,
  dev: process.env.VIVA_ENV === 'demo',
});
```

A minimal `.env` file to match:

```bash .env theme={null}
VIVA_CLIENT_ID=your-smartcheckout-client-id
VIVA_CLIENT_SECRET=your-smartcheckout-client-secret
VIVA_MERCHANT_ID=your-merchant-uuid
VIVA_API_KEY=your-api-key
VIVA_ENV=demo
```

<Warning>
  Never hardcode credentials in your source code or commit them to version control. Exposed credentials can be used to process unauthorized transactions or access sensitive financial data on your merchant account.
</Warning>

***

## Where to Find Your Credentials

All credentials are available in your VivaWallet merchant dashboard:

* **Client ID and Client Secret** — Go to **Settings → API Access → OAuth 2.0 Credentials** and create the relevant application for your integration.
* **Merchant ID and API Key** — Go to **Settings → API Access**. Your Merchant ID and API Key are shown under the Basic Authentication section.
* **ISV Client ID and Client Secret** — Available in the ISV Partner Portal under your ISV application settings.
* **Reseller ID and Reseller API Key** — Provided by VivaWallet when your reseller account is activated in the ISV program.

If you do not yet have a VivaWallet merchant account, register at [vivawallet.com](https://www.vivawallet.com) and complete merchant verification before attempting to retrieve credentials.