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

# Class: PaymentApi

Platform-Agnostic Purchase API Client (RESTful Architecture)

Handles purchase and payment operations using the PERS backend's new RESTful endpoints.
Uses @explorins/pers-shared DTOs for consistency with backend.

Migration Status: Updated to match /purchases controller (replaces /purchase endpoints)

Available Access Levels:

- PUBLIC: Project key authentication for catalog browsing and payment operations
- USER: Requires user authentication JWT (purchase creation, history access)
- ADMIN: Requires tenant admin privileges (not implemented in this client)


Note: This SDK focuses on backend purchase operations only.
Payment provider integrations (Stripe, etc.) should remain in infrastructure layer.

## Table of contents

### Constructors

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


### Methods

- [getPurchaseTokens](/sdk-reference/classes/paymentapi#getpurchasetokens)
- [getDonationTypes](/sdk-reference/classes/paymentapi#getdonationtypes)
- [createPaymentIntent](/sdk-reference/classes/paymentapi#createpaymentintent)
- [updatePaymentIntent](/sdk-reference/classes/paymentapi#updatepaymentintent)
- [cancelPaymentIntent](/sdk-reference/classes/paymentapi#cancelpaymentintent)
- [createUserPurchase](/sdk-reference/classes/paymentapi#createuserpurchase)
- [getUserPurchaseHistory](/sdk-reference/classes/paymentapi#getuserpurchasehistory)


## Constructors

### constructor

• **new PaymentApi**(`apiClient`): [`PaymentApi`](/sdk-reference/classes/paymentapi)

#### Parameters

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


#### Returns

[`PaymentApi`](/sdk-reference/classes/paymentapi)

#### Defined in

[payment/api/payment-api.ts:32](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L32)

## Methods

### getPurchaseTokens

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

PUBLIC: Get purchase tokens (Intelligent Access)

RESTful endpoint: GET /purchases/tokens
Replaces: GET /purchase/token

INTELLIGENT ACCESS:

- PUBLIC (Project Key): Returns active tokens only (active parameter ignored)
- ADMIN (Tenant Admin JWT): Returns filtered results based on active parameter


#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `active?` | `boolean` | Filter by active status |
| `options?` | `PaginationOptions` | Pagination options (page, limit, sortBy, sortOrder) |


#### Returns

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

Paginated response with purchase tokens

#### Defined in

[payment/api/payment-api.ts:54](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L54)

### getDonationTypes

▸ **getDonationTypes**(`options?`): `Promise`<`PaginatedResponseDTO`<`DonationTypeDTO`>>

PUBLIC: Get donation types

RESTful endpoint: GET /purchases/donation-types
Replaces: GET /purchase/donation/type

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `PaginationOptions` | Pagination options (page, limit, sortBy, sortOrder) |


#### Returns

`Promise`<`PaginatedResponseDTO`<`DonationTypeDTO`>>

Paginated response with donation types

#### Defined in

[payment/api/payment-api.ts:72](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L72)

### createPaymentIntent

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

PUBLIC: Create payment intent (FINANCIAL OPERATION)

RESTful endpoint: POST /purchases/payment-intents
Replaces: POST /purchase/payment-intent

CRITICAL: Handles real money operations - tenant context required

#### Parameters

| Name | Type |
|  --- | --- |
| `amount` | `number` |
| `currency` | `EUR` |
| `receiptEmail` | `string` |
| `description` | `string` |


#### Returns

`Promise`<`PaymentIntentDTO`>

#### Defined in

[payment/api/payment-api.ts:90](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L90)

### updatePaymentIntent

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

PUBLIC: Update payment intent (FINANCIAL OPERATION)

RESTful endpoint: PUT /purchases/payment-intents/{paymentIntentId}
Replaces: PUT /purchase/payment-intent/{paymentIntentId}

CRITICAL: Handles real money operations - tenant context required

#### Parameters

| Name | Type |
|  --- | --- |
| `paymentIntentId` | `string` |
| `amount` | `number` |
| `currency` | `EUR` |
| `receiptEmail` | `string` |
| `description` | `string` |


#### Returns

`Promise`<`PaymentIntentDTO`>

#### Defined in

[payment/api/payment-api.ts:108](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L108)

### cancelPaymentIntent

▸ **cancelPaymentIntent**(`paymentIntentId`): `Promise`<`PaymentIntentDTO`>

PUBLIC: Cancel payment intent (FINANCIAL OPERATION)

RESTful endpoint: DELETE /purchases/payment-intents/{paymentIntentId}
Replaces: DELETE /purchase/payment-intent/{paymentIntentId}

CRITICAL: Handles real money operations - tenant context required

#### Parameters

| Name | Type |
|  --- | --- |
| `paymentIntentId` | `string` |


#### Returns

`Promise`<`PaymentIntentDTO`>

#### Defined in

[payment/api/payment-api.ts:126](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L126)

### createUserPurchase

▸ **createUserPurchase**(`paymentIntentId`, `amount`, `purchaseTokenId?`, `donationTypeId?`, `donationAccountAddress?`): `Promise`<`PurchaseCreateResponseDTO`>

USER: Create purchase (BUSINESS CRITICAL - FINANCIAL TRANSACTION)

RESTful endpoint: POST /purchases
Replaces: POST /purchase/auth

USER-ONLY: Requires user authentication JWT for purchase creation
CRITICAL: Real financial transaction with Stripe integration

#### Parameters

| Name | Type |
|  --- | --- |
| `paymentIntentId` | `string` |
| `amount` | `number` |
| `purchaseTokenId?` | `string` |
| `donationTypeId?` | `number` |
| `donationAccountAddress?` | `string` |


#### Returns

`Promise`<`PurchaseCreateResponseDTO`>

#### Defined in

[payment/api/payment-api.ts:143](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L143)

### getUserPurchaseHistory

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

USER: Get user purchase history

RESTful endpoint: GET /purchases/me/history
Replaces: GET /purchase/auth

USER-ONLY: Get authenticated user's purchase history
FINANCIAL RECORDS: User attribution critical for compliance

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `PaginationOptions` | Pagination options (page, limit, sortBy, sortOrder) |


#### Returns

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

Paginated response with purchase history

#### Defined in

[payment/api/payment-api.ts:166](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/payment/api/payment-api.ts#L166)