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

# TypeScript Type Reference for @nkhind/vivawallet-sdk

> Reference for documented public TypeScript types exported by @nkhind/vivawallet-sdk: MethodReturn, webhook payloads, and per-domain input/return types.

The SDK is written in TypeScript and exports the public client classes, helper functions, and many request/response types from the package root. Import documented public types alongside your client classes in a single statement:

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

***

## `MethodReturn<TData, TCode>`

`MethodReturn` is the discriminated union type returned by every async method in the SDK. It has two shapes — a success variant and a failure variant — so TypeScript can narrow `result.data` to its correct type inside a success branch.

```typescript theme={null}
// Success case
{ success: true; data: TData; message: string }

// Failure case
{ success: false; data: null; message: string; code: TCode }
```

**Usage example:**

```typescript theme={null}
const result = await vivawallet.payments.createOrder({ ... });

if (result.success) {
  // TypeScript knows result.data is defined here
  console.log(result.data.orderCode);
} else {
  console.error(result.message);
}
```

The `TCode` type parameter is a string literal (e.g., `'webhookerror'`) that represents the set of known error codes for that specific method. See the [Errors reference](/reference/errors) for details.

***

## Webhook Types

The SDK exports both the original webhook payload aliases and newer tolerant webhook helper types. Use the original aliases for simple typed handlers, and use the tolerant types with the helper functions documented in [Webhook Helpers](/guides/webhook-helpers).

| Type                                      | Description                                                                                                 |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `VivaWebhookDatas<T>`                     | Generic wrapper for all webhook event payloads. Pass a specific event data type as `T` to get a typed body. |
| `SmartCheckoutWebhookEventDatas`          | Original SmartCheckout event payload alias for payment events.                                              |
| `ConnectedAccountWebhookEventDatas`       | Original connected-account event payload alias.                                                             |
| `VivaWebhookEnvelope<T>`                  | Tolerant envelope type for Viva webhook deliveries with optional `EventData`.                               |
| `VivaWebhookEventData`                    | Base tolerant event-data type that allows additional Viva fields.                                           |
| `VivaKnownWebhookEventName`               | Known Viva webhook event-name union used by receiver helpers.                                               |
| `VivaWebhookHeaders`                      | Header map for signed Data Services notifications and retry metadata.                                       |
| `VivaWebhookSoftValidationResult<T>`      | Result returned by every soft validation helper.                                                            |
| `VivaWebhookFieldExpectations`            | Optional expected values passed to soft validation helpers.                                                 |
| `VivaWebhookSignatureVerificationOptions` | Input options for `verifyVivaDataServicesWebhookSignature()`.                                               |
| `VivaWebhookSignatureVerificationResult`  | Signature verification result with issues, delivery ID, and event name.                                     |
| `VivaWebhookIdentity`                     | Identity fields extracted by `extractVivaWebhookIdentity()`.                                                |
| `VivaWebhookIdempotencyKeyResult`         | Idempotency key result from `getVivaWebhookIdempotencyKey()`.                                               |

**Example — typing an Express webhook handler:**

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

