@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/providers/payment-cashfree/easy-split.js

@@ -0,0 +1,206 @@
+/*
+ * Cashfree EASY SPLIT — the vendor and per-vendor-share surface.
+ *
+ * Split out of `index.ts` rather than left in it for two reasons, and the
+ * second is the one that matters:
+ *
+ *   1. that file reached the 1,000-line `max-lines` ceiling;
+ *   2. **every fact in here was originally SPECIFIED, NOT CONFIRMED, and now
+ *      is — verified end to end against a real sandbox vendor + split
+ *      order, not just docs** — see the block below for what 2026-11-05's
+ *      live calls found wrong or missing — isolating it here meant
+ *      correcting each one was an edit to one named thing in one file, with
+ *      no call-site changes.
+ *
+ * `audit-payment-provider-import` allowlists `payment-cashfree/**`, so a
+ * sibling module here is as legitimate as `index.ts` itself.
+ *
+ * EXPORTS: EASY_SPLIT_VENDORS_PATH, ORDER_SPLITS_FIELD,
+ *          MAX_SPLIT_VENDORS_PER_ORDER, mapCashfreeVendorStatus,
+ *          cashfreeVendorPayload, toOrderSplits, CashfreeVendorEntity
+ */
+import { paiseToRupees } from "../../core/money.js";
+/*
+ * 🛑🛑 CONFIRMED 2026-11-05, END TO END — a real sandbox vendor registration
+ * followed by a real sandbox split order against it, both succeeded (200),
+ * with `order_splits` echoed back correctly on the order entity. This
+ * section used to read "every fact below is SPECIFIED, NOT CONFIRMED" —
+ * this is what actually retired that, not just reading docs (CLAUDE.md
+ * Rule #11): five things were wrong or missing, found by the live calls
+ * themselves, not by research:
+ *
+ *   1. THE VENDOR ENDPOINT AND ITS BODY (`cashfreeVendorPayload` /
+ *      `EASY_SPLIT_VENDORS_PATH`). Path confirmed exactly
+ *      (`/easy-split/vendors`). The body was NOT exactly right — the raw
+ *      example request body in Cashfree's own Create Vendor reference uses
+ *      `ifsc` and `account_holder` on both the `bank` and `upi` destination
+ *      objects; this file's original guess used `account_ifsc` and omitted
+ *      `account_holder` entirely on both. Fixed in `cashfreeVendorPayload`
+ *      below — see its own comment.
+ *
+ *   2. THE SPLIT FIELD ON THE ORDER (`ORDER_SPLITS_FIELD`, `toOrderSplits`).
+ *      This was the DANGEROUS one — a wrong field name here is not
+ *      necessarily an error; Cashfree could silently ignore an unknown key
+ *      and capture the order with no split, collecting another seller's
+ *      money into the platform's own account while looking like a success.
+ *      CONFIRMED CORRECT as originally written: `order_splits`, each entry
+ *      `{vendor_id, amount}` — verbatim from the Create Order OpenAPI schema,
+ *      and now also confirmed by a real order actually echoing it back.
+ *
+ *   3. HOW MANY VENDORS ONE ORDER MAY CARRY (`MAX_SPLIT_VENDORS_PER_ORDER`).
+ *      Confirmed via Cashfree's own Easy Split FAQ: "You can split a single
+ *      transaction among a maximum of 5 vendors." Set below.
+ *
+ *   4. `status` ON THE VENDOR PAYLOAD. Found live, not from docs — a real
+ *      sandbox Create Vendor call without this field was rejected with
+ *      `status_missing`. Added as a required `"ACTIVE"` literal; see
+ *      `CashfreeVendorPayload`'s own comment.
+ *
+ *   5. `kyc_details.business_type` ON THE VENDOR PAYLOAD. Also found live —
+ *      an omitted `kyc_details` was rejected with `kyc_details_missing`;
+ *      an empty one was then rejected with
+ *      `kyc_details.business_type_missing`; a guessed `"Individual"` was
+ *      then rejected with `INVALID_REQUEST_TYPE` and Cashfree's own
+ *      validator handed back the full accepted enum in its error message.
+ *      `"E-commerce"` — confirmed correct, not guessed — is now sent for
+ *      every vendor; see `CASHFREE_VENDOR_BUSINESS_TYPE`'s own comment for
+ *      the full accepted list.
+ */
+/** Confirmed against Cashfree's own Create Vendor API reference, 2026-11-05. */
+export const EASY_SPLIT_VENDORS_PATH = "/easy-split/vendors";
+/** Confirmed against Cashfree's own Create Order OpenAPI schema, 2026-11-05 — each entry `{vendor_id, amount}`. */
+export const ORDER_SPLITS_FIELD = "order_splits";
+/**
+ * Confirmed against Cashfree's own Easy Split FAQ, 2026-11-05: "You can
+ * split a single transaction among a maximum of 5 vendors."
+ *
+ * A multi-vendor cart in this codebase produces ONE payment across SEVERAL
+ * orders (`createPhonePeGroupOrder` is called once per seller group off a
+ * single capture), so this is the real ceiling the adapter refuses above —
+ * see `createOrderWithSplit`'s own check. Never truncates: dropping the
+ * last vendor's split would collect their share into the platform's account
+ * and look like a success: a cart needing a 6th seller settled gets a loud,
+ * buyer-visible refusal instead.
+ */
+export const MAX_SPLIT_VENDORS_PER_ORDER = 5;
+/**
+ * Cashfree's vendor status → the contract's outcome.
+ *
+ * 🛑 FAILS CLOSED, and "closed" here means **`pending`, not `rejected`**. An
+ * unrecognised status must not become `active` (that would let a split be built
+ * against a vendor Cashfree has not approved) and must not become `rejected`
+ * either — a refusal is a statement about the seller that sends an operator to
+ * contact them, and we would be making it up. `pending` is the only honest
+ * answer to "Cashfree said something we do not recognise": the split path
+ * refuses to settle to a non-`active` vendor, so nothing is collected wrongly,
+ * and the raw value is carried in the message so a human can read it.
+ */
+export function mapCashfreeVendorStatus(status) {
+    switch ((status ?? "").toUpperCase()) {
+        case "ACTIVE":
+            return "active";
+        case "BLOCKED":
+        case "DELETED":
+        case "REJECTED":
+            return "rejected";
+        default:
+            // `PENDING`, `IN_BENE_CREATION`, and anything we have not seen.
+            return "pending";
+    }
+}
+/*
+ * 🛑 CONFIRMED 2026-11-05 live against Cashfree's sandbox validator — a
+ * guessed `business_type: "Individual"` was rejected with
+ * `INVALID_REQUEST_TYPE` and this VERBATIM accepted list: Grocery,
+ * Jewellery, Miscellaneous, Web host/Domain seller, E-commerce, Online
+ * Gaming, Society/Trust/Club/Association, Mutual funds/Broking, B2B, Real
+ * Estate, Housing, Rentals, Utilities, Travel and Hospitality, Education,
+ * Food and Beverages, NBFCs/Organizations into Lending, Chit Funds, Non
+ * Profit/NGO, Financial Services, Government, Readymade, SaaS, Professional
+ * Services (Doctors, Lawyers, Architects, CAs, and other Professionals),
+ * Open and Semi Open Wallet, Social Media and Entertainment, Pan shop,
+ * Telecom, Digital Goods, Insurance, Pharmacy, Healthcare, Retail and
+ * Shopping, Gaming, Logistics.
+ *
+ * Every vendor this platform registers IS a marketplace seller on this
+ * platform — there is no per-seller input to collect here, so this is a
+ * platform-wide constant, not a guess per vendor. `"E-commerce"` is the one
+ * entry that actually describes what every vendor here is.
+ */
+const CASHFREE_VENDOR_BUSINESS_TYPE = "E-commerce";
+export function cashfreeVendorPayload(input) {
+    /*
+     * 🛑 CONFIRMED 2026-11-05 against Cashfree's own raw example request body
+     * (API reference, Create Vendor) — `account_holder` and `ifsc` (NOT
+     * `account_ifsc`), on BOTH destination objects. The original guess here
+     * used `account_ifsc` and omitted `account_holder` on both bank and UPI —
+     * exactly the "wrong key, Cashfree ignores it, vendor registers with an
+     * incomplete/wrong destination" risk the file's own header warns about.
+     * Fixed to the confirmed shape.
+     */
+    const destination = input.bank
+        ? {
+            bank: {
+                account_number: input.bank.accountNumber,
+                account_holder: input.bank.accountHolderName,
+                ifsc: input.bank.ifsc.toUpperCase(),
+            },
+        }
+        : input.upi
+            ? { upi: { vpa: input.upi.vpa, account_holder: input.upi.accountHolderName } }
+            : {};
+    return {
+        vendor_id: input.vendorId,
+        status: "ACTIVE",
+        name: input.name,
+        email: input.email,
+        phone: input.phone,
+        verify_account: true,
+        dashboard_access: false,
+        ...destination,
+        /*
+         * 🛑 `kyc_details` is now ALWAYS sent — see the field's own comment on
+         * `CashfreeVendorPayload`. `business_type` is the one sub-field
+         * Cashfree's validator requires; `pan`/`gst` stay conditional since a
+         * seller with neither is a real state (blocker #5), not an error to
+         * force — only `business_type` is non-negotiable.
+         */
+        kyc_details: {
+            business_type: CASHFREE_VENDOR_BUSINESS_TYPE,
+            ...(input.pan ? { pan: input.pan } : {}),
+            ...(input.gstin ? { gst: input.gstin } : {}),
+        },
+    };
+}
+/**
+ * Split instructions → Cashfree's `order_splits`.
+ *
+ * 🛑 DECIMAL RUPEES, like `order_amount`. Every caller passes the smallest
+ * unit; the conversion happens here, at the boundary, exactly once. A split in
+ * the wrong unit is indistinguishable from a correct one until a seller is paid
+ * 100× too much.
+ *
+ * 🛑 Refuses a zero or negative share rather than sending it. A ₹0 split is at
+ * best a no-op and at worst a 400 that fails the whole capture; either way the
+ * caller computed something it did not mean, and the correct response is to say
+ * so rather than to quietly drop a vendor from a settlement.
+ */
+export function toOrderSplits(splits) {
+    return splits.map((split) => {
+        if (!split.vendorId) {
+            throw Object.assign(new Error(`Cashfree split instruction for store "${split.storeId}" has no vendorId — ` +
+                `that store is not registered as an Easy Split vendor, so its share ` +
+                `cannot be settled to it.`), { httpStatus: 409, code: "SPLIT_VENDOR_UNREGISTERED" });
+        }
+        if (!Number.isFinite(split.amount) || split.amount <= 0) {
+            throw Object.assign(new Error(`Cashfree split instruction for vendor "${split.vendorId}" has a ` +
+                `non-positive amount (${split.amount}). Refusing rather than dropping ` +
+                `the vendor from the settlement.`), { httpStatus: 400, code: "SPLIT_AMOUNT_INVALID" });
+        }
+        return {
+            vendor_id: split.vendorId,
+            // 🛑 DECIMAL RUPEES — the one unit conversion on the way out.
+            amount: paiseToRupees(split.amount),
+        };
+    });
+}

