@delopay/sdk 0.34.0 → 0.35.1

package/README.md

@@ -171,6 +171,108 @@ const gateway = await delopay.shops.gateways.connect(merchantId, shop.shop_id, {
 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.
+
 ### 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.

package/dist/index.d.cts

@@ -840,6 +840,19 @@ interface BillingProfileResponse {
     consecutive_recharge_failures: number;
     stripe_customer_id?: string | null;
     suspended_at?: string | null;
+    /**
+     * Whether the merchant is on the trusted list. Trusted merchants are
+     * exempt from automatic AND manual suspension until the flag is cleared.
+     */
+    is_trusted: boolean;
+    /**
+     * What caused the current suspension: `auto_recharge` or `admin`. Absent
+     * when the merchant is not suspended. An `admin` suspension is sticky — a
+     * top-up will not auto-reactivate it; only an admin unsuspend lifts it.
+     */
+    suspension_source?: string | null;
+    /** Admin-provided reason for a manual suspension. Absent otherwise. */
+    suspension_reason?: string | null;
     created_at: string;
     modified_at: string;
     /**

package/dist/index.d.ts

@@ -840,6 +840,19 @@ interface BillingProfileResponse {
     consecutive_recharge_failures: number;
     stripe_customer_id?: string | null;
     suspended_at?: string | null;
+    /**
+     * Whether the merchant is on the trusted list. Trusted merchants are
+     * exempt from automatic AND manual suspension until the flag is cleared.
+     */
+    is_trusted: boolean;
+    /**
+     * What caused the current suspension: `auto_recharge` or `admin`. Absent
+     * when the merchant is not suspended. An `admin` suspension is sticky — a
+     * top-up will not auto-reactivate it; only an admin unsuspend lifts it.
+     */
+    suspension_source?: string | null;
+    /** Admin-provided reason for a manual suspension. Absent otherwise. */
+    suspension_reason?: string | null;
     created_at: string;
     modified_at: string;
     /**

package/dist/internal.cjs

@@ -4010,6 +4010,48 @@ var PlatformBilling = class {
       body: params
     });
   }
+  /**
+   * Manually suspend a merchant (e.g. confirmed fraud or ToS violation),
+   * independent of balance. A `reason` is required for audit. Throws 412 if
+   * the merchant is trusted (clear the flag first) or already suspended.
+   *
+   * @param merchantId - The merchant account ID.
+   * @param params - Suspension reason.
+   * @returns The updated billing profile.
+   */
+  async suspend(merchantId, params) {
+    return this.request("POST", `/billing/${encodeURIComponent(merchantId)}/admin/suspend`, {
+      body: params
+    });
+  }
+  /**
+   * Lift a suspension. Restores the merchant to `active` (or `delinquent` if
+   * the balance is at/below the hard floor) and resets the recharge-failure
+   * counter. Throws 412 if the merchant is not suspended.
+   *
+   * @param merchantId - The merchant account ID.
+   * @param params - Optional audit note.
+   * @returns The updated billing profile.
+   */
+  async unsuspend(merchantId, params = {}) {
+    return this.request("POST", `/billing/${encodeURIComponent(merchantId)}/admin/unsuspend`, {
+      body: params
+    });
+  }
+  /**
+   * Set or clear the trusted (suspension-exempt) flag. Trusted merchants
+   * cannot be suspended automatically or manually. Does not lift an existing
+   * suspension — use {@link PlatformBilling.unsuspend} for that.
+   *
+   * @param merchantId - The merchant account ID.
+   * @param params - The desired trusted state.
+   * @returns The updated billing profile.
+   */
+  async setTrusted(merchantId, params) {
+    return this.request("PATCH", `/billing/${encodeURIComponent(merchantId)}/admin/trusted`, {
+      body: params
+    });
+  }
 };
 
 // src/internal/resources/platformFees.ts