liqpay-nestjs 0.2.15 → 0.2.17

package/README.md

@@ -1,15 +1,347 @@
 # liqpay-nestjs
 
-To install dependencies:
+NestJS module for LiqPay payments with DI-friendly configuration, signed checkout helpers, typed request and response models, and webhook callback parsing.
+
+## Features
+
+- NestJS module with `forRoot` and `forRootAsync`
+- `LiqpayService` with payment and webhook helpers
+- Signed checkout URL and checkout form generation
+- Typed payment status requests
+- Callback signature validation and payload parsing
+- Exported Zod schemas and TypeScript types from the package root
+
+## Requirements
+
+- Node.js `>= 18`
+- `@nestjs/common` `^10 || ^11`
+- `@nestjs/core` `^10 || ^11`
+
+## Installation
 
 ```bash
-bun install
+npm install liqpay-nestjs
 ```
 
-To run:
+## Quick Start
 
-```bash
-bun run index.ts
+### Register the module
+
+```ts
+import { Module } from '@nestjs/common'
+import { LiqPayModule } from 'liqpay-nestjs'
+
+@Module({
+	imports: [
+		LiqPayModule.forRoot({
+			publicKey: process.env.LIQPAY_PUBLIC_KEY!,
+			privateKey: process.env.LIQPAY_PRIVATE_KEY!,
+			resultUrl: 'https://example.com/payments/result',
+			serverUrl: 'https://example.com/payments/webhook',
+			isGlobal: true,
+		}),
+	],
+})
+export class AppModule {}
+```
+
+### Register the module asynchronously
+
+```ts
+import { Module } from '@nestjs/common'
+import { ConfigModule, ConfigService } from '@nestjs/config'
+import { LiqPayModule } from 'liqpay-nestjs'
+
+@Module({
+	imports: [
+		ConfigModule.forRoot(),
+		LiqPayModule.forRootAsync({
+			imports: [ConfigModule],
+			inject: [ConfigService],
+			useFactory: (config: ConfigService) => ({
+				publicKey: config.getOrThrow<string>('LIQPAY_PUBLIC_KEY'),
+				privateKey: config.getOrThrow<string>('LIQPAY_PRIVATE_KEY'),
+				resultUrl: config.get<string>('LIQPAY_RESULT_URL'),
+				serverUrl: config.get<string>('LIQPAY_SERVER_URL'),
+				isGlobal: true,
+			}),
+		}),
+	],
+})
+export class AppModule {}
 ```
 
-This project was created using `bun init` in bun v1.3.10. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Inject and use `LiqpayService`
+
+```ts
+import { Controller, Get, Query } from '@nestjs/common'
+import { CheckoutRequest, LiqpayService } from 'liqpay-nestjs'
+
+@Controller('payments')
+export class PaymentsController {
+	constructor(private readonly liqpay: LiqpayService) {}
+
+	@Get('checkout-url')
+	getCheckoutUrl(@Query('orderId') orderId: string) {
+		const payload: CheckoutRequest = {
+			action: 'pay',
+			amount: 199,
+			currency: 'UAH',
+			description: 'Order payment',
+			orderId,
+		}
+
+		return {
+			url: this.liqpay.payments.getCheckoutUrl(payload),
+		}
+	}
+}
+```
+
+## Typical Flow
+
+1. Register `LiqPayModule` with your public and private keys.
+2. Create a checkout URL or checkout form from a `CheckoutRequest`.
+3. Point `serverUrl` to a Nest endpoint that receives the LiqPay callback envelope.
+4. Parse the callback with `liqpay.webhooks.parseCheckoutCallback(...)`.
+5. Optionally confirm the final state with `liqpay.payments.getPaymentStatus(orderId)`.
+
+## Configuration
+
+Both `LiqPayModule.forRoot(...)` and `LiqPayModule.forRootAsync(...)` resolve to the same options shape.
+
+| Option       | Type      | Required | Description                                                                          |
+| ------------ | --------- | -------- | ------------------------------------------------------------------------------------ |
+| `publicKey`  | `string`  | Yes      | LiqPay public key.                                                                   |
+| `privateKey` | `string`  | Yes      | LiqPay private key used for request signing.                                         |
+| `resultUrl`  | `string`  | No       | Default redirect URL after checkout. Can be overridden per request.                  |
+| `serverUrl`  | `string`  | No       | Default callback URL for LiqPay server notifications. Can be overridden per request. |
+| `isGlobal`   | `boolean` | No       | Registers the Nest module as global when set to `true`. Defaults to `false`.         |
+
+The async registration path validates the resolved options at runtime and throws if `publicKey` or `privateKey` are missing or not strings.
+
+## LiqpayService API
+
+`LiqpayService` exposes two sub-services:
+
+- `payments`
+- `webhooks`
+
+### `payments.getCheckoutUrl(payload)`
+
+Builds a signed LiqPay checkout URL.
+
+```ts
+const url = liqpay.payments.getCheckoutUrl({
+	action: 'pay',
+	amount: 100,
+	currency: 'UAH',
+	description: 'Order #123',
+	orderId: 'order-123',
+})
+```
+
+Notes:
+
+- This is a pure helper and does not perform an HTTP request.
+- The library signs the payload with the configured private key.
+- `version` is always sent as `7`.
+- `resultUrl` and `serverUrl` fall back to module-level defaults if omitted from the payload.
+
+### `payments.getCheckoutForm(payload, buttonText?, buttonColor?)`
+
+Returns an HTML form string with LiqPay's `sdk-button` widget.
+
+```ts
+const html = liqpay.payments.getCheckoutForm(
+	{
+		action: 'pay',
+		amount: 100,
+		currency: 'UAH',
+		description: 'Order #123',
+		orderId: 'order-123',
+	},
+	'Pay now',
+	'#1f9d55',
+)
+```
+
+Defaults:
+
+- `buttonText`: `Pay`
+- `buttonColor`: `#77CC5D`
+
+### `payments.create(payload)`
+
+Returns the normalized checkout payload together with the generated `checkoutUrl`.
+
+```ts
+const checkout = liqpay.payments.create({
+	action: 'pay',
+	amount: 100,
+	currency: 'UAH',
+	description: 'Order #123',
+	orderId: 'order-123',
+})
+
+console.log(checkout.checkoutUrl)
+```
+
+Use this when you want both the prepared payload and the final redirect URL without making a network call.
+
+### `payments.getPaymentStatus(orderId)`
+
+Calls LiqPay's status API and returns `Promise<Result<PaymentStatusResponse>>`.
+
+```ts
+const result = await liqpay.payments.getPaymentStatus('order-123')
+
+if (result.error) {
+	console.error(result.error.code, result.error.description)
+} else {
+	console.log(result.data.status)
+	console.log(result.data.amount)
+	console.log(result.data.orderId)
+}
+```
+
+You only pass `orderId`; the library builds the `status` request internally.
+
+### `webhooks.parseCheckoutCallback(envelope)`
+
+Validates the callback signature, decodes the Base64 payload, and parses it into `Promise<Result<CheckoutCallback>>`.
+
+```ts
+import { Body, Controller, Post } from '@nestjs/common'
+import { LiqPayEnvelope, LiqpayService } from 'liqpay-nestjs'
+
+@Controller('payments')
+export class WebhookController {
+	constructor(private readonly liqpay: LiqpayService) {}
+
+	@Post('webhook')
+	async handleWebhook(@Body() envelope: LiqPayEnvelope) {
+		const result = await this.liqpay.webhooks.parseCheckoutCallback(envelope)
+
+		if (result.error) {
+			return { ok: false, error: result.error }
+		}
+
+		return { ok: true, callback: result.data }
+	}
+}
+```
+
+The expected envelope shape is:
+
+```ts
+type LiqPayEnvelope = {
+	data: string
+	signature: string
+}
+```
+
+## Request and Response Normalization
+
+The library normalizes the most common application-facing models and handles LiqPay's wire format for you.
+
+- Top-level checkout and status request fields use the expected TypeScript property names, for example `orderId`, `resultUrl`, `serverUrl`, and `senderFirstName`.
+- Some nested LiqPay-specific helper objects keep the exact field names defined by their exported schemas. When in doubt, validate against the schema you are using.
+- Outgoing requests are serialized into the format LiqPay expects.
+- Callback and status responses are transformed back to camelCase.
+- Dates, booleans, and several enum-backed fields are normalized where possible.
+- Checkout signing always uses the module's configured public and private keys.
+
+## Minimal Checkout Payload
+
+The smallest useful `CheckoutRequest` usually looks like this:
+
+```ts
+import { CheckoutRequest } from 'liqpay-nestjs'
+
+const payload: CheckoutRequest = {
+	action: 'pay',
+	amount: 100,
+	currency: 'UAH',
+	description: 'Order #123',
+	orderId: 'order-123',
+}
+```
+
+`CheckoutRequest` also supports many LiqPay-specific fields for advanced scenarios, including:
+
+- recurring payments: `subscribe`, `subscribeDateStart`, `subscribePeriodicity`
+- one-click and tokenized flows: `cardToken`, `customer`, `customerUserId`, `recurringbytoken`
+- fiscalization: `rroInfo`, `dae`
+- split payments: `splitRules`
+- customer and sender metadata: `ip`, `senderFirstName`, `senderLastName`, `senderAddress`, and related fields
+
+## Schemas and Types
+
+All public schemas and types are exported from the package root, so you can import them directly from `liqpay-nestjs`.
+
+```ts
+import {
+	CheckoutCallback,
+	CheckoutCallbackSchema,
+	CheckoutRequest,
+	CheckoutRequestSchema,
+	PaymentStatusResponse,
+	PaymentStatusResponseSchema,
+	Result,
+} from 'liqpay-nestjs'
+```
+
+Main export groups:
+
+- base: `LiqPayEnvelope`, `LiqPayEnvelopeSchema`, `Result<T>`, request and response base unions
+- checkout: `CheckoutRequest`, `CheckoutRequestSchema`, `CheckoutCallback`, `CheckoutCallbackSchema`
+- payment status: `PaymentStatusRequest`, `PaymentStatusRequestSchema`, `PaymentStatusResponse`, `PaymentStatusResponseSchema`
+- common: `DetailAddenda`, `FiscalData`, `SplitRule` and their schemas
+- enums: action, currency, language, paytype, payment status, version, and related schema exports
+- error: LiqPay error response and error code schemas and types
+- nest: `LiqPayModule`, `LiqpayService`, `LiqPayOptions`, `LiqPayAsyncOptions`, `LIQPAY_OPTIONS`
+
+### Validating your own DTOs with the exported schemas
+
+```ts
+import { CheckoutRequestSchema, LiqpayService } from 'liqpay-nestjs'
+
+const payload = CheckoutRequestSchema.parse(input)
+const checkout = liqpay.payments.create(payload)
+```
+
+This is useful if you want to validate incoming controller data before passing it to the service.
+
+## Result Contract and Error Handling
+
+Methods that parse LiqPay responses use this result shape:
+
+```ts
+type Result<T> =
+	| { data: T; error?: null }
+	| { data: null; error: { code: string; description: string } }
+```
+
+The library can return:
+
+- LiqPay provider errors parsed from `err_code` and `err_description`
+- internal parsing or transport errors such as `invalid_signature`, `decode_error`, `validation_error`, `invalid_response`, and `http_error`
+
+Always check `result.error` before using `result.data`.
+
+## Advanced Nest Exports
+
+The package root also exports:
+
+- `LIQPAY_OPTIONS`
+- `createLiqpayOptionsProvider(...)`
+- `createLiqpayAsyncOptionsProvider(...)`
+
+These helpers are useful if you want to compose your own providers around the package token instead of using `LiqPayModule` directly.
+
+## Build
+
+```bash
+npm run build
+```

