> ## 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 Client: Standard Merchant API Integration

> The Vivawallet client covers payments, transactions, webhooks, fees, bank transfers, wallets, data services, POS helpers, and more for standard merchants.

The `Vivawallet` class is the main entry point for standard merchant integrations. Once instantiated with your credentials, it exposes typed sub-clients for payments, transactions, webhooks, fees, bank transfers, wallets, data services, POS helpers, reseller flows, RF code payments, obligations, payment sources, and legacy bank-account operations.

## Initialization

Pass your OAuth credentials together with your merchant Basic Auth credentials. The SDK uses the right authentication method for each API call.

```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: used by source helpers
  dev: false,                   // Optional: true uses demo endpoints
});
```

<ParamField body="clientId" type="string" required>
  Your OAuth 2.0 Client ID, used for Bearer-token API calls.
</ParamField>

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

<ParamField body="merchantId" type="string" required>
  Your merchant UUID, used as the username in Viva Basic Auth endpoints.
</ParamField>

<ParamField body="apikey" type="string" required>
  Your merchant API key, used as the password in Viva Basic Auth endpoints.
</ParamField>

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

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

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

## Available Modules

After instantiation, all sub-clients are available as properties of the `Vivawallet` instance:

<CardGroup cols={2}>
  <Card title="payments" icon="credit-card">
    Create, retrieve, update, cancel, and create legacy payment orders.
  </Card>

  <Card title="transactions" icon="arrow-right-arrow-left">
    Retrieve, cancel, refund, rebate, tokenize, MOTO, preauth, OCT, and legacy transaction operations.
  </Card>

  <Card title="webhooks" icon="webhook">
    Add, update, delete, and list webhook subscriptions. Retrieve webhook verification keys.
  </Card>

  <Card title="fees" icon="receipt">
    Retrieve fee amounts for payment orders through the Basic Auth fees endpoint.
  </Card>

  <Card title="bankTransfers" icon="building-columns">
    Link bank accounts, retrieve transfer options, create transfer fees, and execute outgoing transfers.
  </Card>

  <Card title="wallets" icon="wallet">
    Merchant wallet balances and balance transfers between Viva accounts.
  </Card>

  <Card title="dataServices" icon="database">
    Transaction search, MT940 exports, sale transaction exports, and account transaction search.
  </Card>

  <Card title="pos" icon="terminal">
    Standard Cloud Terminal helpers for device search, POS transactions, terminal actions, and session management.
  </Card>

  <Card title="resellers" icon="store">
    Reseller payment flows including cash, bill, OTP, and reseller order creation.
  </Card>

  <Card title="rfCodePayments" icon="barcode">
    Generate RF code payment references.
  </Card>

  <Card title="obligations" icon="file-invoice">
    Create payment obligations tied to specific amounts and references.
  </Card>

  <Card title="source" icon="code">
    Create or set payment source codes associated with your merchant account.
  </Card>

  <Card title="legacyBankAccounts" icon="landmark">
    Legacy bank account linking and outgoing transfer operations.
  </Card>
</CardGroup>

### Usage Example

Each sub-client method returns a typed `MethodReturn` result object:

```typescript theme={null}
const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #42',
  customer: {
    email: 'customer@example.com',
    requestLang: 'en-GB',
  },
  merchantTrns: 'internal-ref-42',
});

if (result.success) {
  console.log('Order code:', result.data.orderCode);
} else {
  console.error('Error:', result.message);
}
```

## `getSmartCheckout` Helper

After creating a payment order, redirect your customer to the VivaWallet SmartCheckout page using the standalone `getSmartCheckout()` function. This function constructs the full redirect URL from the order code and optional display options.

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

const url = getSmartCheckout({
  orderCode: '1234567890123456',
  color: '0000FF', // Optional: hex color, without '#'
  dev: false,      // Optional: use demo checkout URL
});

res.redirect(url);
```

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

<ParamField body="color" type="string">
  Optional color value passed to VivaWallet for the checkout UI.
</ParamField>

<ParamField body="paymentMethod" type="number">
  Optional VivaWallet payment method identifier to pre-select on the checkout page.
</ParamField>

<ParamField body="dev" type="boolean">
  When `true`, the URL points to the VivaWallet demo checkout environment instead of production.
</ParamField>

`getSmartCheckout()` returns the full SmartCheckout URL as a string.

## Demo Environment

Pass `dev: true` when constructing the `Vivawallet` client to route API calls to VivaWallet demo endpoints. `getSmartCheckout()` also accepts `dev: true`, because the checkout redirect URL is built independently from the client instance.

```typescript theme={null}
const vivawallet = new Vivawallet({
  clientId: 'demo-client-id',
  clientSecret: 'demo-client-secret',
  merchantId: 'demo-merchant-id',
  apikey: 'demo-api-key',
  dev: true,
});

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

<Note>
  Demo credentials are separate from live credentials. Use matching demo credentials when the client is created with `dev: true`.
</Note>

## Related Guides

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card" href="/guides/payments">
    Learn how to create, retrieve, update, and cancel payment orders.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/guides/transactions">
    Cancel, refund, and inspect transaction details.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Manage webhook subscriptions and type incoming events.
  </Card>

  <Card title="Webhook Helpers" icon="shield-check" href="/guides/webhook-helpers">
    Verify, deduplicate, and soft-validate incoming webhook deliveries.
  </Card>

  <Card title="Cloud Terminal" icon="terminal" href="/guides/cloud-terminal">
    Search POS devices, initiate terminal requests, and manage sessions.
  </Card>

  <Card title="Bank Transfers" icon="building-columns" href="/guides/bank-transfers">
    Link bank accounts and execute outgoing fund transfers.
  </Card>

  <Card title="Wallets" icon="wallet" href="/guides/wallets">
    Check balances and move funds between merchant wallets.
  </Card>
</CardGroup>