Retrieve and Manage VivaWallet Payment Transactions

Retrieve transaction details, cancel transactions, issue refunds, create card tokens, and run advanced transaction operations through the transactions module.

Use vivawallet.transactions for operations that target one transaction at a time: retrieving a transaction by ID, refunding or cancelling it, capturing a transaction, creating a card token, and running advanced flows such as MOTO charges, incremental pre-authorizations, rebates, fast refunds, and OCT / Pay Out.

Use vivawallet.dataServices for bulk transaction search, filtered reporting, MT940 data, and sale transaction exports. The transactions module focuses on individual transaction actions.

Retrieve a transaction

Call getTransactionById(transactionId) with the Viva transaction UUID.

const result = await vivawallet.transactions.getTransactionById(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
);

if (result.success && result.data) {
  console.log(result.data.statusId);
  console.log(result.data.amount);
}

Common statusId values returned by the SDK type:

Value	Meaning
F	Finished
A	Active
C	Captured
E	Error
R	Refunded
X	Cancelled
M	Claimed / disputed

The SDK returns Viva’s response shape directly. It does not normalize transaction amounts or status fields.

Cancel or refund a transaction

Call cancelTransaction(transactionId, refundOptions). The current SDK type requires an amount; pass the amount you want to refund in the currency’s smallest unit.

const cancelResult = await vivawallet.transactions.cancelTransaction(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 1000,
    merchantTrns: 'refund-order-1234',
    customerTrns: 'Refund for Order #1234',
    sourceCode: 'Default',
  },
);

if (cancelResult.success && cancelResult.data) {
  console.log('Refund transaction:', cancelResult.data.TransactionId);
}

Capture or create a transaction

Use createTransaction(options) when Viva expects a transaction payload containing the initial transaction id.

const captureResult = await vivawallet.transactions.createTransaction({
  id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  amount: 5000,
  merchantTrns: 'capture-order-1234',
  customerTrns: 'Capture for Order #1234',
  sourceCode: 'Default',
});

if (captureResult.success && captureResult.data) {
  console.log('Transaction:', captureResult.data.TransactionId);
}

makeTransaction(options) is still available as a deprecated alias for createTransaction(options).

MOTO card charge

A Mail Order / Telephone Order (MOTO) charge uses makeMotoCardCharge(options). The charge references an existing payment order via orderCode; the card details are sent in the creditcard object.

const order = await vivawallet.payments.createOrder({
  amount: 5000,
  customerTrns: 'Phone order #5678',
  customer: {
    email: '[e-mail]',
    fullName: 'Jane Doe',
  },
  sourceCode: 'Default',
});

if (!order.success || !order.data) {
  throw new Error('Failed to create payment order');
}

const motoResult = await vivawallet.transactions.makeMotoCardCharge({
  moto: true,
  orderCode: order.data.orderCode,
  fullName: 'Jane Doe',
  email: '[e-mail]',
  creditcard: {
    number: '4111111111111111',
    expirationDate: '2030-12',
    cvc: '123',
  },
  sourceCode: 'Default',
});

if (motoResult.success && motoResult.data) {
  console.log('MOTO charge:', motoResult.data.TransactionId);
}

MOTO charges require you to handle raw card details. Make sure the integration is PCI-DSS compliant before using this flow.

Create a card token

Use createCardToken(options) to obtain a reusable token associated with the card used for a previous transaction.

const tokenResult = await vivawallet.transactions.createCardToken({
  transactionId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  cardTokenType: 0,
});

if (tokenResult.success && tokenResult.data) {
  console.log('Card token:', tokenResult.data.token);
}

The returned type exposes token plus any additional fields returned by Viva.

Incremental pre-authorization

Use increasePreauth(transactionId, options) to increase the amount on an existing pre-authorized transaction.

const preauthResult = await vivawallet.transactions.increasePreauth(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 2000,
    merchantTrns: 'additional-hold-1234',
    idempotencyKey: 'preauth-1234-1',
  },
);

Cancel partial authorization

Use cancelPartialAuthorization(transactionId, options) to release part of an existing partial authorization.

const partialCancelResult = await vivawallet.transactions.cancelPartialAuthorization(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 500,
    merchantTrns: 'release-hold-1234',
  },
);

Rebate and fast refund

rebate(transactionId, options) and fastRefund(transactionId, options) create follow-up credit transactions tied to an original transaction.

const rebateResult = await vivawallet.transactions.rebate(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 500,
    merchantTrns: 'rebate-order-1234',
    idempotencyKey: 'rebate-1234-1',
  },
);

const fastRefundResult = await vivawallet.transactions.fastRefund(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 1000,
    merchantTrns: 'fast-refund-order-1234',
    idempotencyKey: 'fast-refund-1234-1',
  },
);

To cancel a rebate or fast refund, call cancelRebateOrFastRefund(transactionId, options).

await vivawallet.transactions.cancelRebateOrFastRefund(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 1000,
    merchantTrns: 'cancel-fast-refund-1234',
    idempotencyKey: 'cancel-fast-refund-1234-1',
  },
);

OCT / Pay Out

Use octAndPayout(transactionId, options) for the OCT / Pay Out endpoint. serviceId selects the operation: 6 for OCT, 14 for Pay Out.

const payoutResult = await vivawallet.transactions.octAndPayout(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  {
    amount: 10000,
    serviceId: 14,
    idempotencyKey: 'payout-1234-1',
    sourceCode: 'Default',
    merchantTrns: 'Marketplace payout',
  },
);

if (payoutResult.success && payoutResult.data) {
  console.log('Payout transaction:', payoutResult.data.TransactionId);
}

Legacy transaction lookup

For older Basic Auth integrations, use getLegacyTransactions(transactionId?, query?).

const legacyResult = await vivawallet.transactions.getLegacyTransactions(
  'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  { sourceCode: 'Default' },
);

if (legacyResult.success && legacyResult.data) {
  console.log(legacyResult.data.Transactions);
}