@mnpay/bonum 1.5.0

package/@types/types/invoice.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { PaymentProviderSchema, PaymentProviderItemSchema, InvoiceItemSchema, ExtraInputTypeSchema, InvoiceExtraSchema, CreateInvoiceRequestSchema, CreateInvoiceResponseSchema } from '../schemas/invoice.js';
+export type PaymentProvider = z.infer<typeof PaymentProviderSchema>;
+export type PaymentProviderItem = z.infer<typeof PaymentProviderItemSchema>;
+export type InvoiceItem = z.infer<typeof InvoiceItemSchema>;
+export type ExtraInputType = z.infer<typeof ExtraInputTypeSchema>;
+export type InvoiceExtra = z.infer<typeof InvoiceExtraSchema>;
+export type CreateInvoiceRequest = z.infer<typeof CreateInvoiceRequestSchema>;
+export type CreateInvoiceResponse = z.infer<typeof CreateInvoiceResponseSchema>;

package/@types/types/neo.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+import { SendChatMessageRequestSchema } from '../schemas/neo.js';
+export type SendChatMessageRequest = z.infer<typeof SendChatMessageRequestSchema>;

package/@types/types/qr.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import { CreateQrCodeRequestSchema, QrDeepLinkSchema, CreateQrCodeResponseSchema, PayByCardTokenQrRequestSchema } from '../schemas/qr.js';
+export type CreateQrCodeRequest = z.infer<typeof CreateQrCodeRequestSchema>;
+export type QrDeepLink = z.infer<typeof QrDeepLinkSchema>;
+export type CreateQrCodeResponse = z.infer<typeof CreateQrCodeResponseSchema>;
+export type PayByCardTokenQrRequest = z.infer<typeof PayByCardTokenQrRequestSchema>;

package/@types/types/subscription.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import { RecurringTypeSchema, PaymentPlanSchema, SubscribeRequestSchema, SubscriptionDataSchema, ChangeSubscriptionTokenRequestSchema, ListPaymentPlansResponseSchema } from '../schemas/subscription.js';
+export type RecurringType = z.infer<typeof RecurringTypeSchema>;
+export type PaymentPlan = z.infer<typeof PaymentPlanSchema>;
+export type SubscribeRequest = z.infer<typeof SubscribeRequestSchema>;
+export type SubscriptionData = z.infer<typeof SubscriptionDataSchema>;
+export type ChangeSubscriptionTokenRequest = z.infer<typeof ChangeSubscriptionTokenRequestSchema>;
+export type ListPaymentPlansResponse = z.infer<typeof ListPaymentPlansResponseSchema>;

package/@types/types/webhook.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { WebhookTypeSchema, WebhookStatusSchema, WebhookMessageSchema, PaymentWebhookBodySchema, SubscriptionPaymentWebhookBodySchema, CardTokenWebhookBodySchema, WebhookBankInfoSchema, bonumWebhookSchema } from '../schemas/webhook.js';
+export type WebhookType = z.infer<typeof WebhookTypeSchema>;
+export type WebhookStatus = z.infer<typeof WebhookStatusSchema>;
+export type WebhookMessage<T = unknown> = Omit<z.infer<typeof WebhookMessageSchema>, 'body'> & {
+    body: T;
+};
+export type PaymentWebhookBody = z.infer<typeof PaymentWebhookBodySchema>;
+export type SubscriptionPaymentWebhookBody = z.infer<typeof SubscriptionPaymentWebhookBodySchema>;
+export type CardTokenWebhookBody = z.infer<typeof CardTokenWebhookBodySchema>;
+export type WebhookBankInfo = z.infer<typeof WebhookBankInfoSchema>;
+/** Fully parsed Bonum webhook, discriminated on `type` (PDF §3.3, §4.1, §5.3). */
+export type BonumWebhook = z.infer<typeof bonumWebhookSchema>;

package/@types/utils/headers.d.ts

