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

# Class: PurchaseManager

Purchase Manager - Clean, high-level interface for purchase operations

Provides a comprehensive API for purchase and payment management including payment
intent creation, purchase token handling, user purchase history, and integration
with payment processors. Handles both fiat currency payments and loyalty token
purchases within the ecosystem.

**`Example`**

```typescript
// Create payment intent for fiat purchase
const paymentIntent = await sdk.purchases.createPaymentIntent(
  50.00,
  'USD',
  'customer@example.com',
  'Loyalty token bundle purchase'
);
console.log('Payment intent created:', paymentIntent.id);

// Get available purchase tokens
const tokens = await sdk.purchases.getActivePurchaseTokens();
console.log(`${tokens.length} token packages available`);

// View purchase history
const purchases = await sdk.purchases.getAllUserPurchases();
console.log(`User has made ${purchases.length} purchases`);
```

**`Example`**

```typescript
// Browse available token packages
const availableTokens = await sdk.purchases.getActivePurchaseTokens(true);

console.log('Available Token Packages:');
availableTokens.forEach(token => {
  console.log(`\n${token.name}`);
  console.log(`Price: $${token.price} ${token.currency}`);
  console.log(`Tokens: ${token.tokenAmount} ${token.tokenSymbol}`);
  console.log(`Description: ${token.description}`);
});
```

**`Example`**

```typescript
// Create payment for specific token package
const selectedPackage = availableTokens[0];
const paymentIntent = await sdk.purchases.createPaymentIntent(
  selectedPackage.price,
  selectedPackage.currency,
  'user@example.com',
  `Purchase: ${selectedPackage.name}`
);

// Use payment intent client secret for frontend payment processing
console.log('Payment client secret:', paymentIntent.clientSecret);
```

## Table of contents

### Constructors

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


### Methods

