[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / TransactionManager

# Class: TransactionManager

Transaction Manager - Clean, high-level interface for transaction operations

Provides a comprehensive API for loyalty transaction management including transaction
creation, history tracking, reporting, and administrative oversight. Transactions
are the core financial operations that track token movements, purchases, rewards,
and all value exchanges within the loyalty ecosystem.

**`Example`**

```typescript
// Create a purchase transaction
const transaction = await sdk.transactions.createTransaction({
  type: 'PURCHASE',
  amount: 100.00,
  currency: 'USD',
  businessId: 'partner-store-123',
  description: 'Coffee shop purchase'
});

// Get transaction details
const details = await sdk.transactions.getTransactionById(transaction.id);
console.log('Transaction:', details.description, details.status);

// View transaction history
const history = await sdk.transactions.getUserTransactionHistory('ALL');
console.log(`Found ${history.length} transactions`);
```

**`Example`**

```typescript
// Get different types of transactions
const purchases = await sdk.transactions.getUserTransactionHistory('PURCHASE');
const rewards = await sdk.transactions.getUserTransactionHistory('REWARD');
const redemptions = await sdk.transactions.getUserTransactionHistory('REDEMPTION');

console.log('Transaction Summary:');
console.log(`Purchases: ${purchases.length}`);
console.log(`Rewards: ${rewards.length}`);
console.log(`Redemptions: ${redemptions.length}`);
```

**`Example`**

```typescript
// Admin: Get paginated transactions for analysis
const allTransactions = await sdk.transactions.getPaginatedTransactions({ page: 1, limit: 100 });

// Export transaction data
const csvBlob = await sdk.transactions.exportTransactionsCSV();
const downloadUrl = URL.createObjectURL(csvBlob);
console.log('Download transaction report:', downloadUrl);
```

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/transactionmanager#constructor)


### Methods

- [getTransactionById](/sdk-reference/classes/transactionmanager#gettransactionbyid)
- [createTransaction](/sdk-reference/classes/transactionmanager#createtransaction)
- [getUserTransactionHistory](/sdk-reference/classes/transactionmanager#getusertransactionhistory)
- [getPaginatedTransactions](/sdk-reference/classes/transactionmanager#getpaginatedtransactions)
- [exportCSV](/sdk-reference/classes/transactionmanager#exportcsv)
- [exportTransactionsCSV](/sdk-reference/classes/transactionmanager#exporttransactionscsv)
- [prepareExistingTransaction](/sdk-reference/classes/transactionmanager#prepareexistingtransaction)
- [prepareClientSignedTransaction](/sdk-reference/classes/transactionmanager#prepareclientsignedtransaction)
- [submitSignedTransaction](/sdk-reference/classes/transactionmanager#submitsignedtransaction)
- [queryTransactionsBySender](/sdk-reference/classes/transactionmanager#querytransactionsbysender)
- [queryTransactionsByRecipient](/sdk-reference/classes/transactionmanager#querytransactionsbyrecipient)
- [getTransactionAnalytics](/sdk-reference/classes/transactionmanager#gettransactionanalytics)
- [getTransactionService](/sdk-reference/classes/transactionmanager#gettransactionservice)


## Constructors

### constructor

• **new TransactionManager**(`apiClient`, `events?`): [`TransactionManager`](/sdk-reference/classes/transactionmanager)

#### Parameters

| Name | Type |
|  --- | --- |
| `apiClient` | [`PersApiClient`](/sdk-reference/classes/persapiclient) |
| `events?` | [`PersEventEmitter`](/sdk-reference/classes/perseventemitter) |


#### Returns

[`TransactionManager`](/sdk-reference/classes/transactionmanager)

#### Defined in

[managers/transaction-manager.ts:65](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L65)

## Methods

### getTransactionById

▸ **getTransactionById**(`transactionId`, `include?`): `Promise`<`TransactionDTO`>

Get transaction by ID

Retrieves detailed information for a specific transaction including status,
amounts, participants, token transfers, and blockchain confirmations.
Provides complete transaction audit trail and verification data.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `transactionId` | `string` | Unique transaction identifier |
| `include?` | `TransactionIncludeRelation`[] | Optional relations to include (sender, recipient, business) for enriched entity data |


#### Returns

`Promise`<`TransactionDTO`>

Promise resolving to complete transaction data

**`Throws`**

When transaction with specified ID is not found or access denied

**`Example`**

```typescript
try {
  // Get transaction with enriched sender/recipient data
  const transaction = await sdk.transactions.getTransactionById(
    'txn-abc123',
    ['sender', 'recipient', 'business']
  );
  
  console.log('Transaction Details:');
  console.log('ID:', transaction.id);
  console.log('Type:', transaction.type);
  console.log('Status:', transaction.status);
  console.log('Amount:', transaction.amount, transaction.currency);
  console.log('Date:', new Date(transaction.createdAt).toLocaleString());
  
  if (transaction.description) {
    console.log('Description:', transaction.description);
  }
  
  // Access enriched sender data
  if (transaction.included?.sender) {
    console.log('Sender:', transaction.included.sender);
  }
  
  // Access enriched recipient data
  if (transaction.included?.recipient) {
    console.log('Recipient:', transaction.included.recipient);
  }
  
  // Access enriched business data
  if (transaction.included?.engagedBusiness) {
    console.log('Business:', transaction.included.engagedBusiness.displayName);
  }
  
  // Show blockchain confirmation
  if (transaction.blockchainHash) {
    console.log('Blockchain:', transaction.blockchainHash);
  }
  
} catch (error) {
  console.log('Transaction not found or access denied:', error.message);
}
```

#### Defined in

[managers/transaction-manager.ts:130](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L130)

### createTransaction

▸ **createTransaction**(`transactionData`): `Promise`<`TransactionRequestResponseDTO`>

Create a new transaction

Creates a new transaction in the loyalty system, processing token transfers,
applying rewards, and updating user balances. Supports various transaction
types including purchases, rewards, redemptions, and transfers.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `transactionData` | `TransactionRequestDTO` | Transaction configuration including type, amounts, and context |


#### Returns

`Promise`<`TransactionRequestResponseDTO`>

Promise resolving to transaction creation response

**`Throws`**

When validation fails or insufficient balance

**`Example`**

```typescript
try {
  const purchase = await sdk.transactions.createTransaction({
    type: 'PURCHASE',
    amount: 25.50,
    currency: 'USD',
    businessId: 'coffee-shop-123',
    description: 'Morning coffee and pastry',
    metadata: {
      items: ['Latte', 'Croissant'],
      location: 'Downtown Store'
    }
  });
  
  console.log('Purchase completed!');
  console.log('Transaction ID:', purchase.id);
  console.log('Status:', purchase.status);
  
  if (purchase.tokensEarned?.length) {
    console.log('\nLoyalty rewards earned:');
    purchase.tokensEarned.forEach(reward => {
      console.log(`${reward.amount} ${reward.token.symbol}`);
    });
  }
  
} catch (error) {
  console.log('Transaction failed:', error.message);
}
```

**`Example`**

```typescript
// Create reward transaction (typically triggered by campaigns)
const reward = await sdk.transactions.createTransaction({
  type: 'REWARD',
  businessId: 'partner-hotel-456',
  description: 'Welcome bonus for new customer',
  tokenRewards: [
    {
      tokenId: 'loyalty-points',
      amount: 500
    }
  ]
});

console.log('Reward transaction created:', reward.id);
```

**`Example`**

```typescript
// Create token transfer between users
const transfer = await sdk.transactions.createTransaction({
  type: 'TRANSFER',
  recipientUserId: 'user-789',
  description: 'Gift to friend',
  tokenTransfers: [
    {
      tokenId: 'loyalty-points',
      amount: 100,
      direction: 'OUTBOUND'
    }
  ]
});

console.log('Transfer initiated:', transfer.id);
```

#### Defined in

[managers/transaction-manager.ts:216](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L216)

### getUserTransactionHistory

▸ **getUserTransactionHistory**(`options?`): `Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Get user's transaction history

Retrieves transaction history for the authenticated user with comprehensive
filtering options. Provides chronological view of all user's loyalty
activities including purchases, rewards, redemptions, and transfers.
Optionally enrich with related entities (sender, recipient, business).

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `TransactionQueryParams` | Query options including filters, pagination, and include relations |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Promise resolving to paginated transaction data with optional included entities

**`Example`**

```typescript
const result = await sdk.transactions.getUserTransactionHistory();

console.log(`Transaction History (${result.data.length} of ${result.pagination.total} transactions)`);

result.data.forEach((transaction, index) => {
  const date = new Date(transaction.createdAt).toLocaleDateString();
  console.log(`\n${index + 1}. ${transaction.type} - ${date}`);
  console.log(`   ${transaction.description || 'No description'}`);
  console.log(`   Status: ${transaction.status}`);
});
```

**`Example`**

```typescript
// Get only completed sent transactions
const sent = await sdk.transactions.getUserTransactionHistory({
  role: TransactionRole.SENDER,
  status: TransactionStatus.COMPLETED,
  include: ['recipient', 'business'],
  page: 1,
  limit: 50
});

sent.data.forEach(tx => {
  console.log(`Sent to: ${tx.included?.recipient?.displayName || tx.recipientAddress}`);
});
```

**`Example`**

```typescript
// Get all transactions triggered by a specific campaign claim
const claimTxs = await sdk.transactions.getUserTransactionHistory({
  triggerProcessId: 'claim-abc123',
  include: ['sender', 'recipient', 'business']
});

claimTxs.data.forEach(tx => {
  console.log('Transaction from claim:', tx.id);
  if (tx.included?.engagedBusiness) {
    console.log('Business:', tx.included.engagedBusiness.displayName);
  }
});
```

#### Defined in

[managers/transaction-manager.ts:286](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L286)

### getPaginatedTransactions

▸ **getPaginatedTransactions**(`options`): `Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Admin: Get paginated transactions

Retrieves transactions with pagination support for efficient large dataset
handling. This operation requires administrator privileges and is used for
detailed transaction analysis and reporting interfaces.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options` | `TransactionPaginationRequestDTO` & { `include?`: `TransactionIncludeRelation`[]  } | Pagination, filtering parameters, and optional include relations |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Promise resolving to paginated transaction results with metadata

**`Throws`**

When not authenticated as administrator

**`Example`**

```typescript
// Admin operation - paginated transaction retrieval
const result = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 50,
  sortBy: 'createdAt',
  sortOrder: 'DESC'
});

console.log(`� Page ${result.page} of ${result.totalPages}`);
console.log(`Showing ${result.data.length} of ${result.total} transactions`);

result.data.forEach((transaction, index) => {
  console.log(`${index + 1}. ${transaction.type} - ${transaction.status}`);
  console.log(`   ${new Date(transaction.createdAt).toLocaleDateString()}`);
});

// Continue pagination if needed
if (result.hasNextPage) {
  const nextPage = await sdk.transactions.getPaginatedTransactions({
    page: result.page + 1,
    limit: 50
  });
}
```

**`Example`**

```typescript
// Admin operation - filter transactions by criteria
const filteredResult = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 25,
  filters: {
    type: 'PURCHASE',
    status: 'COMPLETED',
    businessId: 'partner-store-123',
    dateFrom: '2024-01-01',
    dateTo: '2024-12-31'
  },
  sortBy: 'amount',
  sortOrder: 'DESC'
});

console.log('Filtered Results:');
console.log(`Found ${filteredResult.total} matching transactions`);

filteredResult.data.forEach(transaction => {
  console.log(`$${transaction.amount} - ${transaction.business?.displayName}`);
});
```

**`Example`**

```typescript
// Include sender and recipient entities
const result = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 50,
  include: ['sender', 'recipient', 'business']
});

result.data.forEach(tx => {
  if (tx.included?.sender) console.log('From:', tx.included.sender);
  if (tx.included?.recipient) console.log('To:', tx.included.recipient);
});
```

#### Defined in

[managers/transaction-manager.ts:370](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L370)

### exportCSV

▸ **exportCSV**(`options?`): `Promise`<`Blob`>

Admin: Export transactions as CSV

Generates a comprehensive CSV export of all tenant transactions for
external analysis, reporting, or compliance purposes. This operation
requires administrator privileges and creates a downloadable file.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `Object` | Optional date range filters |
| `options.dateFrom?` | `string` | Start date filter (ISO date string) |
| `options.dateTo?` | `string` | End date filter (ISO date string) |


#### Returns

`Promise`<`Blob`>

Promise resolving to CSV blob for download

**`Throws`**

When not authenticated as administrator or export fails

**`Example`**

```typescript
const csvBlob = await sdk.transactions.exportCSV();
const downloadUrl = URL.createObjectURL(csvBlob);
```

**`Example`**

```typescript
const csvBlob = await sdk.transactions.exportCSV({
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31'
});
```

#### Defined in

[managers/transaction-manager.ts:405](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L405)

### exportTransactionsCSV

▸ **exportTransactionsCSV**(`options?`): `Promise`<`Blob`>

Admin: Export transactions as CSV

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `Object` |
| `options.dateFrom?` | `string` |
| `options.dateTo?` | `string` |


#### Returns

`Promise`<`Blob`>

**`Deprecated`**

Use `exportCSV()` instead for consistent naming across all managers

#### Defined in

[managers/transaction-manager.ts:414](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L414)

### prepareExistingTransaction

▸ **prepareExistingTransaction**(`transactionId`): `Promise`<`TransactionRequestResponseDTO`>

Prepare existing transaction for client-side signing

Retrieves the necessary data to sign an existing transaction on the client side.
This is typically used when a transaction has been created but requires user signature.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `transactionId` | `string` | The ID of the transaction to prepare |


#### Returns

`Promise`<`TransactionRequestResponseDTO`>

Promise resolving to the transaction preparation data

#### Defined in

[managers/transaction-manager.ts:427](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L427)

### prepareClientSignedTransaction

▸ **prepareClientSignedTransaction**(`request`): `Promise`<`TransactionRequestResponseDTO`>

Prepare a new transaction for client-side signing

Creates a new transaction and immediately returns the data needed for client-side signing.
This combines creation and preparation into a single flow for client-signed operations.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `request` | `TransactionRequestDTO` | The transaction request details |


#### Returns

`Promise`<`TransactionRequestResponseDTO`>

Promise resolving to the transaction preparation data

#### Defined in

[managers/transaction-manager.ts:440](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L440)

### submitSignedTransaction

▸ **submitSignedTransaction**(`signedTxData`): `Promise`<`TransactionRequestResponseDTO`>

Submit a signed transaction

Submits a transaction that has been signed on the client side to the backend for processing.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `signedTxData` | `TransactionSubmissionRequestDTO` | The signed transaction data |


#### Returns

`Promise`<`TransactionRequestResponseDTO`>

Promise resolving to the submission result

#### Defined in

[managers/transaction-manager.ts:452](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L452)

### queryTransactionsBySender

▸ **queryTransactionsBySender**(`accountSelector`): `Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Query transactions by sender

Retrieves transactions where the specified account is the sender.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `accountSelector` | `AccountSelectorDTO` | Selector for the sender account |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Promise resolving to paginated transactions

#### Defined in

[managers/transaction-manager.ts:473](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L473)

### queryTransactionsByRecipient

▸ **queryTransactionsByRecipient**(`accountSelector`): `Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Query transactions by recipient

Retrieves transactions where the specified account is the recipient.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `accountSelector` | `AccountSelectorDTO` | Selector for the recipient account |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TransactionDTO`>>

Promise resolving to paginated transactions

#### Defined in

[managers/transaction-manager.ts:485](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L485)

### getTransactionAnalytics

▸ **getTransactionAnalytics**(`analyticsRequest`): `Promise`<`TransactionAnalyticsResponseDTO`>

Get transaction analytics

Retrieves analytics data for transactions based on the provided request criteria.
Useful for generating reports and dashboards.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `analyticsRequest` | `TransactionAnalyticsRequestDTO` | The analytics query parameters |


#### Returns

`Promise`<`TransactionAnalyticsResponseDTO`>

Promise resolving to the analytics data

#### Defined in

[managers/transaction-manager.ts:498](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L498)

### getTransactionService

▸ **getTransactionService**(): [`TransactionService`](/sdk-reference/classes/transactionservice)

Get the full transaction service for advanced operations

Provides access to the complete TransactionService instance for advanced
transaction operations, custom analytics, blockchain interactions, and
operations not covered by the high-level manager methods.

#### Returns

[`TransactionService`](/sdk-reference/classes/transactionservice)

TransactionService instance with full API access

**`Example`**

```typescript
const transactionService = sdk.transactions.getTransactionService();

// Access advanced transaction analytics
const analytics = await transactionService.getTransactionAnalytics({
  timeframe: 'last-30-days',
  groupBy: 'business'
});

// Access blockchain transaction monitoring
const blockchainStatus = await transactionService.getBlockchainTransactionStatus('txn-123');

// Access transaction API directly
const transactionApi = transactionService.api;

// Use advanced validation and verification
const verification = await transactionService.verifyTransactionIntegrity('txn-456');

// Access real-time transaction streaming
const stream = transactionService.subscribeToTransactionUpdates();
stream.on('transaction', (transaction) => {
  console.log('New transaction:', transaction.id);
});
```

#### Defined in

[managers/transaction-manager.ts:537](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/transaction-manager.ts#L537)