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

# Create and Manage Payments via VivaWallet SmartCheckout

> Create payment orders, redirect customers to SmartCheckout, retrieve fees, and manage the full order lifecycle using the VivaWallet payments and fees modules.

The standard payment flow has three steps: create a payment order on your server, redirect the customer to SmartCheckout with the returned `orderCode`, then confirm the outcome through webhooks or an order lookup. These operations live under `vivawallet.payments`.

<Note>
  All monetary amounts are expressed in the **smallest currency unit**. For EUR that means cents: pass `1000` for EUR 10.00.
</Note>

## Create a Payment Order

Call `createOrder(orderData)` to register a new payment intent with VivaWallet. On success, `result.data.orderCode` contains the code you need to build the checkout URL.

```typescript theme={null}
const result = await vivawallet.payments.createOrder({
  amount: 1000,
  customerTrns: 'Order #1234',
  customer: {
    email: 'customer@example.com',
    fullName: 'John Doe',
    phone: '+30123456789',
    requestLang: 'en-GB',
  },
  sourceCode: 'DEFAULT',
  allowRecurring: false,
  maxInstallments: 0,
});

if (!result.success) {
  console.error(result.message);
  return;
}

const { orderCode } = result.data;
```

Common `createOrder()` fields:

| Field                  | Required | Description                                         |
| ---------------------- | -------- | --------------------------------------------------- |
| `amount`               | Yes      | Payment amount in the smallest currency unit.       |
| `customerTrns`         | No       | Friendly payment description shown to the customer. |
| `customer.email`       | No       | Customer email address.                             |
| `customer.fullName`    | No       | Customer full name.                                 |
| `customer.phone`       | No       | Customer phone number.                              |
| `customer.requestLang` | No       | Checkout language/locale, for example `en-GB`.      |
| `sourceCode`           | No       | Payment source code for this order.                 |
| `allowRecurring`       | No       | Allows recurring payments for the order.            |
| `maxInstallments`      | No       | Maximum number of installments to offer.            |

## Redirect to SmartCheckout

Once you have an `orderCode`, use the `getSmartCheckout` helper to build the hosted checkout URL and redirect your customer to it.

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

const checkoutUrl = getSmartCheckout({
  orderCode: String(orderCode),
  color: '0000FF', // Optional: hex color, without '#'
  dev: false,      // Set true to use the demo checkout URL
});

res.redirect(checkoutUrl);
```

`getSmartCheckout()` is a standalone helper exported from the package root. Its `dev` flag only affects the checkout URL it builds. API calls use demo endpoints when the client itself was constructed with `dev: true`.

## Retrieve an Order

After the customer completes or abandons checkout, retrieve the order to inspect its current state. The SDK method takes the `orderCode` directly, not an options object.

```typescript theme={null}
const orderResult = await vivawallet.payments.getOrder(orderCode);

if (orderResult.success) {
  const order = orderResult.data;
  console.log(order.stateId);
  console.log(order.requestAmount);
}
```

## Cancel a Payment Order

Cancel an unpaid order to prevent the customer from completing it. This is useful when your session expires or the cart contents change.

```typescript theme={null}
const cancelResult = await vivawallet.payments.cancelOrder(String(orderCode));

if (cancelResult.success) {
  console.log('Order cancelled');
}
```

## Update a Payment Order

You can update certain fields on an existing unpaid order, such as amount or customer-facing text, using `updateOrder(orderCode, options)`.

```typescript theme={null}
const updateResult = await vivawallet.payments.updateOrder(orderCode, {
  amount: 2000,
  customerTrns: 'Updated Order #1234',
});

if (!updateResult.success) {
  console.error(updateResult.message);
}
```

## Retrieve Payment Fees

Use `vivawallet.fees.retrieveFees(options)` when you need Viva's fee calculation for a payment order amount. This method uses the legacy Basic Auth fee endpoint, so the client must be initialized with `merchantId` and `apikey`.

```typescript theme={null}
const fees = await vivawallet.fees.retrieveFees({
  orderCode: String(orderCode),
  amount: 1000,
});

if (fees.success && fees.data) {
  console.log(fees.data.Fee);
  console.log(fees.data.ServiceFee);
  console.log(fees.data.TotalConversionFee);
}
```

`VivaFeesReturn` mirrors Viva's response fields, including `Fee`, `BillFee`, `ServiceFee`, `ResellerFee`, `CollectionFee`, and `TotalConversionFee` when returned by the API.

## Create a Legacy Payment Order

For older integrations that use VivaWallet's Basic Auth payment API, use `createLegacyOrder(orderData)`. This method targets the legacy endpoint and requires `merchantId` and `apikey` credentials on your client.

```typescript theme={null}
const legacyResult = await vivawallet.payments.createLegacyOrder({
  amount: 1000,
  customerTrns: 'Order #1234',
  email: 'customer@example.com',
  fullName: 'John Doe',
  phone: '+30123456789',
  requestLang: 'en-GB',
});

if (legacyResult.success) {
  const { orderCode } = legacyResult.data;
}
```

Prefer `createOrder()` for new integrations. It uses the OAuth-based Checkout v2 order endpoint and returns the SDK's normalized `{ orderCode }` response.