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

# Installing the VivaWallet Node SDK in Your Project

> Add @nkhind/vivawallet-sdk to your Node.js project with npm, yarn, or pnpm, then import client classes and TypeScript types from the package root.

`@nkhind/vivawallet-sdk` is published to the public npm registry and works in any Node.js project that supports TypeScript. Install it once, import the client you need, and you are ready to make authenticated API calls — no additional HTTP client or token-management setup required.

## Requirements

Before installing, make sure your environment meets the following minimum versions:

| Requirement | Minimum version                                                 |
| ----------- | --------------------------------------------------------------- |
| Node.js     | 16.x or later                                                   |
| TypeScript  | 4.x or later (recommended for full discriminated-union support) |

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @nkhind/vivawallet-sdk
  ```

  ```bash yarn theme={null}
  yarn add @nkhind/vivawallet-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @nkhind/vivawallet-sdk
  ```
</CodeGroup>

<Card title="NPM package" icon="package" href="https://www.npmjs.com/package/@nkhind/vivawallet-sdk">
  View the package on npm to check the latest published version, package metadata, and registry details.
</Card>

## Import the clients

The SDK exports each client class as a named export from the package root. Import only the clients you need:

```typescript theme={null}
import { Vivawallet } from '@nkhind/vivawallet-sdk';    // Standard merchant
import { VivaISV } from '@nkhind/vivawallet-sdk';        // ISV / reseller
import { Marketplace } from '@nkhind/vivawallet-sdk';    // Multi-seller platform

// Utility helper for building SmartCheckout redirect URLs
import { getSmartCheckout } from '@nkhind/vivawallet-sdk';
```

`getSmartCheckout` is a synchronous helper that builds the VivaWallet hosted-checkout redirect URL from a payment order code. It accepts an `orderCode` (string), an optional `dev` flag for the demo environment, and optional `color` and `paymentMethod` query parameters:

```typescript theme={null}
const checkoutUrl = getSmartCheckout({
  orderCode: String(result.data.orderCode), // returned by payments.createOrder()
  dev: false,                         // true → routes to demo checkout
  color: 'FF6600',                    // optional: brand colour (hex, no #)
  paymentMethod: 0,                   // optional: pre-select a payment method
});

// Redirect the user to this URL to complete payment
res.redirect(checkoutUrl);
```

## Import TypeScript types

The SDK exports its public client classes, helper functions, and many public TypeScript types from the package root. Use those exports to type webhook payloads, method responses, and request bodies in your own code:

```typescript theme={null}
import type {
  VivaWebhookDatas,
  SmartCheckoutWebhookEventDatas,
  ConnectedAccountWebhookEventDatas,
} from '@nkhind/vivawallet-sdk';

// Type your Express (or any framework) webhook handler body directly:
app.post('/webhooks/viva', (req, res) => {
  const payload: VivaWebhookDatas<SmartCheckoutWebhookEventDatas> = req.body;

  console.log(payload.EventData.TransactionId);
  res.sendStatus(200);
});
```

<Tip>
  Import public SDK types from `@nkhind/vivawallet-sdk` first. Avoid relying on internal package subpaths unless a type is intentionally exposed there by a future SDK release.
</Tip>

## Verifying your setup

Create a minimal script to confirm the package is installed and your TypeScript configuration can resolve the module. No real API credentials or network calls are needed for this check:

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

// Instantiate the client — this does not make any network requests
const vivawallet = new Vivawallet({
  clientId: 'test-client-id',
  clientSecret: 'test-client-secret',
  merchantId: 'test-merchant-id',
  apikey: 'test-api-key',
});

console.log('VivaWallet SDK loaded successfully:', typeof vivawallet);
// → VivaWallet SDK loaded successfully: object
```

If this compiles and runs without errors, your installation is working correctly. Replace the placeholder strings with your real credentials (ideally from environment variables — see [Authentication](/authentication)) when you are ready to make live or demo API calls.