> ## 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: Overview, Clients, and Concepts

> Understand the @nkhind/vivawallet-sdk architecture: choose between the Vivawallet, VivaISV, or Marketplace client and see how typed responses work.

The VivaWallet Node SDK (`@nkhind/vivawallet-sdk`) is a TypeScript-first wrapper that gives you a typed interface to the VivaWallet payment platform. It covers Standard payments, Marketplace, ISV, POS, webhook, wallet, transfer, and reporting modules through client classes that share the same `MethodReturn` result shape.

<Note>
  This is a community-maintained SDK and is not officially affiliated with Viva Payments S.A.
</Note>

## What is this SDK?

`@nkhind/vivawallet-sdk` is a non-official TypeScript wrapper for VivaWallet APIs. Rather than manually constructing HTTP requests and auth headers, you instantiate one of the SDK's three public client classes with your credentials and call typed async methods directly.

The SDK handles three things for you:

* **OAuth token requests** — OAuth-based methods request a Bearer token with your client credentials before calling VivaWallet, so application code does not pass tokens manually.
* **Basic Auth header construction** — for legacy endpoints that use Merchant ID + API Key, the SDK builds and attaches the correct `Authorization` header automatically.
* **Typed responses** — every async method returns a `MethodReturn<TData, TCode>` discriminated union so you always check whether a call succeeded before touching the response data.

## Client Classes

Choose the client that matches your integration model. You only need to instantiate the one that fits your use case.

<CardGroup cols={1}>
  <Card title="Vivawallet" icon="shop" href="/clients/vivawallet">
    The standard merchant client. Use it for SmartCheckout payment orders, transaction management, webhooks, fees, bank transfers, wallets, data services, and POS helpers on a single merchant account.
  </Card>

  <Card title="VivaISV" icon="buildings" href="/clients/isv">
    The ISV / reseller client. Use it to manage connected merchant accounts, create payment orders on behalf of sub-merchants, and access ISV-specific POS and cloud terminal endpoints.
  </Card>

  <Card title="Marketplace" icon="store" href="/clients/marketplace">
    The multi-seller platform client. Use it to onboard marketplace sellers, route payments to multiple parties, and transfer funds between seller wallets.
  </Card>
</CardGroup>

## Key Features

* Payment order creation and SmartCheckout redirect via `getSmartCheckout()`
* Transaction retrieval, cancellation, refund, MOTO, preauth, OCT, and payout operations
* Webhook subscriptions plus receiver helpers for verification responses, Data Services signatures, idempotency, and soft validation
* Fees, bank transfers, wallets, RF code payments, resellers, and data services
* Standard and ISV POS / Cloud Terminal helper modules
* ISV connected account, payment, transaction, source, webhook, and POS modules
* Marketplace sellers, payment orders, transactions, transfers, webhooks, and source management
* Cloud Terminal access-token helper
* TypeScript request and response types exported from the package root for the public SDK surface

## TypeScript Support

Every async method in the SDK returns a `MethodReturn<TData, TCode>` discriminated union. When `result.success` is `true`, the `result.data` property is typed for that specific endpoint. When `result.success` is `false`, you get a structured error with a `message` and a typed `code`.

```typescript theme={null}
const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #42',
});

if (result.success) {
  // result.data is fully typed here
  console.log(result.data.orderCode);
} else {
  // result.message and result.code are available on failure
  console.error(result.message, result.code);
}
```

This pattern means you do not need to use `try/catch` for expected API failures. The SDK converts them into typed failure values in the discriminated union.

## Environments

VivaWallet provides two environments:

| Environment | Purpose                                           |
| ----------- | ------------------------------------------------- |
| Production  | Live transactions against real merchant accounts  |
| Demo        | Sandbox testing with test credentials and amounts |

Pass `dev: true` when constructing a client to make that client use the VivaWallet demo endpoints for API calls.

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

`getSmartCheckout()` also accepts `dev: true`, because the redirect URL is built independently from the client instance.

```typescript theme={null}
const checkoutUrl = getSmartCheckout({
  orderCode: String(orderCode),
  dev: true,
});
```