> ## 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 Class – Payments API Client Reference

> Complete reference for the Vivawallet class: constructor options, thirteen sub-client modules, and the standalone getSmartCheckout function.

`Vivawallet` is the primary client class for standard merchant integrations. It exposes typed sub-client modules for payments, transactions, webhooks, fees, wallets, bank transfers, data services, POS helpers, resellers, RF code payments, obligations, source codes, and legacy bank accounts.

## Constructor

```typescript theme={null}
new Vivawallet(options: {
  clientId: string;
  clientSecret: string;
  merchantId: string;
  apikey: string;
  sourceCode?: string | null;
  dev?: boolean;
  logs?: boolean;
})
```

Import and instantiate the client with your VivaWallet 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',
  dev: false,
});
```

<ParamField path="clientId" type="string" required>
  OAuth 2.0 Client ID used to request Bearer tokens.
</ParamField>

<ParamField path="clientSecret" type="string" required>
  OAuth 2.0 Client Secret paired with `clientId` for token requests.
</ParamField>

<ParamField path="merchantId" type="string" required>
  Merchant UUID used as the username in Viva Basic Auth requests.
</ParamField>

<ParamField path="apikey" type="string" required>
  API key used as the password in Viva Basic Auth requests.
</ParamField>

<ParamField path="sourceCode" type="string | null">
  Stored on the client for source-code helpers. Pass source codes in method options when a payment or transaction endpoint requires one.
</ParamField>

<ParamField path="dev" default="false" type="boolean">
  When `true`, the client uses VivaWallet demo endpoints for API calls.
</ParamField>

<ParamField path="logs" default="false" type="boolean">
  Enables internal SDK error logging when `true`.
</ParamField>

***

## Sub-client Modules

Each module is available as a property on the `Vivawallet` instance and handles one domain of the VivaWallet API.

| Module               | Type                     | Description                                                                                     |
| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `payments`           | `VivaPayments`           | Create, retrieve, update, cancel, and create legacy payment orders                              |
| `transactions`       | `VivaTransactions`       | Retrieve, create, cancel, refund, rebate, preauth, MOTO, OCT, and legacy transaction operations |
| `webhooks`           | `VivaWebhooks`           | Add, update, delete, list subscriptions, and retrieve webhook keys                              |
| `fees`               | `VivaFees`               | Retrieve fee amounts for payment orders through the Basic Auth fees endpoint                    |
| `bankTransfers`      | `VivaBankTransfers`      | Bank account linking, bank transfer options, fees, and outgoing transfers                       |
| `wallets`            | `VivaWallets`            | Merchant wallet balances and balance transfers                                                  |
| `dataServices`       | `VivaDataServices`       | Transaction search, MT940 data, sale exports, and account transaction search                    |
| `pos`                | `VivaPos`                | Standard Cloud Terminal device, transaction, action, and session helpers                        |
| `resellers`          | `VivaResellers`          | Reseller cash, bill, OTP, and order flows                                                       |
| `rfCodePayments`     | `VivaRFCodePayments`     | RF code payment references                                                                      |
| `obligations`        | `VivaObligations`        | Payment obligations                                                                             |
| `source`             | `VivaSourceCode`         | Payment source-code helpers                                                                     |
| `legacyBankAccounts` | `VivaLegacyBankAccounts` | Legacy bank account operations                                                                  |

***

## Methods

### `getCloudTerminalAccessToken()`

```typescript theme={null}
vivawallet.getCloudTerminalAccessToken(): Promise<MethodReturn<{
  access_token: string;
  expires_in: number;
  token_type: string;
} | null, 'tokenerror'>>
```

Calls `POST /connect/token` with `grant_type=client_credentials` and returns VivaWallet's full token response. The SDK does not cache this token; callers should reuse it until `expires_in` elapses.

### `getVivaWebhookCode()`

```typescript theme={null}
vivawallet.getVivaWebhookCode(): Promise<MethodReturn<string | null, 'webhookerror'>>
```

Deprecated wrapper around `webhooks.retrieveWebhookKey()`.

***

## `getSmartCheckout(options)`

A standalone named export, not a method on the class. It builds the full SmartCheckout redirect URL for a given order code.

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

const url = getSmartCheckout({
  orderCode: '1234567890123456',
  color: 'FF6600',
  dev: false,
});
```

**Signature:**

```typescript theme={null}
function getSmartCheckout(options: {
  orderCode: string;
  color?: string;
  paymentMethod?: number;
  dev?: boolean;
}): string
```

<ParamField path="orderCode" type="string" required>
  The order code returned by `payments.createOrder()`, converted to a string.
</ParamField>

<ParamField path="color" type="string">
  Optional color value appended to the SmartCheckout URL.
</ParamField>

<ParamField path="paymentMethod" type="number">
  Optional VivaWallet payment method identifier to pre-select on SmartCheckout.
</ParamField>

<ParamField path="dev" default="false" type="boolean">
  When `true`, constructs a URL pointing to the VivaWallet demo checkout environment.
</ParamField>

**Returns:** `string` — the fully constructed SmartCheckout redirect URL.