@delopay/sdk 0.62.0 → 0.63.0

package/README.md

@@ -1,430 +1,430 @@
-# @delopay/sdk
-
-TypeScript SDK for the [Delopay](https://delopay.net) payments API. Zero dependencies, works in Node 18+ and browsers.
-
-## Installation
-
-```bash
-pnpm add @delopay/sdk
-```
-
-```bash
-npm install @delopay/sdk
-```
-
-```bash
-yarn add @delopay/sdk
-```
-
-## Quick Start
-
-```typescript
-import { Delopay } from '@delopay/sdk';
-
-const delopay = new Delopay(process.env.DELOPAY_API_KEY!);
-
-const payment = await delopay.payments.create({
-  amount: 1000, // in minor units (€10.00)
-  currency: 'EUR',
-  description: 'Order #1234',
-  customer_id: 'cus_abc123',
-});
-
-console.log(payment.payment_id, payment.status);
-```
-
-## Configuration
-
-```typescript
-const delopay = new Delopay(apiKey, {
-  sandbox: true, // Use https://sandbox.delopay.net (default: false → production)
-  baseUrl: 'https://…', // Override base URL entirely
-  timeout: 30_000, // Request timeout in ms (default: 30 000)
-});
-```
-
-**API keys:**
-
-- `prd_…` / `snd_…` — server-side secret key. Full API access. Keep this private.
-- `pk_prd_…` / `pk_snd_…` — client-side publishable key. Restricted to browser-safe operations.
-
-## Usage Examples
-
-### Create a payment
-
-> **Never send raw card numbers through the SDK.** Delopay's API is not a
-> raw-PAN endpoint: cards are collected on the Delopay **hosted checkout**
-> (or via a payment link), so card data never touches your server and stays
-> out of your PCI scope. Server-side you create the payment and hand the buyer
-> off; you confirm server-side only with a saved `payment_token`, a
-> `mandate_id`, or a redirect method (e.g. a PayPal wallet) — never card data.
-
-```typescript
-// Recommended: hosted checkout via a payment link.
-const payment = await delopay.payments.create({
-  amount: 2500,
-  currency: 'EUR',
-  payment_link: true,
-  customer_id: 'cus_abc123',
-  description: 'Order #1234',
-  return_url: 'https://example.com/checkout/complete',
-});
-
-// Send the buyer here — they pick a method and enter card details on the
-// hosted page. Delopay handles 3-D Secure and redirects.
-console.log(payment.payment_link?.link);
-
-// Fulfil on the payment_succeeded webhook, or re-check server-side:
-const final = await delopay.payments.retrieve(payment.payment_id);
-```
-
-Confirm server-side **without card data** — with a saved token (off-session):
-
-```typescript
-const confirmed = await delopay.payments.confirm(pending.payment_id, {
-  payment_token: savedPaymentToken, // from paymentMethods.listForCustomer()
-  off_session: true,
-  return_url: 'https://example.com/checkout/complete',
-});
-
-console.log(confirmed.status); // 'succeeded' | 'requires_customer_action' | …
-```
-
-Or with a redirect payment method that involves no card data at all:
-
-```typescript
-const paypal = await delopay.payments.create({
-  amount: 2500,
-  currency: 'EUR',
-  confirm: true,
-  payment_method: 'wallet',
-  payment_method_type: 'paypal',
-  payment_method_data: { wallet: { paypal_redirect: {} } },
-  return_url: 'https://example.com/checkout/complete',
-});
-// paypal.next_action?.redirect_to_url → send the buyer there to approve
-```
-
-### Create a refund
-
-```typescript
-const refund = await delopay.refunds.create({
-  payment_id: 'pay_abc123',
-  amount: 1000, // partial refund; omit for full refund
-  reason: 'Customer request',
-});
-
-console.log(refund.refund_id, refund.status);
-```
-
-### Manage customers
-
-```typescript
-const customer = await delopay.customers.create({
-  name: 'Jane Doe',
-  email: 'jane@example.com',
-  metadata: { plan: 'pro' },
-});
-
-// List saved payment methods
-const { customer_payment_methods } = await delopay.paymentMethods.listForCustomer(
-  customer.customer_id,
-);
-
-// Use a saved method on a new payment
-const payment = await delopay.payments.create({
-  amount: 1000,
-  currency: 'EUR',
-  customer_id: customer.customer_id,
-  payment_token: customer_payment_methods[0]?.payment_token,
-  confirm: true,
-});
-```
-
-### Handle disputes
-
-```typescript
-// Disputes for one payment come from the payment object:
-const payment = await delopay.payments.retrieve('pay_abc123');
-
-for (const dispute of payment.disputes ?? []) {
-  console.log(dispute.dispute_id, dispute.dispute_stage, dispute.dispute_status);
-}
-
-// Or list disputes across the account, filtered by status:
-const open = await delopay.disputes.list({ dispute_status: 'dispute_opened' });
-```
-
-### Inspect why a payment failed
-
-```typescript
-// Every attempt on a payment — including retries across connectors — with its
-// full failure detail (raw code + Delopay-unified, human-readable reason).
-const { size, data } = await delopay.payments.listAttempts('pay_abc123');
-
-for (const attempt of data) {
-  // e.g. "stripe failure — Insufficient funds (51)"
-  console.log(
-    `${attempt.connector ?? 'unknown'} ${attempt.status} — ` +
-      `${attempt.unified_message ?? attempt.error_message ?? 'no error'}` +
-      `${attempt.error_code ? ` (${attempt.error_code})` : ''}`,
-  );
-}
-```
-
-### Manage shops and gateways
-
-```typescript
-// Create a shop (business profile)
-const shop = await delopay.shops.create(merchantId, {
-  shop_name: 'My Online Store',
-  webhook_url: 'https://example.com/webhooks/delopay',
-  return_url: 'https://example.com/checkout/complete',
-});
-
-// Connect Stripe as a payment gateway
-const gateway = await delopay.shops.gateways.connect(merchantId, shop.shop_id, {
-  connector_type: 'payment_processor',
-  connector_name: 'stripe',
-  connector_account_details: {
-    auth_type: 'HeaderKey',
-    api_key: process.env.STRIPE_SECRET_KEY,
-  },
-  test_mode: true,
-});
-
-// List connected gateways
-const gateways = await delopay.shops.gateways.list(merchantId, shop.shop_id);
-```
-
-### Subscriptions
-
-Recurring billing runs through a billing processor connected to the shop (Stripe
-Billing or PayPal). Every subscription call is **profile-scoped** — pass the
-shop's `X-Profile-Id` so the backend can resolve the billing processor (you get
-`IR_04` otherwise):
-
-```typescript
-const opts = { headers: { 'X-Profile-Id': profileId } };
-```
-
-**Browse plans and estimate cost** before creating anything:
-
-```typescript
-// List purchasable plans (or addons) with their prices
-const plans = await delopay.subscriptions.getItems({ item_type: 'plan' }, opts);
-const priceId = plans[0]?.price_id[0]?.price_id;
-
-// Preview what the customer will be charged
-const estimate = await delopay.subscriptions.getEstimate({ item_price_id: priceId }, opts);
-console.log(estimate.amount, estimate.currency, estimate.interval); // 1500 'EUR' 'Month'
-```
-
-> **Never send raw card numbers.** The subscription API rejects
-> `payment_method_data.card` with a raw PAN. Cards are collected client-side by
-> the connector's hosted fields (Stripe Elements) so the card never touches your
-> server, keeping raw card data out of your PCI scope. Confirm with a hosted
-> checkout session or a previously-saved token, as shown below.
-
-**Recommended: hosted checkout.** Create the subscription server-side, then send
-the buyer to the Delopay hosted checkout with the returned `client_secret`. The
-buyer enters their card in the connector iframe; you never handle the PAN:
-
-```typescript
-const pending = await delopay.subscriptions.create(
-  {
-    item_price_id: priceId,
-    customer_id: 'cus_abc123',
-    payment_details: { return_url: 'https://example.com/subscription/complete' },
-  },
-  opts,
-);
-
-// Redirect the buyer to the hosted checkout to enter their card.
-const checkoutUrl =
-  `https://checkout.delopay.net/pay/${merchantId}/${pending.id}` +
-  `?cs=${encodeURIComponent(pending.client_secret ?? '')}`;
-// → res.redirect(checkoutUrl)
-
-// Activation arrives via the subscription/invoice webhooks; never trust the
-// client. Reconcile with subscriptions.retrieve(pending.id, opts).
-```
-
-**Saved payment method (off-session).** If the customer already has a saved,
-tokenized payment method, confirm server-side with the token — still no PAN:
-
-```typescript
-const sub = await delopay.subscriptions.createAndConfirm(
-  {
-    item_price_id: priceId,
-    customer_id: 'cus_abc123',
-    payment_details: {
-      payment_method: 'card',
-      payment_method_id: savedPaymentMethodId, // token, not a card number
-      setup_future_usage: 'off_session',
-      return_url: 'https://example.com/subscription/complete',
-    },
-  },
-  opts,
-);
-
-if (sub.redirect_url) {
-  // Some processors (e.g. PayPal) still need buyer approval — redirect there.
-} else {
-  console.log(sub.status); // 'active'
-}
-```
-
-You can also split create and confirm — call `subscriptions.confirm(id, …)` with
-the `client_secret` and a `payment_token` once the buyer has a token. Same rule:
-a `payment_token` / `payment_method_id`, never a raw card.
-
-**Manage the lifecycle.** Pause, resume, and cancel take optional timing and
-proration controls; called with no body they act immediately:
-
-```typescript
-await delopay.subscriptions.pause(sub.id, { pause_option: 'end_of_term' }, opts);
-await delopay.subscriptions.resume(sub.id, undefined, opts);
-await delopay.subscriptions.cancel(
-  sub.id,
-  { cancel_option: 'immediately', credit_option_for_current_term_charges: 'prorate' },
-  opts,
-);
-
-// Retrieve one, or list for the profile
-const current = await delopay.subscriptions.retrieve(sub.id, opts);
-const all = await delopay.subscriptions.list({ limit: 20 }, opts);
-```
-
-Each billing cycle raises an invoice (`sub.invoice`) with its own payment leg
-(`sub.payment`); track cycle outcomes via the subscription/invoice webhooks.
-
-### Platform fee rules
-
-Price the platform fee by payment method, connector, amount, currency or card
-network. Build the rule program with `feeProgram()` — rules are tried in order,
-first match wins, otherwise the default applies:
-
-```typescript
-import { Delopay, feeProgram } from '@delopay/sdk';
-
-const delopay = new Delopay(process.env.DELOPAY_API_KEY ?? '');
-
-const algorithm = feeProgram()
-  .rule({ name: 'crypto', when: { paymentMethod: 'crypto' }, fee: { percentage: 1.0 } })
-  .rule({
-    name: 'card_on_cryptomus',
-    when: { paymentMethod: 'card', connector: 'cryptomus' },
-    fee: { percentage: 2.0 },
-  })
-  .otherwise({ percentage: 3.0 })
-  .build();
-
-await delopay.fees.rules.upsert({ algorithm }, 'merchant_abc123');
-
-const program = await delopay.fees.rules.retrieve('merchant_abc123'); // or null
-await delopay.fees.rules.delete('merchant_abc123'); // revert to flat schedules
-```
-
-Merchants without a rule program keep their existing flat fee schedules / volume
-tier unchanged.
-
-### Webhook verification
-
-Delopay signs each outgoing webhook with HMAC-SHA512 over the raw request body and delivers the hex-encoded digest in the `X-Webhook-Signature-512` header. Use `express.raw()` (not `express.json()`) so the bytes reach the verifier unchanged.
-
-The verified event matches the wire body: `{ merchant_id, event_id, event_type, content: { type, object }, timestamp }`. `event_type` says what happened (e.g. `'payment_succeeded'`); `content.type` tags the payload kind (e.g. `'payment_details'`) — narrow on it to get a typed `content.object` (the payment/refund/dispute, with `payment_id` etc.).
-
-```typescript
-import express from 'express';
-import { Delopay } from '@delopay/sdk';
-
-app.post('/webhooks/delopay', express.raw({ type: 'application/json' }), async (req, res) => {
-  const signature = req.header('x-webhook-signature-512') ?? '';
-  const secret = process.env.DELOPAY_WEBHOOK_SECRET!;
-
-  let event;
-  try {
-    event = await Delopay.webhooks.verify(req.body, signature, secret);
-  } catch {
-    return res.status(400).send('Invalid signature');
-  }
-
-  if (event.content.type === 'payment_details') {
-    const payment = event.content.object; // typed: PaymentResponse
-    switch (event.event_type) {
-      case 'payment_succeeded':
-        // fulfil order — payment.payment_id, payment.amount, payment.currency
-        break;
-      case 'payment_failed':
-        // notify customer — payment.error_message
-        break;
-    }
-  }
-
-  res.json({ received: true });
-});
-```
-
-## Error Handling
-
-All errors are instances of `DelopayError`:
-
-```typescript
-import { Delopay, DelopayError, DelopayAuthenticationError } from '@delopay/sdk';
-
-try {
-  const payment = await delopay.payments.retrieve('pay_does_not_exist');
-} catch (err) {
-  if (err instanceof DelopayAuthenticationError) {
-    // status: 401 — invalid or missing API key
-    console.error('Check your API key');
-  } else if (err instanceof DelopayError) {
-    console.error(err.message); // human-readable message
-    console.error(err.status); // HTTP status code
-    console.error(err.code); // machine-readable error code
-    console.error(err.type); // error category (e.g. 'not_found')
-    console.error(err.data); // structured context for select codes (see below)
-  }
-}
-```
-
-**Error classes:**
-
-| Class                        | When                               |
-| ---------------------------- | ---------------------------------- |
-| `DelopayError`               | Base class for all API errors      |
-| `DelopayAuthenticationError` | `401` — invalid or missing API key |
-
-Network timeouts throw `DelopayError` with `code: 'TIMEOUT'`. Network failures throw with `code: 'NETWORK'`.
-
-**Structured error context (`err.data`):** populated for a small set of codes that benefit from a machine-readable hint. Currently:
-
-| `err.code` | `err.data` shape               | Meaning                                                                    |
-| ---------- | ------------------------------ | -------------------------------------------------------------------------- |
-| `UR_48`    | `{ retry_after_secs: number }` | TOTP attempt counter locked out — wait this many seconds before retrying.  |
-| `UR_63`    | `{ retry_after_secs: number }` | Auth-endpoint rate limit tripped — wait this many seconds before retrying. |
-
-## TypeScript
-
-The SDK is written in strict TypeScript. All request and response shapes are fully typed. Import types directly when needed:
-
-```typescript
-import type { PaymentResponse, PaymentCreateRequest, Currency } from '@delopay/sdk';
-```
-
-## Environments
-
-| Environment | Base URL                      | API key prefix       |
-| ----------- | ----------------------------- | -------------------- |
-| Production  | `https://api.delopay.net`     | `prd_…` / `pk_prd_…` |
-| Sandbox     | `https://sandbox.delopay.net` | `snd_…` / `pk_snd_…` |
-
-```typescript
-// Sandbox
-const delopay = new Delopay(process.env.DELOPAY_API_KEY!, { sandbox: true });
-```
-
-## License
-
-MIT
+# @delopay/sdk
+
+TypeScript SDK for the [Delopay](https://delopay.net) payments API. Zero dependencies, works in Node 18+ and browsers.
+
+## Installation
+
+```bash
+pnpm add @delopay/sdk
+```
+
+```bash
+npm install @delopay/sdk
+```
+
+```bash
+yarn add @delopay/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Delopay } from '@delopay/sdk';
+
+const delopay = new Delopay(process.env.DELOPAY_API_KEY!);
+
+const payment = await delopay.payments.create({
+  amount: 1000, // in minor units (€10.00)
+  currency: 'EUR',
+  description: 'Order #1234',
+  customer_id: 'cus_abc123',
+});
+
+console.log(payment.payment_id, payment.status);
+```
+
+## Configuration
+
+```typescript
+const delopay = new Delopay(apiKey, {
+  sandbox: true, // Use https://sandbox.delopay.net (default: false → production)
+  baseUrl: 'https://…', // Override base URL entirely
+  timeout: 30_000, // Request timeout in ms (default: 30 000)
+});
+```
+
+**API keys:**
+
+- `prd_…` / `snd_…` — server-side secret key. Full API access. Keep this private.
+- `pk_prd_…` / `pk_snd_…` — client-side publishable key. Restricted to browser-safe operations.
+
+## Usage Examples
+
+### Create a payment
+
+> **Never send raw card numbers through the SDK.** Delopay's API is not a
+> raw-PAN endpoint: cards are collected on the Delopay **hosted checkout**
+> (or via a payment link), so card data never touches your server and stays
+> out of your PCI scope. Server-side you create the payment and hand the buyer
+> off; you confirm server-side only with a saved `payment_token`, a
+> `mandate_id`, or a redirect method (e.g. a PayPal wallet) — never card data.
+
+```typescript
+// Recommended: hosted checkout via a payment link.
+const payment = await delopay.payments.create({
+  amount: 2500,
+  currency: 'EUR',
+  payment_link: true,
+  customer_id: 'cus_abc123',
+  description: 'Order #1234',
+  return_url: 'https://example.com/checkout/complete',
+});
+
+// Send the buyer here — they pick a method and enter card details on the
+// hosted page. Delopay handles 3-D Secure and redirects.
+console.log(payment.payment_link?.link);
+
+// Fulfil on the payment_succeeded webhook, or re-check server-side:
+const final = await delopay.payments.retrieve(payment.payment_id);
+```
+
+Confirm server-side **without card data** — with a saved token (off-session):
+
+```typescript
+const confirmed = await delopay.payments.confirm(pending.payment_id, {
+  payment_token: savedPaymentToken, // from paymentMethods.listForCustomer()
+  off_session: true,
+  return_url: 'https://example.com/checkout/complete',
+});
+
+console.log(confirmed.status); // 'succeeded' | 'requires_customer_action' | …
+```
+
+Or with a redirect payment method that involves no card data at all:
+
+```typescript
+const paypal = await delopay.payments.create({
+  amount: 2500,
+  currency: 'EUR',
+  confirm: true,
+  payment_method: 'wallet',
+  payment_method_type: 'paypal',
+  payment_method_data: { wallet: { paypal_redirect: {} } },
+  return_url: 'https://example.com/checkout/complete',
+});
+// paypal.next_action?.redirect_to_url → send the buyer there to approve
+```
+
+### Create a refund
+
+```typescript
+const refund = await delopay.refunds.create({
+  payment_id: 'pay_abc123',
+  amount: 1000, // partial refund; omit for full refund
+  reason: 'Customer request',
+});
+
+console.log(refund.refund_id, refund.status);
+```
+
+### Manage customers
+
+```typescript
+const customer = await delopay.customers.create({
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  metadata: { plan: 'pro' },
+});
+
+// List saved payment methods
+const { customer_payment_methods } = await delopay.paymentMethods.listForCustomer(
+  customer.customer_id,
+);
+
+// Use a saved method on a new payment
+const payment = await delopay.payments.create({
+  amount: 1000,
+  currency: 'EUR',
+  customer_id: customer.customer_id,
+  payment_token: customer_payment_methods[0]?.payment_token,
+  confirm: true,
+});
+```
+
+### Handle disputes
+
+```typescript
+// Disputes for one payment come from the payment object:
+const payment = await delopay.payments.retrieve('pay_abc123');
+
+for (const dispute of payment.disputes ?? []) {
+  console.log(dispute.dispute_id, dispute.dispute_stage, dispute.dispute_status);
+}
+
+// Or list disputes across the account, filtered by status:
+const open = await delopay.disputes.list({ dispute_status: 'dispute_opened' });
+```
+
+### Inspect why a payment failed
+
+```typescript
+// Every attempt on a payment — including retries across connectors — with its
+// full failure detail (raw code + Delopay-unified, human-readable reason).
+const { size, data } = await delopay.payments.listAttempts('pay_abc123');
+
+for (const attempt of data) {
+  // e.g. "stripe failure — Insufficient funds (51)"
+  console.log(
+    `${attempt.connector ?? 'unknown'} ${attempt.status} — ` +
+      `${attempt.unified_message ?? attempt.error_message ?? 'no error'}` +
+      `${attempt.error_code ? ` (${attempt.error_code})` : ''}`,
+  );
+}
+```
+
+### Manage shops and gateways
+
+```typescript
+// Create a shop (business profile)
+const shop = await delopay.shops.create(merchantId, {
+  shop_name: 'My Online Store',
+  webhook_url: 'https://example.com/webhooks/delopay',
+  return_url: 'https://example.com/checkout/complete',
+});
+
+// Connect Stripe as a payment gateway
+const gateway = await delopay.shops.gateways.connect(merchantId, shop.shop_id, {
+  connector_type: 'payment_processor',
+  connector_name: 'stripe',
+  connector_account_details: {
+    auth_type: 'HeaderKey',
+    api_key: process.env.STRIPE_SECRET_KEY,
+  },
+  test_mode: true,
+});
+
+// List connected gateways
+const gateways = await delopay.shops.gateways.list(merchantId, shop.shop_id);
+```
+
+### Subscriptions
+
+Recurring billing runs through a billing processor connected to the shop (Stripe
+Billing or PayPal). Every subscription call is **profile-scoped** — pass the
+shop's `X-Profile-Id` so the backend can resolve the billing processor (you get
+`IR_04` otherwise):
+
+```typescript
+const opts = { headers: { 'X-Profile-Id': profileId } };
+```
+
+**Browse plans and estimate cost** before creating anything:
+
+```typescript
+// List purchasable plans (or addons) with their prices
+const plans = await delopay.subscriptions.getItems({ item_type: 'plan' }, opts);
+const priceId = plans[0]?.price_id[0]?.price_id;
+
+// Preview what the customer will be charged
+const estimate = await delopay.subscriptions.getEstimate({ item_price_id: priceId }, opts);
+console.log(estimate.amount, estimate.currency, estimate.interval); // 1500 'EUR' 'Month'
+```
+
+> **Never send raw card numbers.** The subscription API rejects
+> `payment_method_data.card` with a raw PAN. Cards are collected client-side by
+> the connector's hosted fields (Stripe Elements) so the card never touches your
+> server, keeping raw card data out of your PCI scope. Confirm with a hosted
+> checkout session or a previously-saved token, as shown below.
+
+**Recommended: hosted checkout.** Create the subscription server-side, then send
+the buyer to the Delopay hosted checkout with the returned `client_secret`. The
+buyer enters their card in the connector iframe; you never handle the PAN:
+
+```typescript
+const pending = await delopay.subscriptions.create(
+  {
+    item_price_id: priceId,
+    customer_id: 'cus_abc123',
+    payment_details: { return_url: 'https://example.com/subscription/complete' },
+  },
+  opts,
+);
+
+// Redirect the buyer to the hosted checkout to enter their card.
+const checkoutUrl =
+  `https://checkout.delopay.net/pay/${merchantId}/${pending.id}` +
+  `?cs=${encodeURIComponent(pending.client_secret ?? '')}`;
+// → res.redirect(checkoutUrl)
+
+// Activation arrives via the subscription/invoice webhooks; never trust the
+// client. Reconcile with subscriptions.retrieve(pending.id, opts).
+```
+
+**Saved payment method (off-session).** If the customer already has a saved,
+tokenized payment method, confirm server-side with the token — still no PAN:
+
+```typescript
+const sub = await delopay.subscriptions.createAndConfirm(
+  {
+    item_price_id: priceId,
+    customer_id: 'cus_abc123',
+    payment_details: {
+      payment_method: 'card',
+      payment_method_id: savedPaymentMethodId, // token, not a card number
+      setup_future_usage: 'off_session',
+      return_url: 'https://example.com/subscription/complete',
+    },
+  },
+  opts,
+);
+
+if (sub.redirect_url) {
+  // Some processors (e.g. PayPal) still need buyer approval — redirect there.
+} else {
+  console.log(sub.status); // 'active'
+}
+```
+
+You can also split create and confirm — call `subscriptions.confirm(id, …)` with
+the `client_secret` and a `payment_token` once the buyer has a token. Same rule:
+a `payment_token` / `payment_method_id`, never a raw card.
+
+**Manage the lifecycle.** Pause, resume, and cancel take optional timing and
+proration controls; called with no body they act immediately:
+
+```typescript
+await delopay.subscriptions.pause(sub.id, { pause_option: 'end_of_term' }, opts);
+await delopay.subscriptions.resume(sub.id, undefined, opts);
+await delopay.subscriptions.cancel(
+  sub.id,
+  { cancel_option: 'immediately', credit_option_for_current_term_charges: 'prorate' },
+  opts,
+);
+
+// Retrieve one, or list for the profile
+const current = await delopay.subscriptions.retrieve(sub.id, opts);
+const all = await delopay.subscriptions.list({ limit: 20 }, opts);
+```
+
+Each billing cycle raises an invoice (`sub.invoice`) with its own payment leg
+(`sub.payment`); track cycle outcomes via the subscription/invoice webhooks.
+
+### Platform fee rules
+
+Price the platform fee by payment method, connector, amount, currency or card
+network. Build the rule program with `feeProgram()` — rules are tried in order,
+first match wins, otherwise the default applies:
+
+```typescript
+import { Delopay, feeProgram } from '@delopay/sdk';
+
+const delopay = new Delopay(process.env.DELOPAY_API_KEY ?? '');
+
+const algorithm = feeProgram()
+  .rule({ name: 'crypto', when: { paymentMethod: 'crypto' }, fee: { percentage: 1.0 } })
+  .rule({
+    name: 'card_on_cryptomus',
+    when: { paymentMethod: 'card', connector: 'cryptomus' },
+    fee: { percentage: 2.0 },
+  })
+  .otherwise({ percentage: 3.0 })
+  .build();
+
+await delopay.fees.rules.upsert({ algorithm }, 'merchant_abc123');
+
+const program = await delopay.fees.rules.retrieve('merchant_abc123'); // or null
+await delopay.fees.rules.delete('merchant_abc123'); // revert to flat schedules
+```
+
+Merchants without a rule program keep their existing flat fee schedules / volume
+tier unchanged.
+
+### Webhook verification
+
+Delopay signs each outgoing webhook with HMAC-SHA512 over the raw request body and delivers the hex-encoded digest in the `X-Webhook-Signature-512` header. Use `express.raw()` (not `express.json()`) so the bytes reach the verifier unchanged.
+
+The verified event matches the wire body: `{ merchant_id, event_id, event_type, content: { type, object }, timestamp }`. `event_type` says what happened (e.g. `'payment_succeeded'`); `content.type` tags the payload kind (e.g. `'payment_details'`) — narrow on it to get a typed `content.object` (the payment/refund/dispute, with `payment_id` etc.).
+
+```typescript
+import express from 'express';
+import { Delopay } from '@delopay/sdk';
+
+app.post('/webhooks/delopay', express.raw({ type: 'application/json' }), async (req, res) => {
+  const signature = req.header('x-webhook-signature-512') ?? '';
+  const secret = process.env.DELOPAY_WEBHOOK_SECRET!;
+
+  let event;
+  try {
+    event = await Delopay.webhooks.verify(req.body, signature, secret);
+  } catch {
+    return res.status(400).send('Invalid signature');
+  }
+
+  if (event.content.type === 'payment_details') {
+    const payment = event.content.object; // typed: PaymentResponse
+    switch (event.event_type) {
+      case 'payment_succeeded':
+        // fulfil order — payment.payment_id, payment.amount, payment.currency
+        break;
+      case 'payment_failed':
+        // notify customer — payment.error_message
+        break;
+    }
+  }
+
+  res.json({ received: true });
+});
+```
+
+## Error Handling
+
+All errors are instances of `DelopayError`:
+
+```typescript
+import { Delopay, DelopayError, DelopayAuthenticationError } from '@delopay/sdk';
+
+try {
+  const payment = await delopay.payments.retrieve('pay_does_not_exist');
+} catch (err) {
+  if (err instanceof DelopayAuthenticationError) {
+    // status: 401 — invalid or missing API key
+    console.error('Check your API key');
+  } else if (err instanceof DelopayError) {
+    console.error(err.message); // human-readable message
+    console.error(err.status); // HTTP status code
+    console.error(err.code); // machine-readable error code
+    console.error(err.type); // error category (e.g. 'not_found')
+    console.error(err.data); // structured context for select codes (see below)
+  }
+}
+```
+
+**Error classes:**
+
+| Class                        | When                               |
+| ---------------------------- | ---------------------------------- |
+| `DelopayError`               | Base class for all API errors      |
+| `DelopayAuthenticationError` | `401` — invalid or missing API key |
+
+Network timeouts throw `DelopayError` with `code: 'TIMEOUT'`. Network failures throw with `code: 'NETWORK'`.
+
+**Structured error context (`err.data`):** populated for a small set of codes that benefit from a machine-readable hint. Currently:
+
+| `err.code` | `err.data` shape               | Meaning                                                                    |
+| ---------- | ------------------------------ | -------------------------------------------------------------------------- |
+| `UR_48`    | `{ retry_after_secs: number }` | TOTP attempt counter locked out — wait this many seconds before retrying.  |
+| `UR_63`    | `{ retry_after_secs: number }` | Auth-endpoint rate limit tripped — wait this many seconds before retrying. |
+
+## TypeScript
+
+The SDK is written in strict TypeScript. All request and response shapes are fully typed. Import types directly when needed:
+
+```typescript
+import type { PaymentResponse, PaymentCreateRequest, Currency } from '@delopay/sdk';
+```
+
+## Environments
+
+| Environment | Base URL                      | API key prefix       |
+| ----------- | ----------------------------- | -------------------- |
+| Production  | `https://api.delopay.net`     | `prd_…` / `pk_prd_…` |
+| Sandbox     | `https://sandbox.delopay.net` | `snd_…` / `pk_snd_…` |
+
+```typescript
+// Sandbox
+const delopay = new Delopay(process.env.DELOPAY_API_KEY!, { sandbox: true });
+```
+
+## License
+
+MIT