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:

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.

// Success case
{ success: true; data: TData; message: string }

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

Usage example:

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

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:

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