@@ -0,0 +1,9 @@
+import { type Store } from '../definitions/index.js';
+export declare const langHeader: (store: Store, language?: Store["language"]) => {
+    'Accept-Language': "mn" | "en";
+} | {
+    'Accept-Language'?: never;
+};
+export declare const cardTokenHeader: (cardToken: string) => {
+    'X-CARD-TOKEN': string;
+};

package/@types/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './webhook.js';
+export * from './headers.js';

package/@types/utils/webhook.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates the Bonum webhook payload using HMAC-SHA256.
+ * The raw body must be the EXACT compact JSON string you received, without any modification or formatting.
+ * Uses a constant-time comparison so the check does not leak signature bytes through response timing.
+ *
+ * @param rawBody The unparsed raw JSON string of the webhook payload.
+ * @param checksumKey The MERCHANT_CHECKSUM_KEY from Bonum.
+ * @param headerChecksum The `x-checksum-v2` header value precisely.
+ * @returns boolean true if valid
+ */
+export declare const validateWebhookChecksum: (rawBody: string, checksumKey: string, headerChecksum: string) => boolean;

package/@types/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Record<string, any>;
+export default _default;

package/@types/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: Record<string, any>;
+export default _default;

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## [1.5.0](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.4.1...bonum-v1.5.0) (2026-09-09)
+
+
+### Features
+
+* **release:** publish five packages to public npm, fix always-failing release job ([#72](https://github.com/mnpay/mn-payment-platforms/issues/72)) ([f352143](https://github.com/mnpay/mn-payment-platforms/commit/f352143fe60e49fc263f6d33a3fe91a55acfcca1))
+
+## [1.4.1](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.4.0...bonum-v1.4.1) (2026-07-09)
+
+
+### Bug Fixes
+
+* **bonum:** SDK-owned webhook checksum verification (verifyWebhookChecksum) ([#65](https://github.com/mnpay/mn-payment-platforms/issues/65)) ([007a827](https://github.com/mnpay/mn-payment-platforms/commit/007a8274adce2abc9a39d6256e6ca97a1cbc197b))
+
+## [1.4.0](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.3.0...bonum-v1.4.0) (2026-07-06)
+
+
+### Features
+
+* Bonum subscriptions, card tokenization & cancel/refund (SDK audit + payment-gateway) ([#63](https://github.com/mnpay/mn-payment-platforms/issues/63)) ([7d64dc4](https://github.com/mnpay/mn-payment-platforms/commit/7d64dc44e616746694a4cb01b6200d6a491be621))
+
+## [1.3.0](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.2.0...bonum-v1.3.0) (2026-06-10)
+
+
+### Features
+
+* per-invoice language (Accept-Language) for Bonum + payment-gateway ([#61](https://github.com/mnpay/mn-payment-platforms/issues/61)) ([f3229ef](https://github.com/mnpay/mn-payment-platforms/commit/f3229eff961a523068be25ea5c37ccf24e057bdb))
+
+## [1.2.0](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.1.2...bonum-v1.2.0) (2026-04-04)
+
+
+### Features
+
+* add @mnpay/provider package ([#53](https://github.com/mnpay/mn-payment-platforms/issues/53)) ([2478258](https://github.com/mnpay/mn-payment-platforms/commit/247825871c141b1c9dba2a624798da7949f56a0b))
+
+## [1.1.2](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.1.1...bonum-v1.1.2) (2026-04-02)
+
+
+### Bug Fixes
+
+* bug ([6923bcd](https://github.com/mnpay/mn-payment-platforms/commit/6923bcd3491948faa79c294659edcef67582d960))
+
+## [1.1.1](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.1.0...bonum-v1.1.1) (2026-03-29)
+
+
+### Bug Fixes
+
+* bonum ([97015d5](https://github.com/mnpay/mn-payment-platforms/commit/97015d52d29550564f64fb16b50fb25b94ffd553))
+
+## [1.1.0](https://github.com/mnpay/mn-payment-platforms/compare/bonum-v1.0.0...bonum-v1.1.0) (2026-03-26)
+
+
+### Features
+
+* add bonum package ([#46](https://github.com/mnpay/mn-payment-platforms/issues/46)) ([bcfb62c](https://github.com/mnpay/mn-payment-platforms/commit/bcfb62cd4392e432f8b239d22142b96f4b3beb1c))

package/README.md

@@ -0,0 +1,486 @@
+# @mnpay/bonum
+
+Client library for the **Bonum** payment gateway. Supports invoices, QR-code payments, card tokenization, recurring subscriptions, and NEO digital wallet messaging.
+
+- Production API: `https://apis.bonum.mn`
+- Test API: `https://testapi.bonum.mn`
+
+## Installation
+
+```bash
+npm install @mnpay/bonum
+```
+
+```bash
+yarn add @mnpay/bonum
+```
+
+## Usage
+
+```typescript
+import { useBonum } from '@mnpay/bonum'
+
+const bonum = useBonum({
+  appSecret: 'your-app-secret',
+  terminalId: 'your-terminal-id',
+  isTestEnv: false, // set true to use test environment
+})
+```
+
+### Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appSecret` | `string` | Yes | Application secret key |
+| `terminalId` | `string` | Yes | Terminal identifier |
+| `baseUrl` | `string` | No | Override API base URL |
+| `checksumKey` | `string` | No | MERCHANT_CHECKSUM_KEY issued out-of-band by Bonum (distinct from `appSecret`). Required to call `verifyWebhookChecksum` — it throws when unset. |
+| `language` | `'mn' \| 'en'` | No | Default response language (`Accept-Language` header). When unset, no language header is sent. Override per request via `createInvoice({ language })`. |
+| `isTestEnv` | `boolean` | No | Use test environment URL |
+
+Access tokens are managed automatically — the client fetches and refreshes tokens via an interceptor before each request.
+
+---
+
+## Authentication
+
+### `getToken()`
+
+Fetches a new access token using `appSecret` and `terminalId`. Called automatically by the interceptor; you rarely need to call this manually.
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tokenType` | `'Bearer'` | Token type |
+| `accessToken` | `string` | Access token |
+| `expiresIn` | `number` | Token lifetime in seconds |
+| `refreshToken` | `string` | Refresh token |
+| `refreshExpiresIn` | `number` | Refresh token lifetime in seconds |
+| `unit` | `'SECONDS'` | Unit for expiry values |
+
+### `refreshToken()`
+
+Refreshes the access token using the stored refresh token. Called automatically when the access token expires.
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `accessToken` | `string` | New access token |
+
+---
+
+## Payment Providers
+
+### `getPaymentProviders()`
+
+Returns the list of payment providers and their enabled status.
+
+**Response:** `PaymentProviderItem[]`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `provider` | `'QPAY' \| 'E_COMMERCE' \| 'WE_CHAT' \| 'SONO_SHOP'` | Provider identifier |
+| `enabled` | `boolean` | Whether the provider is currently active |
+
+---
+
+## Invoices
+
+### `createInvoice(data)`
+
+Creates a payment invoice and returns a `followUpLink` to redirect the customer to.
+
+**Request:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `amount` | `number` | Yes | Invoice amount |
+| `callback` | `string` | Yes | Webhook URL called when payment status changes |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+| `expiresIn` | `number` | Yes | Invoice expiry duration in seconds |
+| `providers` | `PaymentProvider[]` | No | Limit to specific payment providers |
+| `items` | `InvoiceItem[]` | No | Line items to display on the invoice |
+| `extras` | `InvoiceExtra[]` | No | Extra input fields shown to the customer |
+| `language` | `'mn' \| 'en'` | No | Per-invoice display language, sent as the `Accept-Language` header. Falls back to the client-level `language`; when neither is set, no language header is sent. |
+
+**`InvoiceItem`:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | `string` | Yes | Item name |
+| `amount` | `number` | Yes | Item price |
+| `count` | `number` | Yes | Quantity |
+| `image` | `string` | No | Item image URL |
+| `remark` | `string` | No | Additional note |
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `invoiceId` | `string` | Created invoice ID |
+| `followUpLink` | `string` | URL to redirect the customer to for payment |
+
+**Example:**
+
+```typescript
+const { data } = await bonum.createInvoice({
+  amount: 19900,
+  callback: 'https://yoursite.com/webhook/bonum',
+  transactionId: 'TXN-001',
+  expiresIn: 300,
+})
+
+// Redirect customer to:
+console.log(data.followUpLink)
+```
+
+### `getInvoiceStatus({ invoiceId })`
+
+> ⚠️ **Test environment only — do NOT use in production.** Bonum only exposes invoice
+> status polling in the test environment. In production, track payment outcomes via the
+> `PAYMENT` webhook (see [Webhooks](#webhooks)) rather than polling this endpoint.
+
+Returns the current status of an invoice.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `invoiceId` | `string` | Yes | Invoice ID from `createInvoice` |
+
+### `setInvoicePaid({ invoiceId })`
+
+Marks an invoice as paid. Typically called from a webhook handler after confirming payment.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `invoiceId` | `string` | Yes | Invoice ID to mark as paid |
+
+---
+
+## QR Code Payments
+
+### `createQrCode(data)`
+
+Creates a QR code for payment. The customer scans the QR with a supported banking app.
+
+**Request:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `amount` | `number` | Yes | Payment amount |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+| `expiresIn` | `number` | Yes | QR code expiry in seconds |
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `invoiceId` | `string` | Invoice ID for this QR payment |
+| `qrCode` | `string` | Raw QR code string |
+| `qrImage` | `string` | Base64-encoded QR code image |
+| `links` | `QrDeepLink[]` | Deep links for supported banking apps |
+
+**`QrDeepLink`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Bank/app name |
+| `description` | `string` | Description |
+| `logo` | `string` | Logo URL |
+| `link` | `string` | Deep link URL |
+| `appStoreId` | `string` | iOS App Store ID |
+| `androidPackageName` | `string` | Android package name |
+
+### `invoiceByQrCode({ qrCode })`
+
+Creates an invoice using data from a scanned QR code.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `qrCode` | `string` | Yes | Raw QR code string scanned by the customer |
+
+### `payByCardTokenQr({ qrCode, transactionId, cardToken })`
+
+Pays a QR code invoice using a stored card token.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `qrCode` | `string` | Yes | QR code to pay |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+| `cardToken` | `string` | Yes | Card token from `createCardToken` |
+
+---
+
+## Card Tokenization
+
+### `createCardToken(data)`
+
+Initiates card tokenization. Returns a `followUpLink` to redirect the customer to for card entry.
+
+**Request:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `callback` | `string` | Yes | Webhook URL called after tokenization completes |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+| `payment` | `{ amount: number }` | No | Charge the card immediately on tokenization |
+| `subscription` | `CardTokenSubscription` | No | Attach the token to a subscription plan |
+| `items` | `InvoiceItem[]` | No | Line items to display |
+
+**`CardTokenSubscription`:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `planId` | `number` | Yes | Subscription plan ID |
+| `cycleValue` | `string` | Yes | Billing cycle value (e.g. day of month) |
+| `cycles` | `number \| null` | No | Total billing cycles (`null` = unlimited) |
+| `payNow` | `boolean` | No | Charge on tokenization |
+| `custEmail` | `string` | No | Customer email for receipts |
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `followUpLink` | `string` | URL to redirect the customer to for card entry |
+| `id` | `string` | Token request ID |
+
+### `purchaseWithCardToken({ cardToken, amount, currency, transactionId })`
+
+Makes a purchase using a stored card token.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cardToken` | `string` | Yes | Stored card token |
+| `amount` | `number` | Yes | Charge amount |
+| `currency` | `string` | Yes | Currency code |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Transaction ID |
+| `status` | `'SUCCESS' \| 'FAILED' \| 'QUEUED'` | Transaction status |
+| `completedAt` | `string` | Completion timestamp |
+| `description` | `string` | Result description |
+| `cardStatus` | `'ACTIVE' \| 'INACTIVE' \| null` | Card status |
+| `respCode` | `string \| null` | Response code |
+
+### `rollbackPurchase({ id, cardToken })`
+
+Refunds an already-completed card-token purchase in full (PDF §4.3:
+`GET /mpay-service/merchant/transaction/rollback/{id}`). The refund always applies
+to the full amount of the original purchase identified by `id`, so no `amount` is sent.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | `string` | Yes | Transaction ID of the original purchase to roll back |
+| `cardToken` | `string` | Yes | Card token used in the original purchase (sent as `X-CARD-TOKEN`) |
+
+---
+
+## Subscriptions
+
+### `listPaymentPlans()`
+
+Returns all available subscription plans.
+
+**Response:** `PaymentPlan[]`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `planId` | `number` | Plan ID |
+| `name` | `string` | Plan name |
+| `remark` | `string` | Plan description |
+| `recurringType` | `'WEEKLY' \| 'MONTHLY' \| 'YEARLY'` | Billing frequency |
+| `amount` | `number` | Recurring charge amount |
+| `status` | `'ACTIVE' \| 'INACTIVE'` | Plan availability |
+| `cardCount` | `number` | Number of cards enrolled |
+| `retryCount` | `number` | Payment retry count on failure |
+| `createdAt` | `string` | Plan creation timestamp |
+
+### `subscribe({ cardToken, planId, cycleValue, cycles?, payNow?, custEmail? })`
+
+Subscribes a card to a payment plan.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cardToken` | `string` | Yes | Card token to subscribe |
+| `planId` | `number` | Yes | Subscription plan ID |
+| `cycleValue` | `number \| string` | Yes | Billing cycle value |
+| `cycles` | `number \| null` | No | Total cycles (`null` = unlimited) |
+| `payNow` | `boolean` | No | Charge immediately on subscription |
+| `custEmail` | `string` | No | Customer email for receipts |
+
+**Response:** `SubscriptionData` (see below)
+
+### `getSubscriptions({ cardToken })`
+
+Returns all subscriptions associated with a card token.
+
+**Response:** `SubscriptionData[]`
+
+**`SubscriptionData`:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `subscriptionId` | `number` | Subscription ID |
+| `subscribedAt` | `string` | Subscription creation timestamp |
+| `cardMask` | `string` | Masked card number |
+| `plan` | `PaymentPlan` | The associated plan |
+| `nextBillAt` | `string` | Next billing date |
+| `lastBilledAt` | `string` | Last billing date |
+| `status` | `'ACTIVE' \| 'INACTIVE' \| 'CANCELLED'` | Subscription status |
+
+### `unsubscribe({ subscriptionId, planId? })`
+
+Cancels a subscription.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `subscriptionId` | `string` | Yes | Subscription ID to cancel |
+| `planId` | `string` | No | Plan ID (if required by the plan) |
+
+### `deleteSubscription({ subscriptionId, planId? })`
+
+Permanently deletes a subscription record.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `subscriptionId` | `string` | Yes | Subscription ID to delete |
+| `planId` | `string` | No | Plan ID (if required) |
+
+### `changeSubscriptionTokenNewCard({ subscriptionId, callback, transactionId, items? })`
+
+Updates a subscription with a new card — initiates a new tokenization flow.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `subscriptionId` | `string` | Yes | Subscription to update |
+| `callback` | `string` | Yes | Webhook URL after new card is tokenized |
+| `transactionId` | `string` | Yes | Unique merchant-side transaction ID |
+| `items` | `InvoiceItem[]` | No | Line items to display |
+
+**Response:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `followUpLink` | `string` | URL to redirect customer to for new card entry |
+
+### `changeSubscriptionTokenExisting({ subscriptionId, newCardToken })`
+
+Updates a subscription with an already-tokenized card.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `subscriptionId` | `string` | Yes | Subscription to update |
+| `newCardToken` | `string` | Yes | Existing card token to use |
+
+> **Note:** `executeSubscriptionPayment` is `@internal` and intentionally undocumented.
+> Subscription charges are automatic — Bonum fires the `SUBSCRIPTION-PAYMENT` webhook on
+> each recurring charge. Do not call it directly; rely on the webhook instead.
+
+---
+
+## NEO (Digital Wallet)
+
+The NEO methods communicate with a separate NEO / M-Chat base URL, passed per-request.
+
+### `getNeoUserData({ requestId, mChatBaseUrl })`
+
+Retrieves NEO user account data for a given share request.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `requestId` | `string` | Yes | Share request ID |
+| `mChatBaseUrl` | `string` | Yes | M-Chat service base URL |
+
+### `sendNeoMessage({ phoneNumber, message, neoBaseUrl })`
+
+Sends a message to a user through the NEO messaging service.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `phoneNumber` | `string` | Yes | Recipient phone number |
+| `message` | `string` | Yes | Message content |
+| `neoBaseUrl` | `string` | Yes | NEO service base URL |
+
+---
+
+## Webhook Verification
+
+### `verifyWebhookChecksum(rawBody, headerChecksum)`
+
+Verifies the `x-checksum-v2` webhook signature using the configured `checksumKey`.
+Synchronous — no API call. **Throws** when `checksumKey` is not configured.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rawBody` | `string` | Yes | Exact raw request body as received on the wire |
+| `headerChecksum` | `string` | Yes | The `x-checksum-v2` header value |
+
+---
+
+## Webhooks
+
+Bonum delivers status updates as signed webhooks. In production this is the **authoritative**
+way to learn the outcome of a payment, card tokenization, or recurring charge — prefer it over
+polling `getInvoiceStatus` (which is test-environment only).
+
+### Verifying the signature
+
+Each webhook carries an `x-checksum-v2` header (HmacSHA256 over the raw request body). When the
+client is configured with `checksumKey` (the MERCHANT_CHECKSUM_KEY Bonum issues out-of-band —
+**not** your `appSecret`), verify with the SDK method:
+
+```ts
+const bonum = useBonum({ terminalId, appSecret, checksumKey })
+
+const ok = bonum.verifyWebhookChecksum(rawBody, req.headers['x-checksum-v2'])
+if (!ok) throw new Error('Invalid Bonum webhook checksum')
+```
+
+`verifyWebhookChecksum` **throws** when `checksumKey` is not configured, so a misconfiguration
+never masquerades as an invalid signature.
+
+The underlying pure function is also exported if you manage the key yourself:
+
+```ts
+import { validateWebhookChecksum } from '@mnpay/bonum'
+
+const ok = validateWebhookChecksum(rawBody, checksumKey, req.headers['x-checksum-v2'])
+```
+
+> **Important:** `rawBody` must be the exact bytes received on the wire — capture it *before* any
+> JSON parsing (`readRawBody` in h3/Nitro, `express.raw`, `req.text()` in Next.js). Re-serializing
+> a parsed body changes key order/escaping and the HMAC will never match.
+
+### Parsing the payload
+
+`bonumWebhookSchema` is a Zod discriminated union (discriminated on `type`) covering all three
+documented webhook kinds, each in a `SUCCESS` / `FAILED` variant. The parsed type is exported as
+`BonumWebhook`.
+
+| `type` | When it fires | Body |
+|--------|---------------|------|
+| `PAYMENT` | A regular invoice was paid / failed (PDF §3.3) | Transaction detail (`invoiceId`, `amount`, `currency`, `transactionId`, `terminalId`, …) |
+| `CARD-TOKEN` | A card tokenization completed / failed (PDF §4.1) | Token + bank info |
+| `SUBSCRIPTION-PAYMENT` | An automatic recurring charge ran (PDF §5.3) | `subscriptionId`, `invoiceId`, `planId`, `transactionId`, `amount`, `currency`, `completedAt` |
+
+```ts
+import { bonumWebhookSchema } from '@mnpay/bonum'
+
+const event = bonumWebhookSchema.parse(req.body)
+switch (event.type) {
+  case 'PAYMENT':
+    // reconcile invoice payment
+    break
+  case 'CARD-TOKEN':
+    // store the card token from the tokenization result
+    break
+  case 'SUBSCRIPTION-PAYMENT':
+    // record the recurring charge
+    break
+}
+```