- [createPaymentIntent](/sdk-reference/classes/purchasemanager#createpaymentintent)
- [getActivePurchaseTokens](/sdk-reference/classes/purchasemanager#getactivepurchasetokens)
- [getAllUserPurchases](/sdk-reference/classes/purchasemanager#getalluserpurchases)
- [getPurchaseService](/sdk-reference/classes/purchasemanager#getpurchaseservice)


## Constructors

### constructor

• **new PurchaseManager**(`apiClient`): [`PurchaseManager`](/sdk-reference/classes/purchasemanager)

#### Parameters

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


#### Returns

[`PurchaseManager`](/sdk-reference/classes/purchasemanager)

#### Defined in

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

## Methods

### createPaymentIntent

▸ **createPaymentIntent**(`amount`, `currency`, `receiptEmail`, `description`): `Promise`<`PaymentIntentDTO`>

Create a payment intent

Creates a payment intent for processing fiat currency payments through
integrated payment processors (e.g., Stripe). Payment intents are used to
securely handle payment processing on the frontend while maintaining
server-side validation and security.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `amount` | `number` | Payment amount in the specified currency's smallest unit (e.g., cents for USD) |
| `currency` | `string` | Payment currency code (e.g., 'USD', 'EUR', 'GBP') |
| `receiptEmail` | `string` | Email address for sending payment receipt |
| `description` | `string` | Human-readable description of the payment |


#### Returns

`Promise`<`PaymentIntentDTO`>

Promise resolving to payment intent with client secret

**`Throws`**

When payment processing is unavailable or validation fails

**`Example`**

```typescript
try {
  const paymentIntent = await sdk.purchases.createPaymentIntent(
    2500,  // $25.00 in cents
    'USD',
    'customer@example.com',
    '1000 Loyalty Points Package'
  );
  
  console.log('Payment Intent Created:');
  console.log('ID:', paymentIntent.id);
  console.log('Amount:', paymentIntent.amount / 100, paymentIntent.currency);
  console.log('Status:', paymentIntent.status);
  console.log('Client Secret:', paymentIntent.clientSecret);
  
  // Use client secret in frontend payment processing
  // Example with Stripe Elements:
  // const { confirmPayment } = useStripe();
  // await confirmPayment({
  //   elements,
  //   confirmParams: {
  //     return_url: 'https://yourapp.com/payment-success'
  //   }
  // });
  
} catch (error) {
  console.log('Payment intent creation failed:', error.message);
}
```

**`Example`**

```typescript
// Get available token packages first
const packages = await sdk.purchases.getActivePurchaseTokens(true);
const selectedPackage = packages.find(p => p.name === 'Starter Package');

if (selectedPackage) {
  const paymentIntent = await sdk.purchases.createPaymentIntent(
    selectedPackage.price * 100,  // Convert to cents
    selectedPackage.currency,
    'user@example.com',
    `Purchase: ${selectedPackage.name} - ${selectedPackage.tokenAmount} ${selectedPackage.tokenSymbol}`
  );
  
  console.log(`Payment setup for ${selectedPackage.name}`);
  console.log(`Will receive: ${selectedPackage.tokenAmount} ${selectedPackage.tokenSymbol}`);
  console.log(`Payment amount: $${selectedPackage.price}`);
  
  // Store payment intent for frontend processing
  localStorage.setItem('paymentIntentId', paymentIntent.id);
  localStorage.setItem('expectedTokens', selectedPackage.tokenAmount.toString());
}
```

**`Example`**

```typescript
// Create payment intent for recurring subscription
const subscriptionPayment = await sdk.purchases.createPaymentIntent(
  999,  // $9.99/month
  'USD',
  'subscriber@example.com',
  'Premium Loyalty Membership - Monthly'
);

console.log('Subscription payment intent:', subscriptionPayment.id);
// Payment processor will handle recurring billing setup
```

#### Defined in

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

### getActivePurchaseTokens

▸ **getActivePurchaseTokens**(`active?`, `options?`): `Promise`<`PaginatedResponseDTO`<`PurchaseTokenDTO`>>

Get active purchase tokens

Retrieves available token packages that users can purchase with fiat currency.
These packages represent bundles of loyalty tokens at various price points,
often with bonus tokens for larger purchases.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `active?` | `boolean` | Optional filter to show only active packages (default: all packages) |
| `options?` | `PaginationOptions` | - |


#### Returns

`Promise`<`PaginatedResponseDTO`<`PurchaseTokenDTO`>>

Promise resolving to array of purchase token packages

**`Example`**

```typescript
const allPackages = await sdk.purchases.getActivePurchaseTokens();
const activeOnly = await sdk.purchases.getActivePurchaseTokens(true);

console.log('Token Package Catalog:');

activeOnly.forEach(package => {
  console.log(`\n${package.name}`);
  console.log(`Price: $${package.price} ${package.currency}`);
  console.log(`🪙  Tokens: ${package.tokenAmount} ${package.tokenSymbol}`);
  console.log(`${package.description}`);
  
  // Calculate value per token
  const costPerToken = package.price / package.tokenAmount;
  console.log(`Value: $${costPerToken.toFixed(4)} per token`);
  
  if (package.bonusTokens && package.bonusTokens > 0) {
    console.log(`Bonus: +${package.bonusTokens} extra tokens`);
    const totalTokens = package.tokenAmount + package.bonusTokens;
    const actualCostPerToken = package.price / totalTokens;
    console.log(`With bonus: $${actualCostPerToken.toFixed(4)} per token`);
  }
  
  if (package.validUntil) {
    console.log(`⏰ Valid until: ${new Date(package.validUntil).toLocaleDateString()}`);
  }
});

// Find best value package
const bestValue = activeOnly.reduce((best, current) => {
  const currentValue = current.price / (current.tokenAmount + (current.bonusTokens || 0));
  const bestValue = best.price / (best.tokenAmount + (best.bonusTokens || 0));
  return currentValue < bestValue ? current : best;
});

console.log(`\n� Best Value: ${bestValue.name}`);
```

**`Example`**

```typescript
const packages = await sdk.purchases.getActivePurchaseTokens(true);

// Filter by currency
const usdPackages = packages.filter(p => p.currency === 'USD');
const eurPackages = packages.filter(p => p.currency === 'EUR');

console.log(`USD packages: ${usdPackages.length}`);
console.log(`EUR packages: ${eurPackages.length}`);

// Filter by price range
const budgetPackages = packages.filter(p => p.price <= 25);
const premiumPackages = packages.filter(p => p.price > 100);

console.log(`Budget options (≤$25): ${budgetPackages.length}`);
console.log(`Premium options (>$100): ${premiumPackages.length}`);

// Sort by token amount
const sortedByTokens = [...packages].sort((a, b) => 
  (b.tokenAmount + (b.bonusTokens || 0)) - (a.tokenAmount + (a.bonusTokens || 0))
);

console.log('\nTop 3 by token amount:');
sortedByTokens.slice(0, 3).forEach((pkg, index) => {
  const totalTokens = pkg.tokenAmount + (pkg.bonusTokens || 0);
  console.log(`${index + 1}. ${pkg.name}: ${totalTokens} tokens`);
});
```

#### Defined in

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

### getAllUserPurchases

▸ **getAllUserPurchases**(`options?`): `Promise`<`PaginatedResponseDTO`<`PurchaseDTO`>>

Get all user purchases

Retrieves the complete purchase history for the authenticated user,
including both successful and failed purchases. Provides insights into
user spending patterns, token acquisition, and payment history.

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `PaginationOptions` |


#### Returns

`Promise`<`PaginatedResponseDTO`<`PurchaseDTO`>>

Promise resolving to array of user's purchase records

**`Example`**

```typescript
const userPurchases = await sdk.purchases.getAllUserPurchases();

console.log(`Purchase History (${userPurchases.length} purchases):`);

userPurchases.forEach((purchase, index) => {
  console.log(`\n${index + 1}. Purchase #${purchase.id}`);
  console.log(`Date: ${new Date(purchase.createdAt).toLocaleDateString()}`);
  console.log(`Amount: $${purchase.amount} ${purchase.currency}`);
  console.log(`Status: ${purchase.status}`);
  
  if (purchase.description) {
    console.log(`Description: ${purchase.description}`);
  }
  
  if (purchase.tokensReceived) {
    console.log(`🪙  Tokens received: ${purchase.tokensReceived}`);
  }
  
  if (purchase.paymentMethod) {
    console.log(`Payment method: ${purchase.paymentMethod}`);
  }
  
  if (purchase.receiptEmail) {
    console.log(`� Receipt sent to: ${purchase.receiptEmail}`);
  }
});

// Calculate purchase statistics
const successfulPurchases = userPurchases.filter(p => p.status === 'COMPLETED');
const totalSpent = successfulPurchases.reduce((sum, p) => sum + p.amount, 0);
const totalTokens = successfulPurchases.reduce((sum, p) => sum + (p.tokensReceived || 0), 0);

console.log('\nPurchase Statistics:');
console.log(`Total purchases: ${userPurchases.length}`);
console.log(`Successful purchases: ${successfulPurchases.length}`);
console.log(`Total spent: $${totalSpent.toFixed(2)}`);
console.log(`Total tokens acquired: ${totalTokens}`);

if (totalTokens > 0) {
  const avgCostPerToken = totalSpent / totalTokens;
  console.log(`Average cost per token: $${avgCostPerToken.toFixed(4)}`);
}
```

**`Example`**

```typescript
const purchases = await sdk.purchases.getAllUserPurchases();

// Analyze by time period
const last30Days = purchases.filter(p => 
  new Date(p.createdAt) > new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
);

const last6Months = purchases.filter(p => 
  new Date(p.createdAt) > new Date(Date.now() - 180 * 24 * 60 * 60 * 1000)
);

console.log('Purchase Timeline:');
console.log(`Last 30 days: ${last30Days.length} purchases`);
console.log(`Last 6 months: ${last6Months.length} purchases`);

// Analyze by status
const statusCounts = purchases.reduce((acc, p) => {
  acc[p.status] = (acc[p.status] || 0) + 1;
  return acc;
}, {});

console.log('\nBy status:');
Object.entries(statusCounts).forEach(([status, count]) => {
  console.log(`${status}: ${count} purchases`);
});

// Find largest and most recent purchases
const largestPurchase = purchases.reduce((max, current) => 
  current.amount > max.amount ? current : max, purchases[0]
);

const mostRecent = purchases.reduce((newest, current) => 
  new Date(current.createdAt) > new Date(newest.createdAt) ? current : newest, purchases[0]
);

if (largestPurchase) {
  console.log(`\nLargest purchase: $${largestPurchase.amount} on ${new Date(largestPurchase.createdAt).toLocaleDateString()}`);
}

if (mostRecent) {
  console.log(`⏰ Most recent: $${mostRecent.amount} on ${new Date(mostRecent.createdAt).toLocaleDateString()}`);
}
```

#### Defined in

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

### getPurchaseService

▸ **getPurchaseService**(): [`PaymentService`](/sdk-reference/classes/paymentservice)

Get the full purchase service for advanced operations

Provides access to the complete PaymentService instance for advanced purchase
operations, payment processor integrations, subscription management, and
operations not covered by the high-level manager methods.

#### Returns

[`PaymentService`](/sdk-reference/classes/paymentservice)

PaymentService instance with full API access

**`Example`**

```typescript
const paymentService = sdk.purchases.getPurchaseService();

// Access advanced payment analytics
const analytics = await paymentService.getPaymentAnalytics();

// Access subscription management
const subscriptions = await paymentService.getUserSubscriptions();

// Access payment method management
const paymentMethods = await paymentService.getUserPaymentMethods();

// Access payment API directly
const paymentApi = paymentService.api;

// Use advanced purchase validation
const validation = await paymentService.validatePurchaseEligibility('token-package-123');

// Access payment processor webhooks
const webhookHandler = paymentService.createWebhookHandler();
```

#### Defined in

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