package/dist/providers/payment-cashfree/index.d.ts

@@ -0,0 +1,341 @@
+/**
+ * @mohasinac/payment-cashfree — Cashfree Payments PG (Orders API) IPaymentProvider
+ *
+ * Implements the `IPaymentProvider` contract against Cashfree's PG Orders API
+ * using bare `fetch` — **no SDK, no new npm dependency**. Credentials arrive
+ * through the constructor, same shape as `payment-manual`, `payment-phonepe`
+ * and `payment-razorpay`: no Firestore read, no DB dependency, and no second
+ * "deprecated standalone helper" surface that bypasses the provider registry
+ * (Root Cause #75).
+ *
+ * Why this gateway exists alongside the other two: Razorpay and PhonePe both
+ * name "Bidding/Auction houses" in their prohibited-merchant lists, and this
+ * marketplace's `collector-drop` listing type is competitive bidding. Cashfree's
+ * published terms do not name the activity. Which listing types that unblocks is
+ * a LATER change — see the plan's Phase 1b — and nothing in this file touches
+ * `blockedPaymentMethods`.
+ *
+ * ## 🛑 Three structural differences every caller must account for
+ *
+ *   1. **`order_amount` is DECIMAL RUPEES**, not the smallest currency unit.
+ *      Every caller in this codebase passes the smallest unit (the create-order
+ *      route computes `rupeesToPaise(amountDue)`), and Razorpay/PhonePe both
+ *      take it natively. So the conversion happens HERE, at the boundary, in
+ *      both directions, through `paiseToRupees`/`rupeesToPaise` — and every
+ *      value this class RETURNS stays in the smallest unit so that no consumer
+ *      of `PaymentOrder` / `PaymentCapture` / `Refund` changes. A figure in the
+ *      wrong unit is indistinguishable from a correct one until somebody reads a
+ *      100x amount on an invoice, which is this project's own money-unit
+ *      cautionary tale.
+ *
+ *   2. **There is NO `checkoutUrl`.** Cashfree has no hosted page in this
+ *      integration: `POST /pg/orders` returns a `payment_session_id` which its
+ *      own browser SDK consumes. It is surfaced as
+ *      `PaymentOrder.metadata.paymentSessionId` (see `CASHFREE_SESSION_METADATA_KEY`)
+ *      rather than being dressed up as a URL — inventing one would hand the
+ *      browser a link that 404s. `checkoutUrl` is therefore deliberately unset,
+ *      exactly as `RazorpayProvider` leaves it unset for its client-side modal.
+ *
+ *   3. **`customer_details.customer_phone` is MANDATORY** and Cashfree validates
+ *      its format, so there is no placeholder to fall back on. `createOrder`
+ *      refuses without it, naming the field. The caller resolves a real number
+ *      (the buyer's delivery address, then their profile) or fails the checkout
+ *      before any payment session exists.
+ *
+ * @example
+ * ```ts
+ * registerProviders({
+ *   payment: new CashfreeProvider({
+ *     appId: process.env.CASHFREE_APP_ID!,
+ *     secretKey: process.env.CASHFREE_SECRET_KEY!,
+ *     environment: (process.env.CASHFREE_ENVIRONMENT as "sandbox" | "production") ?? "sandbox",
+ *   }),
+ * });
+ * ```
+ */
+import { IPaymentProvider } from "../../contracts";
+import type { PaymentOrder, PaymentCapture, Refund, Dispute, GatewayPaymentRecord, SettlementVendorInput, SettlementVendorResult, SplitInstruction } from "../../contracts";
+import type { JsonValue } from "../../schemas/types";
+/** Where the `payment_session_id` is published on `PaymentOrder.metadata`. */
+export declare const CASHFREE_SESSION_METADATA_KEY = "paymentSessionId";
+export interface CashfreeConfig {
+    /**
+     * Cashfree's App ID — sent as `x-client-id`.
+     *
+     * 🛑 NOT publishable. Unlike Razorpay's `keyId`, this is a server credential
+     * and must never reach the browser; the browser receives only a
+     * `payment_session_id`, which is per-order and short-lived.
+     */
+    appId: string;
+    /**
+     * Secret key — sent as `x-client-secret`, and ALSO the webhook-signing key
+     * (see `verifyCashfreeWebhookSignature`'s own doc comment — Cashfree has no
+     * separate dedicated webhook secret; confirmed against both the live docs
+     * and the dashboard directly, 2026-11-05). Server-only.
+     */
+    secretKey: string;
+    /** Selects the base URL: sandbox vs production. */
+    environment: "sandbox" | "production";
+    /** Overrides `x-api-version`. Leave unset unless pinning deliberately. */
+    apiVersion?: string;
+}
+/**
+ * Cashfree signs a webhook over BOTH a timestamp header and the raw body, so
+ * verification needs two values while `IPaymentProvider.verifyWebhook(payload,
+ * signature)` has one slot for them. Rather than widen the shared contract for
+ * one gateway, the two are packed into the `signature` argument by a helper this
+ * module owns — so both ends of the encoding live in the provider and no call
+ * site invents a format.
+ *
+ * `.` is unambiguous as a separator: the timestamp is digits and the signature
+ * is base64 (`A-Za-z0-9+/=`), so the split is at the FIRST `.` and neither half
+ * can contain one.
+ */
+export declare const CASHFREE_WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
+export declare const CASHFREE_WEBHOOK_TIMESTAMP_HEADER = "x-webhook-timestamp";
+/** Packs the two webhook headers into one `signature` argument. */
+export declare function packCashfreeWebhookSignature(timestamp: string, signature: string): string;
+/**
+ * The ONE place a Cashfree webhook signature is computed.
+ *
+ * **CONFIRMED 2026-11-05** against Cashfree's own published docs (and the
+ * dashboard directly, for the one part docs alone couldn't settle): the
+ * construction is `base64(HMAC-SHA256(timestamp + rawBody, secretKey))`,
+ * compared against the `x-webhook-signature` header with `x-webhook-timestamp`
+ * as the timestamp. All three previously-open questions are resolved:
+ *
+ *   · CONCATENATION ORDER: `timestamp + body` — confirmed (docs' own
+ *     pseudocode: `signedPayload := $timestamp.$payload`).
+ *   · SIGNING KEY: the SAME API `secretKey` used for order creation — NOT a
+ *     separate webhook secret. Cashfree has no dedicated webhook-signing
+ *     credential; confirmed both in their docs and directly in the dashboard
+ *     (checked 2026-11-05 — no such field exists there). The original
+ *     `webhookSecret` config field this function used to read was a wrong
+ *     assumption, now removed.
+ *   · ENCODING: base64 — confirmed (`Base64Encode(HMACSHA256(...))`).
+ *
+ * Still worth proving BOTH ways once a real delivery is available: a genuine
+ * webhook must verify AND a tampered body must be rejected. A check that has
+ * only ever been seen to pass is not evidence (CLAUDE.md Rule #11) — this
+ * confirms the CONSTRUCTION against the vendor's own spec, which is
+ * necessary but not a substitute for watching one real delivery succeed.
+ *
+ * It is isolated in this one named function precisely so that correcting the
+ * assumption is a one-function edit with no call-site changes.
+ *
+ * 🛑 FAILS CLOSED on every path — no secret, no signature, no timestamp, a
+ * non-numeric timestamp, or a mismatch all return `false`. "I cannot verify
+ * this" and "the signature is good" must never collapse into one return value
+ * on the call that decides whether a payment is genuine.
+ */
+export declare function verifyCashfreeWebhookSignature(rawBody: string, signature: string, timestamp: string, secret: string): boolean;
+export declare class CashfreeProvider extends IPaymentProvider {
+    readonly name = "cashfree";
+    readonly acceptsRestrictedListingTypes: readonly ["collector-drop", "clearance"];
+    private readonly baseUrl;
+    private readonly appId;
+    private readonly secretKey;
+    private readonly apiVersion;
+    constructor(config: CashfreeConfig);
+    /**
+     * The single HTTP boundary. Bare `fetch` — the gateway is three endpoints, so
+     * an SDK would be a dependency for less code than this method.
+     *
+     * A non-2xx carries Cashfree's own body into the thrown message (useful: its
+     * errors name the offending field) and its status as `httpStatus`, which is
+     * what `mapToHttpError` reads. Production scrubs 5xx messages before they
+     * reach a buyer, so the detail stays server-side.
+     */
+    /**
+     * One HTTPS call to Cashfree.
+     *
+     * 🛑 `path` is a SEGMENT, with or without a leading slash — this method owns
+     * the join. Callers may therefore name their endpoints without a leading
+     * slash, which matters because `no-restricted-syntax` reads a bare
+     * `"/orders"` as an APP route that should come from `ROUTES.*`. It is not:
+     * it is a third-party API path, and `ROUTES` would be exactly the wrong home
+     * for it. Normalising here lets the constants say what they are instead of
+     * being spelled around the rule.
+     */
+    private request;
+    /**
+     * Creates a Cashfree order.
+     *
+     * `amount` is in the SMALLEST CURRENCY UNIT — what every caller in this
+     * codebase passes — and is converted to the decimal rupees Cashfree's
+     * `order_amount` expects. The returned `amount` is converted back, so the
+     * contract this provider satisfies is identical to Razorpay's and PhonePe's.
+     *
+     * Required `metadata`:
+     *   · `uid`           — becomes `customer_details.customer_id`, and is packed
+     *                        into `order_tags` so the webhook can place the order
+     *                        with no buyer session.
+     *   · `customerPhone` — `customer_details.customer_phone`, MANDATORY at
+     *                        Cashfree and format-validated there, so there is no
+     *                        placeholder worth sending.
+     *
+     * Optional: `customerEmail`, `customerName`, `redirectUrl` (becomes
+     * `order_meta.return_url`), and anything else the caller wants round-tripped
+     * through `order_tags`.
+     *
+     * 🛑 Returns NO `checkoutUrl`. The browser needs
+     * `metadata.paymentSessionId` — see the class header, point 2.
+     */
+    createOrder(amount: number, currency?: string, metadata?: Record<string, JsonValue>): Promise<PaymentOrder>;
+    /**
+     * Creates a Cashfree order whose CAPTURE is split across vendors.
+     *
+     * 🛑 This is the method the checkout path calls — always, even with no
+     * splits. See `IPaymentProvider.createOrderWithSplit` for why there is one
+     * call site rather than a choice between two methods.
+     *
+     * 🛑 Every vendor named in `splits` must already be an `active` Easy Split
+     * vendor. That is the CALLER's check (`buildSplitInstructions` refuses to
+     * build a split for an unregistered store, and `toOrderSplits` refuses an
+     * empty `vendorId`) because the caller is the only place that holds the store
+     * documents and can refuse BEFORE a payment session exists.
+     *
+     * 🛑 Refuses above `MAX_SPLIT_VENDORS_PER_ORDER` and NEVER truncates — see
+     * that constant's own 🛑. Dropping the last vendor's split would collect
+     * their share into the platform's account and look like a success.
+     */
+    createOrderWithSplit(amount: number, currency: string, metadata?: Record<string, JsonValue>, splits?: readonly SplitInstruction[]): Promise<PaymentOrder>;
+    /**
+     * The one implementation behind both public create methods.
+     *
+     * Kept private so there is no third way to create a Cashfree order: a second
+     * public entry point is a second place a split instruction can be forgotten.
+     */
+    private createOrderInternal;
+    /**
+     * Converts a Cashfree decimal-rupee figure back to the smallest unit.
+     *
+     * 🛑 `fallback` is what to use when the gateway echoed no amount at all, and
+     * the right value differs per call site — so it is a PARAMETER rather than a
+     * constant. `createOrder` passes the amount it asked to be charged, because
+     * repeating that is better than a confident wrong figure. `capturePayment`
+     * and `getOrder` have nothing truer to offer and pass `0`; that is a known
+     * weakness of a missing field rather than a claim the amount was zero, and a
+     * `NaN` there (what `Number(undefined)` would give) would propagate silently
+     * into arithmetic instead of reading as absent.
+     */
+    private toSmallestUnit;
+    /**
+     * Registers a seller as an Easy Split vendor.
+     *
+     * 🛑 IDEMPOTENT BY `PUT`-LIKE SEMANTICS, and that is an ASSUMPTION too. The
+     * `vendor_id` is ours (the store slug), so a repeat call names the same
+     * vendor — but whether Cashfree treats a second `POST` for a known
+     * `vendor_id` as an update, a conflict, or a duplicate has NOT been
+     * confirmed. The failure is benign in both directions this adapter can see:
+     * a conflict surfaces as a 409 carried into `message` and the job records
+     * `rejected`, which an operator reads and acts on. It is called out because
+     * the job WILL re-run — jobs retry, and an admin can re-approve a store.
+     *
+     * 🛑 Returns `pending` for any status it does not recognise, never `active`
+     * and never `rejected`. See `mapCashfreeVendorStatus`.
+     *
+     * 🛑 A NON-2xx IS NOT A THROW HERE, unlike every other method on this class.
+     * `request()` throws, so the catch converts it into `outcome: "rejected"`
+     * with Cashfree's own body as the message. That is deliberate: the caller is
+     * a background job whose job is to RECORD why a store could not be onboarded
+     * (blockers #3 and #5 mean refusals are expected and routine), and a throw
+     * would make a routine refusal indistinguishable from an outage. The one
+     * thing that must never happen is a refusal recorded as a success.
+     *
+     * 🛑 The thrown message is carried VERBATIM but truncated. Cashfree's errors
+     * name the offending field, which is the whole value of surfacing them — and
+     * `request()` already caps the body at 500 chars. It describes the
+     * DESTINATION the seller supplied; it carries no credential of ours.
+     */
+    registerSettlementVendor(input: SettlementVendorInput): Promise<SettlementVendorResult>;
+    /**
+     * Validates a webhook. `payload` is the RAW request body string; `signature`
+     * is the packed `"<timestamp>.<signature>"` value built by
+     * `packCashfreeWebhookSignature` from the two Cashfree headers.
+     *
+     * 🛑 The raw body is what gets verified, never a re-serialised object:
+     * `JSON.stringify(JSON.parse(body))` is not guaranteed to reproduce the bytes
+     * that were signed.
+     *
+     * Fails closed when the packed value is malformed or on any mismatch.
+     * Reports validity only — the caller parses the body itself after this
+     * returns `true`, same as the existing webhook route.
+     *
+     * Signed with `this.secretKey` — see `verifyCashfreeWebhookSignature`'s own
+     * doc comment for why that's the correct key, not a separate webhook secret.
+     */
+    verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * Cashfree has no buyer-present SIGNED callback of Razorpay's shape.
+     *
+     * Its browser SDK resolves with a result object, but that is not a signed
+     * proof of payment — confirmation comes from the Orders API (`getOrder`) or
+     * the webhook (`verifyWebhook`). So there is nothing here to verify, and the
+     * honest answer is rejection.
+     *
+     * 🛑 `false`, never `true`. "No signature to check" and "the signature is
+     * good" must never collapse into the same return value on the call that
+     * decides whether a payment is genuine.
+     */
+    verifyCheckoutSignature(_payload: Record<string, string>, _secret: string): boolean;
+    /**
+     * Reports the state of the payment behind an order. `orderId` is our own
+     * merchant `order_id`.
+     *
+     * Named `capturePayment` by the contract, but it does NOT capture: Cashfree's
+     * Orders flow auto-captures, so a successful payment is already captured by
+     * the time anything here runs — the same situation as Razorpay's provider.
+     *
+     * Reads `GET /orders/{id}/payments` rather than the order itself, because the
+     * order entity carries no payment id and this is the one method required to
+     * report a `transactionId`. One call, not two.
+     *
+     * 🛑 `PaymentCapture.status` is only `captured | failed`, so a `PENDING`
+     * Cashfree payment maps to `failed` — i.e. "not captured". That is the same
+     * narrowing Razorpay's provider applies and it fails toward not concluding
+     * money moved; `getOrder()` is the method that can express an in-between
+     * state.
+     */
+    capturePayment(orderId: string): Promise<PaymentCapture>;
+    /**
+     * Initiates a refund. `paymentId` here is actually our original merchant
+     * `order_id` — Cashfree refunds are ORDER-keyed
+     * (`POST /orders/{order_id}/refunds`), not payment-keyed. The inherited
+     * parameter name from `IPaymentProvider` is misleading for this provider and
+     * is kept only because the base contract is shared; PhonePe has exactly the
+     * same mismatch for the same reason.
+     *
+     * `amount` is in the smallest currency unit and is REQUIRED: Cashfree's
+     * `refund_amount` is mandatory, so there is no whole-order refund shorthand
+     * to translate an omitted amount into.
+     */
+    refund(paymentId: string, amount?: number): Promise<Refund>;
+    /**
+     * Fetches an order and reports its REAL status. This is the authoritative
+     * "was this paid" check — `verifyAndPlaceGatewayOrderAction` gates order
+     * placement on `status === "paid"`, so `mapOrderStatus` is load-bearing and
+     * an unknown value must never resolve to "paid".
+     *
+     * `metadata` round-trips whatever `createOrder` put in `order_tags`, which is
+     * how the WEBHOOK path (no buyer session) recovers the checkout intent — the
+     * same job PhonePe's `metaInfo` and Razorpay's `notes` do. Without it the
+     * webhook could confirm a payment and then have no uid to place the order for.
+     *
+     * 🛑 That `order_tags` is echoed back on the order entity is an ASSUMPTION of
+     * the same class as the webhook signature's: confirm it against the live API
+     * before relying on the webhook fallback, because the failure mode is a
+     * captured payment with no placeable order (the incident class this project
+     * already has a write-up for).
+     */
+    getOrder(orderId: string): Promise<PaymentOrder>;
+    /**
+     * 🛑 `[]` because the wrapped API cannot enumerate payments in a window — not
+     * because there are none. See the block comment above; the contract requires
+     * the caller to treat an empty list as NO INFORMATION.
+     */
+    listPayments(): Promise<GatewayPaymentRecord[]>;
+    getDispute(disputeId: string): Promise<Dispute>;
+    listDisputes(): Promise<Dispute[]>;
+    acceptDispute(disputeId: string, _confirmIrrevocable: true): Promise<Dispute>;
+}