app.post('/webhooks/viva', (req, res) => {
  const body: VivaWebhookDatas<SmartCheckoutWebhookEventDatas> = req.body;
  console.log(body.EventData.TransactionId);
  res.sendStatus(200);
});
```

***

## Core Types

The types below are exported from `@nkhind/vivawallet-sdk` and can be imported with `import type { ... }`. Internal-only SDK types are intentionally not listed here.

### Payments

| Type                            | Description                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `VivaLegacyPaymentOrderOptions` | Input options for `payments.createLegacyOrder()`                                  |
| `VivaLegacyPaymentOrderReturn`  | Response data from a successful `createLegacyOrder()` call, including `orderCode` |
| `VivaGetOrderReturn`            | Response data from `payments.getOrder()`, with order status and metadata          |
| `VivaUpdateOrderOptions`        | Input options for `payments.updateOrder()`                                        |
| `VivaUpdateOrderReturn`         | Response data from a successful `updateOrder()` call                              |

### Fees

| Type              | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `VivaFeesOptions` | Input options for `fees.retrieveFees()`                                           |
| `VivaFeesReturn`  | Response data from a successful fee lookup, including fee fields returned by Viva |

### Transactions

| Type                                    | Description                                                                                                 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `VivaTransactionDatas`                  | Input options for `transactions.createTransaction()` and deprecated `transactions.makeTransaction()`        |
| `VivaTransactionReturn`                 | Response used by `createTransaction()`, `makeMotoCardCharge()`, `cancelTransaction()`, and `octAndPayout()` |
| `VivaTransactionIdReturn`               | Response containing a transaction ID, used by `increasePreauth()`, `rebate()`, and `fastRefund()`           |
| `VivaRebateOptions`                     | Input options for `transactions.rebate(transactionId, options)`                                             |
| `VivaFastRefundOptions`                 | Input options for `transactions.fastRefund(transactionId, options)`                                         |
| `VivaMotoChargeOptions`                 | Input options for `transactions.makeMotoCardCharge()`                                                       |
| `VivaOctPayoutOptions`                  | Input options for `transactions.octAndPayout(transactionId, options)`                                       |
| `VivaCreateCardTokenOptions`            | Input options for `transactions.createCardToken()`                                                          |
| `VivaCreateCardTokenReturn`             | Response from a successful card tokenisation call                                                           |
| `VivaIncrementalPreauthOptions`         | Input options for `transactions.increasePreauth(transactionId, options)`                                    |
| `VivaCancelPartialAuthorizationOptions` | Input options for `transactions.cancelPartialAuthorization(transactionId, options)`                         |
| `VivaCancelRebateFastRefundOptions`     | Input options for `transactions.cancelRebateOrFastRefund(transactionId, options)`                           |
| `VivaMotoCreditCardOptions`             | Nested credit-card input for `VivaMotoChargeOptions`                                                        |
| `VivaLegacyTransactionsQuery`           | Query parameters for `transactions.getLegacyTransactions()`                                                 |
| `VivaLegacyTransactionsReturn`          | Response shape for legacy transaction lookup calls                                                          |

### Bank Transfers

| Type                               | Description                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| `VivaBankAccountReturn`            | Linked bank account object returned by the current bank transfer API                   |
| `VivaBankAccountsQuery`            | Query parameters for `bankTransfers.retrieveBankAccounts()`                            |
| `VivaLinkBankAccountOptions`       | Input options for `bankTransfers.linkBankAccount()`                                    |
| `VivaLinkBankAccountReturn`        | Response from a successful bank account link call                                      |
| `VivaUpdateBankAccountOptions`     | Options passed to `bankTransfers.updateBankAccount(bankAccountId, options)`            |
| `VivaUpdateBankAccountReturn`      | Response from a successful bank account update                                         |
| `VivaExecuteBankTransferOptions`   | Options passed to `bankTransfers.executeBankTransfer(bankAccountId, options)`          |
| `VivaExecuteBankTransferReturn`    | Response from a successful bank transfer execution                                     |
| `VivaCreateBankTransferFeeOptions` | Options passed to `bankTransfers.createBankTransferFeeCommand(bankAccountId, options)` |
| `VivaCreateBankTransferFeeReturn`  | Response from a successful fee command creation call                                   |
| `VivaBankTransferOptionsQuery`     | Query passed to `bankTransfers.retrieveBankTransferOptions(bankAccountId, query)`      |
| `VivaBankTransferOptionsReturn`    | Available bank transfer options from the API                                           |

### Wallets

| Type                         | Description                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `VivaMerchantWalletReturn`   | Merchant wallet object returned by `wallets.retrieveMerchantWallets()`         |
| `VivaLegacyWalletReturn`     | Legacy wallet response shape returned by `wallets.retrieveWallet()`            |
| `VivaBalanceTransferOptions` | Options passed to `wallets.balanceTransfer(walletId, targetWalletId, options)` |
| `VivaBalanceTransferReturn`  | Response from a successful balance transfer call                               |

### Standard POS / Cloud Terminal

| Type                                      | Description                                                  |
| ----------------------------------------- | ------------------------------------------------------------ |
| `VivaPosSearchDevicesOptions`             | Input options for `pos.devices.searchDevices()`              |
| `VivaPosSearchDevicesReturn`              | POS device record returned by device search                  |
| `VivaPosTransactionBaseOptions`           | Shared base fields for POS transaction requests              |
| `VivaPosInitiateSaleRequestOptions`       | Input options for `pos.transactions.initiateSaleRequest()`   |
| `VivaPosCapturePreAuthRequestOptions`     | Input options for `pos.transactions.capturePreAuthRequest()` |
| `VivaPosRefundTransactionOptions`         | Input options for `pos.transactions.refundTransaction()`     |
| `VivaPosUnreferencedRefundOptions`        | Input options for `pos.transactions.unreferencedRefund()`    |
| `VivaPosFastRefundOptions`                | Input options for `pos.transactions.fastRefund()`            |
| `VivaPosRebateOptions`                    | Input options for `pos.transactions.rebate()`                |
| `VivaPosCreateActionOptions`              | Input options for `pos.transactions.createAction()`          |
| `VivaPosActionReturn`                     | Response from a successful terminal action creation          |
| `VivaPosGetActionDetailsOptions`          | Input options for `pos.transactions.getActionDetails()`      |
| `VivaPosActionDetailsReturn`              | Response from a successful action details lookup             |
| `VivaPosRetrieveSessionByIdOptions`       | Input options for `pos.session.retrieveSessionById()`        |
| `VivaPosRetrieveSessionInfoByDateOptions` | Input options for `pos.session.retrieveSessionInfoByDate()`  |
| `VivaPosRetrieveSessionInfoByDateReturn`  | Session list or single session response from date lookup     |
| `VivaPosAbortSessionOptions`              | Input options for `pos.session.abortSession()`               |
| `VivaPosSessionReturn`                    | POS session data returned by session lookups                 |
| `VivaPosStatusId`                         | POS device/session status ID union                           |
| `VivaPosPaymentMethod`                    | Supported POS payment method union                           |
| `VivaPosActionType`                       | Supported POS action type union                              |

### Webhooks

| Type                                                   | Description                                                                                    |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `VivaWebhookSubscriptionOptions`                       | Input options for `webhooks.addSubscription()` and `webhooks.updateSubscription()`             |
| `VivaWebhookSubscriptionReturn`                        | Response from a successful subscription create/update call                                     |
| `VivaWebhookSubscriptionDatas`                         | A single webhook subscription object returned by `webhooks.listSubscriptions()`                |
| `VivaWebhookSubscriptionEvent`                         | A webhook event type string, for example `"transaction_payment_created"`                       |
| `VivaWebhookDeleteSubscriptionReturn`                  | Response from a successful `webhooks.deleteSubscription()` call                                |
| `VivaMerchantWebhookVerificationBody`                  | `{ Key }` body for Merchant and Marketplace webhook URL verification                           |
| `VivaIsvWebhookVerificationBody`                       | `{ key }` body for ISV webhook URL verification                                                |
| `VivaWebhookVerificationResponse<T>`                   | Framework-agnostic verification response returned by verification response builders            |
| `VivaPaymentResultWebhookEventData`                    | Tolerant payment-result payload shape used by payment created, failed, and reversal validators |
| `VivaOrderUpdatedWebhookEventData`                     | Tolerant `Order Updated` payload shape                                                         |
| `VivaAccountConnectedWebhookEventData`                 | Tolerant account connected payload shape                                                       |
| `VivaAccountVerificationStatusChangedWebhookEventData` | Tolerant account verification payload shape                                                    |
| `VivaTransferCreatedWebhookEventData`                  | Tolerant marketplace transfer payload shape                                                    |
| `VivaObligationWebhookEventData`                       | Deprecated obligation webhook payload shape                                                    |
| `VivaSaleTransactionsWebhookEventData`                 | Tolerant Sale Transactions file webhook payload shape                                          |
| `VivaPosEcrSessionWebhookEventData`                    | Tolerant POS ECR session webhook payload shape                                                 |
| `VivaTransactionPriceCalculatedWebhookEventData`       | Tolerant transaction price calculated payload shape                                            |
| `VivaAccountTransactionCreatedWebhookEventData`        | Tolerant account transaction webhook payload shape                                             |
| `VivaBankTransferCommandWebhookEventData`              | Tolerant bank transfer command webhook payload shape                                           |

### Data Services

| Type                                        | Description                                                      |
| ------------------------------------------- | ---------------------------------------------------------------- |
| `VivaDataServicesTransactionsSearchOptions` | Query options for `dataServices.searchTransactions()`            |
| `VivaDataServicesTransactionsSearchReturn`  | Paginated search result from the transactions search endpoint    |
| `VivaDataServicesTransactionDatas`          | A single transaction data record from the search endpoint        |
| `VivaDataServicesOrderBy`                   | Enum-like type for sort direction in data service queries        |
| `VivaDataServicesPaginationQuery`           | Shared pagination query parameters                               |
| `VivaSaleTransactionsExportOptions`         | Input options for `dataServices.requestSaleTransactionsExport()` |
| `VivaSaleTransactionsExportReturn`          | Response from a successful export initiation                     |
| `VivaSaleTransactionsWebhookDatas`          | Payload shape for sale transactions export webhook notifications |
| `VivaMt940DataReturn`                       | MT940 bank statement data object                                 |
| `VivaRetrieveMt940DataOptions`              | Input options for `dataServices.retrieveMt940Data()`             |
| `VivaAccountTransactionReturn`              | Account-level transaction record                                 |
| `VivaAccountTransactionsSearchOptions`      | Query options for account transaction search                     |

### Obligations

| Type                          | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `VivaCreateObligationOptions` | Input options for `obligations.createObligation()` |
| `VivaCreateObligationReturn`  | Response from a successful obligation creation     |

### Resellers

| Type                                  | Description                                          |
| ------------------------------------- | ---------------------------------------------------- |
| `VivaResellerCreateOrderOptions`      | Input options for creating a reseller payment order  |
| `VivaResellerCreateOrderReturn`       | Response from a successful reseller order creation   |
| `VivaResellerBillPaymentOptions`      | Input options for a reseller bill payment            |
| `VivaResellerBillPaymentReturn`       | Response from a successful bill payment              |
| `VivaResellerCashPaymentOptions`      | Input options for a reseller cash payment            |
| `VivaResellerCashPaymentReturn`       | Response from a successful cash payment              |
| `VivaResellerCheckBillPaymentOptions` | Input options for checking bill payment eligibility  |
| `VivaResellerCheckCashPaymentOptions` | Input options for checking cash payment eligibility  |
| `VivaResellerEligibilityReturn`       | Eligibility check response                           |
| `VivaResellerOtpOptions`              | Input options for OTP verification in reseller flows |

### RF Code Payments

| Type                         | Description                                          |
| ---------------------------- | ---------------------------------------------------- |
| `VivaGenerateRfCodesOptions` | Input options for `rfCodePayments.generateRfCodes()` |
| `VivaGenerateRfCodesReturn`  | Response with generated RF code references           |

### Legacy Bank Accounts

| Type                                    | Description                                             |
| --------------------------------------- | ------------------------------------------------------- |
| `VivaLegacyBankAccountReturn`           | Legacy bank account object                              |
| `VivaLegacyLinkBankAccountOptions`      | Input options for the legacy bank account link endpoint |
| `VivaLegacyOutgoingBankTransferOptions` | Input options for a legacy outgoing bank transfer       |
| `VivaLegacyOutgoingBankTransferReturn`  | Response from a successful legacy bank transfer         |

### Marketplace

| Type                              | Description                                                     |
| --------------------------------- | --------------------------------------------------------------- |
| `MPOrdersOptions`                 | Input options for creating a marketplace payment order          |
| `MPOrdersReturn`                  | Response from a successful marketplace order creation           |
| `MPCreateAccountDatas`            | Input data for creating a connected seller account              |
| `MPCreateAccountResponse`         | Response from a successful seller account creation              |
| `MPConnectedAccountReturn`        | A connected seller account object                               |
| `MPConnectedAccountAddress`       | Address sub-object for a connected account                      |
| `MPConnectedAccountBankAccount`   | Bank account sub-object for a connected account                 |
| `MPConnectedAccountBranding`      | Branding sub-object for a connected account                     |
| `MPConnectedAccountInvitation`    | Invitation details sub-object for a connected account           |
| `MPConnectedAccountPayouts`       | Payout settings sub-object for a connected account              |
| `MPCreateConnectedAccountPayouts` | Input shape for setting payout preferences                      |
| `MPUpdateConnectedAccountOptions` | Input options for `sellers.updateConnectedAccount()`            |
| `MPUpdateConnectedAccountReturn`  | Response from a successful account update                       |
| `MPPayoutDayOfWeek`               | String literal union for payout day configuration               |
| `MPPayoutInterval`                | String literal union for payout interval configuration          |
| `MPTransfersDatas`                | Input data for `marketplace.transfers.sendFunds()`              |
| `MPTransfersResponse`             | Response from a successful transfer send call                   |
| `MPCreateTransferReversalOptions` | Input options for creating a transfer reversal                  |
| `MPCreateTransferReversalReturn`  | Response from a successful reversal creation                    |
| `MPTransactionCancelOptions`      | Input options for cancelling a marketplace transaction          |
| `MPCancelTransactionReturn`       | Response from a successful marketplace transaction cancellation |