package/dist/core/__devtypes/documented/checkout.callback.d.ts

@@ -1,8 +1,8 @@
-import { LiqPayAction, LiqPayCurrency, LiqPayMpiEci, LiqPayPaymentStatus, LiqPayPaytype } from './types';
+import { Action, Currency, MpiEci, PaymentStatus, Paytype } from './types';
 /**
  * Contract of decoded format of API parameters received in a request from LiqPay after payment
  */
-export interface LiqPayCheckoutCallback {
+export interface CheckoutCallback {
     /**
      * Acquirer ID
      */
@@ -14,7 +14,7 @@ export interface LiqPayCheckoutCallback {
      * - `subscribe` - creation of a regular payment
      * - `regular` - regular payment
      */
-    action: LiqPayAction;
+    action: Action;
     /**
      * Agent commission in payment currency
      */
@@ -66,15 +66,15 @@ export interface LiqPayCheckoutCallback {
     /**
      * Payment currency
      */
-    currency: LiqPayCurrency;
+    currency: Currency;
     /**
      * Transaction currency credit
      */
-    currency_credit: LiqPayCurrency;
+    currency_credit: Currency;
     /**
      * Transaction currency debit
      */
-    currency_debit: LiqPayCurrency;
+    currency_debit: Currency;
     /**
      * A unique user identifier on the merchant's website. Maximum length __100__ characters.
      */
@@ -110,14 +110,14 @@ export interface LiqPayCheckoutCallback {
     /**
      * `Order_id` of payment in the LiqPay system
      */
-    liqpay_order_id: string;
+    _order_id: string;
     /**
      * Code that represents whether 3D-Secure verification was performed during payment. Possible values:
      * - `5` - the transaction was completed with 3DS (the issuer and acquirer support 3D-Secure technology)
      * - `6` - the payer's card issuer does not support 3D-Secure technology
      * - `7` - the transaction was completed without 3D-Secure
      */
-    mpi_eci: LiqPayMpiEci;
+    mpi_eci: MpiEci;
     /**
      * Payment `Order_id`
      */
@@ -134,7 +134,7 @@ export interface LiqPayCheckoutCallback {
      * - invoice - invoice to e-mail
      * - qr - scan qr code
      */
-    paytype: LiqPayPaytype;
+    paytype: Paytype;
     /**
      * Store public key
      */
@@ -202,7 +202,7 @@ export interface LiqPayCheckoutCallback {
     /**
      * Payment status
      */
-    status: LiqPayPaymentStatus;
+    status: PaymentStatus;
     /**
      * An additional payment status indicating that the current payment is reserved for a refund on your store. Possible values: `true` - the payment is reserved for a refund
      */

package/dist/core/__devtypes/documented/checkout.request.d.ts

@@ -1,11 +1,11 @@
-import { LiqPayDetailAddenda } from './detail-addenda';
-import { LiqPayFiscalData } from './fiscal-data';
-import { LiqPaySplitRule } from './split-rule';
-import { LiqPayAction, LiqPayCurrency, LiqPayLanguage, LiqPayPaytype, LiqPaySubscribePeriodicity } from './types';
+import { DetailAddenda } from './detail-addenda';
+import { FiscalData } from './fiscal-data';
+import { SplitRule } from './split-rule';
+import { Action, Currency, Language, Paytype, SubscribePeriodicity } from './types';
 /**
  * Contract of data that is passed when forming a payment request as `base64` encoded string data when calling the LiqPay API
  */
-export interface LiqPayCheckoutRequest {
+export interface CheckoutRequest {
     /**
      * @group shared
      */
@@ -29,7 +29,7 @@ export interface LiqPayCheckoutRequest {
      * - `subscribe` - regular payment
      * - `paydonate` - donation
      */
-    action: LiqPayAction;
+    action: Action;
     /**
      * Payment amount. For example: `5`, `7.34`
      */
@@ -37,7 +37,7 @@ export interface LiqPayCheckoutRequest {
     /**
      * Payment currency. Possible values: `USD`, `EUR`, `UAH`
      */
-    currency: LiqPayCurrency;
+    currency: Currency;
     /**
      * Payment purpose
      */
@@ -59,7 +59,7 @@ export interface LiqPayCheckoutRequest {
     /**
      * Client language: `uk`, `en`
      */
-    language?: LiqPayLanguage;
+    language?: Language;
     /**
      * Parameter that transmits payment methods to be displayed at checkout.
      * If the parameter is not provided, the store settings are applied. Possible values:
@@ -73,7 +73,7 @@ export interface LiqPayCheckoutRequest {
      * - `invoice` - invoice to e-mail
      * - `qr` - scanning a QR code
      */
-    paytypes?: LiqPayPaytype[];
+    paytypes?: Paytype[];
     /**
      * @group checkout flow
      */
@@ -91,7 +91,7 @@ export interface LiqPayCheckoutRequest {
     /**
      * Data for fiscalization
      */
-    rro_info?: LiqPayFiscalData;
+    rro_info?: FiscalData;
     /**
      * @group sender
      */
@@ -137,7 +137,7 @@ export interface LiqPayCheckoutRequest {
      * - `month` - once a month
      * - `year` - once a year, раз
      */
-    subscribe_periodicity?: LiqPaySubscribePeriodicity;
+    subscribe_periodicity?: SubscribePeriodicity;
     /**
      * Payment with splitting the amount into several recipients. This parameter specifies a `JSON` array with payment splitting rules.
      * One debit is made from the client and several credits are made to the recipients. If you need to transfer your purpose for each amount, use the `description` parameter.
@@ -174,7 +174,7 @@ export interface LiqPayCheckoutRequest {
      * ]
      * ```
      */
-    split_rules?: LiqPaySplitRule[];
+    split_rules?: SplitRule[];
     /**
      * @group one-click payment / tokenization
      */
@@ -232,5 +232,5 @@ export interface LiqPayCheckoutRequest {
      * The `dae` parameter is a `JSON` string to which `base64` has been applied.
      * It can contain the parameters given in the example below.
      */
-    dae?: LiqPayDetailAddenda;
+    dae?: DetailAddenda;
 }

package/dist/core/__devtypes/documented/detail-addenda.d.ts

@@ -1,7 +1,7 @@
 /**
  * Contract of data of Long Detail Addenda entry. __Required for merchants with MCC 4511__.
  */
-export interface LiqPayDetailAddenda {
+export interface DetailAddenda {
     /**
      * Airline abbreviation, max 4 characters
      */

package/dist/core/__devtypes/documented/envelope.d.ts

@@ -3,7 +3,7 @@
  *
  * Contains the payload as a stringified and encrypted JSON (`data`) and a cryptographic `signature`.
  */
-export interface LiqPayEnvelope {
+export interface Envelope {
     /**
      * Stringified and encrypted payload
      */

package/dist/core/__devtypes/documented/fiscal-data.d.ts

@@ -1,12 +1,12 @@
-import { LiqPayFiscalTax, LiqPayUnit } from './types';
+import { FiscalTax, Unit } from './types';
 /**
  * Fiscalization data provided by ID contract
  */
-export interface LiqPayFiscalData {
+export interface FiscalData {
     /**
      * Data about the goods for which payment is made
      */
-    items?: LiqPayFiscalProductById[] | LiqPayFiscalProductByApi[];
+    items?: FiscalProductById[] | FiscalProductByApi[];
     /**
      * List of e-mails to which receipts should be sent after fiscalization
      */
@@ -15,7 +15,7 @@ export interface LiqPayFiscalData {
 /**
  * Contract of data about the product for which payment is being made provided by ID
  */
-export interface LiqPayFiscalProductById {
+export interface FiscalProductById {
     /**
      * Quantity/volume
      */
@@ -36,7 +36,7 @@ export interface LiqPayFiscalProductById {
 /**
  * Contract of data about the product for which payment is being made provided by API
  */
-export interface LiqPayFiscalProductByApi {
+export interface FiscalProductByApi {
     /**
      * Quantity/volume
      */
@@ -60,7 +60,7 @@ export interface LiqPayFiscalProductByApi {
     /**
      * Unit of measure code
      */
-    unitcode: LiqPayUnit;
+    unitcode: Unit;
     /**
      * Digital value of the product barcode
      */
@@ -76,5 +76,5 @@ export interface LiqPayFiscalProductByApi {
     /**
      * Tax rate for the product
      */
-    taxs?: LiqPayFiscalTax[];
+    taxs?: FiscalTax[];
 }

package/dist/core/__devtypes/documented/payment-status.request.d.ts

@@ -1,7 +1,7 @@
 /**
  * Contract of data that is passed when forming a request to receive payment status as data in `base64` encoded string form when calling the LiqPay API
  */
-export interface LiqPayPaymentStatusRequest {
+export interface PaymentStatusRequest {
     /**
      * API version. Current version: `7`
      */

package/dist/core/__devtypes/documented/payment-status.response.d.ts

@@ -1,8 +1,8 @@
-import { LiqPayAction, LiqPayBonusType, LiqPayCurrency, LiqPayLanguage, LiqPayMpiEci, LiqPayPaymentStatus, LiqPayPaytype, LiqPayRequestResult } from './types';
+import { Action, BonusType, Currency, Language, MpiEci, PaymentStatus, Paytype, RequestResult } from './types';
 /**
  * Contract of data that comes in response to a request to get payment status
  */
-export interface LiqPayPaymentStatusResponse {
+export interface PaymentStatusResponse {
     /**
      * Acquirer ID
      */
@@ -17,7 +17,7 @@ export interface LiqPayPaymentStatusResponse {
      * - `auth` - card pre-authorization
      * - `regular` - regular payment
      */
-    action: LiqPayAction;
+    action: Action;
     /**
      * Agent commission in payment currency
      */
@@ -53,7 +53,7 @@ export interface LiqPayPaymentStatusResponse {
     /**
      * Bonus type, possible values: `bonusplus`, `discount_club`, `personal`, `promo`
      */
-    bonus_type: LiqPayBonusType;
+    bonus_type: BonusType;
     /**
      * Sender card token
      */
@@ -77,15 +77,15 @@ export interface LiqPayPaymentStatusResponse {
     /**
      * Payment currency
      */
-    currency: LiqPayCurrency;
+    currency: Currency;
     /**
      * Transaction currency credit
      */
-    currency_credit: LiqPayCurrency;
+    currency_credit: Currency;
     /**
      * Transaction currency debit
      */
-    currency_debit: LiqPayCurrency;
+    currency_debit: Currency;
     /**
      * Payment comment
      */
@@ -109,11 +109,11 @@ export interface LiqPayPaymentStatusResponse {
     /**
      * Client language: `uk`, `en`
      */
-    language: LiqPayLanguage;
+    language: Language;
     /**
      * `Order_id` of payment in the LiqPay system
      */
-    liqpay_order_id: string;
+    _order_id: string;
     /**
      * Payment in installments sign
      */
@@ -124,7 +124,7 @@ export interface LiqPayPaymentStatusResponse {
      * - `6` - the payer's card issuer does not support 3D-Secure technology
      * - `7` - the transaction was completed without 3D-Secure
      */
-    mpi_eci: LiqPayMpiEci;
+    mpi_eci: MpiEci;
     /**
      * Payment `Order_id`
      */
@@ -141,7 +141,7 @@ export interface LiqPayPaymentStatusResponse {
      * - `invoice` - invoice to e-mail
      * - `qr` - scan qr code
      */
-    paytype: LiqPayPaytype;
+    paytype: Paytype;
     /**
      * Store public key
      */
@@ -153,7 +153,7 @@ export interface LiqPayPaymentStatusResponse {
     /**
      * Result of query execution: `ok`, `error`
      */
-    result: LiqPayRequestResult;
+    result: RequestResult;
     /**
      * Unique transaction number in the authorization and settlement system of the servicing bank `Retrieval Reference number`
      */
@@ -205,7 +205,7 @@ export interface LiqPayPaymentStatusResponse {
     /**
      * Payment status
      */
-    status: LiqPayPaymentStatus;
+    status: PaymentStatus;
     /**
      * An additional payment status indicating that the current payment is reserved for a refund on your store. Possible values: `true` - the payment is reserved for a refund
      */