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

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

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

## Retrieve a transaction

Call `getTransactionById(transactionId)` with the Viva transaction UUID.

```typescript theme={null}
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.

```typescript theme={null}
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`.

```typescript theme={null}
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.

```typescript theme={null}
const order = await vivawallet.payments.createOrder({
  amount: 5000,
  customerTrns: 'Phone order #5678',
  customer: {
    email: 'jane@example.com',
    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: 'jane@example.com',
  creditcard: {
    number: '4111111111111111',
    expirationDate: '2030-12',
    cvc: '123',
  },
  sourceCode: 'Default',
});

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

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

## Create a card token

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

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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)`.

```typescript theme={null}
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.

```typescript theme={null}
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?)`.

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

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