@revenexx/node 0.0.2 → 0.1.1

package/dist/services/payments-ledger.d.mts

@@ -0,0 +1,551 @@
+import { Client } from '../client.mjs';
+import { Models } from '../models.mjs';
+import { PaymentStatus } from '../enums/payment-status.mjs';
+import { PaymentMethodKind } from '../enums/payment-method-kind.mjs';
+import { PaymentDunningStage } from '../enums/payment-dunning-stage.mjs';
+import { PaymentsVocabulariesGetName } from '../enums/payments-vocabularies-get-name.mjs';
+import '../query.mjs';
+import '../enums/address-type-row-tone.mjs';
+import '../enums/address-type-row-create-request-tone.mjs';
+import '../enums/address-type-row-update-request-tone.mjs';
+import '../enums/approval-rule-approver-type.mjs';
+import '../enums/approval-rule-condition.mjs';
+import '../enums/approval-rule-effect.mjs';
+import '../enums/approval-rule-create-request-approver-type.mjs';
+import '../enums/approval-rule-create-request-condition.mjs';
+import '../enums/approval-rule-create-request-effect.mjs';
+import '../enums/approval-rule-update-request-approver-type.mjs';
+import '../enums/approval-rule-update-request-condition.mjs';
+import '../enums/approval-rule-update-request-effect.mjs';
+import '../enums/assets-source.mjs';
+import '../enums/attribute-value-bucket.mjs';
+import '../enums/auth-mail-source.mjs';
+import '../enums/recovery-mail-source.mjs';
+import '../enums/registration-status.mjs';
+import '../enums/budget-change-reason.mjs';
+import '../enums/budget-movement-result-status.mjs';
+import '../enums/cart-status.mjs';
+import '../enums/cart-merge-strategy.mjs';
+import '../enums/cart-price-snapshot-mode.mjs';
+import '../enums/cart-io-format.mjs';
+import '../enums/cart-export-format.mjs';
+import '../enums/cart-item-type.mjs';
+import '../enums/cart-vocabulary-tone.mjs';
+import '../enums/cart-vocabulary-name.mjs';
+import '../enums/cart-vocabulary-source.mjs';
+import '../enums/cart-vocabulary-ref-name.mjs';
+import '../enums/categories-rule-match.mjs';
+import '../enums/category-rule-operator.mjs';
+import '../enums/category-rule-match.mjs';
+import '../enums/channel-status.mjs';
+import '../enums/channel-unassigned-visibility.mjs';
+import '../enums/channel-unresolved-reason.mjs';
+import '../enums/channel-context-source.mjs';
+import '../enums/channel-inactive-behavior.mjs';
+import '../enums/channel-policy-source.mjs';
+import '../enums/channel-policy-tenant-default.mjs';
+import '../enums/channel-unassigned-policy.mjs';
+import '../enums/channel-type-tone.mjs';
+import '../enums/channel-visibility-reason.mjs';
+import '../enums/channel-vocabulary-tone.mjs';
+import '../enums/channel-vocabulary-name.mjs';
+import '../enums/channel-vocabulary-source.mjs';
+import '../enums/channel-vocabulary-ref-name.mjs';
+import '../enums/contact-registration-status.mjs';
+import '../enums/contact-status.mjs';
+import '../enums/contact-activity-kind.mjs';
+import '../enums/contact-create-request-registration-status.mjs';
+import '../enums/contact-event-kind-tone.mjs';
+import '../enums/contact-event-kind-create-request-tone.mjs';
+import '../enums/contact-event-kind-update-request-tone.mjs';
+import '../enums/contact-update-request-registration-status.mjs';
+import '../enums/cost-center-budget-type.mjs';
+import '../enums/cost-center-restriction-type.mjs';
+import '../enums/cost-center-restriction-create-request-type.mjs';
+import '../enums/cost-center-restriction-update-request-type.mjs';
+import '../enums/payment-fee-type.mjs';
+import '../enums/form-status.mjs';
+import '../enums/form-submission-status.mjs';
+import '../enums/form-notify-source.mjs';
+import '../enums/form-submission-prune-request-status.mjs';
+import '../enums/forms-vocabulary-tone.mjs';
+import '../enums/forms-vocabulary-name.mjs';
+import '../enums/forms-vocabulary-summary-name.mjs';
+import '../enums/inventory-vocabulary-default-tone.mjs';
+import '../enums/inventory-vocabulary-source.mjs';
+import '../enums/cart-io-apply-mode.mjs';
+import '../enums/cart-io-direction.mjs';
+import '../enums/cart-io-entity.mjs';
+import '../enums/io-profile-resource-apply-mode.mjs';
+import '../enums/io-profile-resource-direction.mjs';
+import '../enums/lifecycle-stage-tone.mjs';
+import '../enums/lifecycle-stage-create-request-tone.mjs';
+import '../enums/lifecycle-stage-update-request-tone.mjs';
+import '../enums/location-type.mjs';
+import '../enums/market-status.mjs';
+import '../enums/market-default-locale-source.mjs';
+import '../enums/market-locale-fallback.mjs';
+import '../enums/market-locale-granularity.mjs';
+import '../enums/market-pricing-source.mjs';
+import '../enums/market-tax-basis.mjs';
+import '../enums/market-readiness-check-id.mjs';
+import '../enums/market-readiness-severity.mjs';
+import '../enums/markets-vocabulary-tone.mjs';
+import '../enums/markets-vocabulary-name.mjs';
+import '../enums/markets-vocabulary-source.mjs';
+import '../enums/markets-vocabulary-summary-name.mjs';
+import '../enums/order-fulfillment-status.mjs';
+import '../enums/order-payment-status.mjs';
+import '../enums/order-status.mjs';
+import '../enums/order-cancellation-scope.mjs';
+import '../enums/order-comment-visibility.mjs';
+import '../enums/order-item-type.mjs';
+import '../enums/order-list-kind-tone.mjs';
+import '../enums/order-list-kind-row-tone.mjs';
+import '../enums/order-list-cart-mode.mjs';
+import '../enums/order-list-vocabulary-default-tone.mjs';
+import '../enums/order-list-vocabulary-name.mjs';
+import '../enums/order-list-vocabulary-source.mjs';
+import '../enums/order-list-vocabulary-tone.mjs';
+import '../enums/order-return-status.mjs';
+import '../enums/order-return-settlement.mjs';
+import '../enums/order-return-refusal.mjs';
+import '../enums/order-vocabulary-tone.mjs';
+import '../enums/order-vocabulary-name.mjs';
+import '../enums/order-vocabulary-source.mjs';
+import '../enums/order-vocabulary-summary-name.mjs';
+import '../enums/order-resolution-stage.mjs';
+import '../enums/organization-status.mjs';
+import '../enums/page-status.mjs';
+import '../enums/pages-vocabulary-app.mjs';
+import '../enums/pages-vocabulary-tone.mjs';
+import '../enums/pages-vocabulary-name.mjs';
+import '../enums/pages-vocabulary-source.mjs';
+import '../enums/pages-vocabulary-index-app.mjs';
+import '../enums/payment-failure-code.mjs';
+import '../enums/payment-term-tone.mjs';
+import '../enums/payment-term-create-request-tone.mjs';
+import '../enums/payment-term-update-request-tone.mjs';
+import '../enums/payment-vocabulary-tone.mjs';
+import '../enums/pending-approval-approver-type.mjs';
+import '../enums/pending-approval-status.mjs';
+import '../enums/price-ending-rule.mjs';
+import '../enums/price-entries-adjust-response-rounding.mjs';
+import '../enums/price-entries-adjust-response-rounding-mode.mjs';
+import '../enums/price-entries-bulk-mode.mjs';
+import '../enums/price-rounding-mode.mjs';
+import '../enums/price-entry-type.mjs';
+import '../enums/price-list-status.mjs';
+import '../enums/price-list-tax-basis.mjs';
+import '../enums/price-currency-source.mjs';
+import '../enums/price-list-tiebreak.mjs';
+import '../enums/price-tax-inclusive-default.mjs';
+import '../enums/price-tax-unresolved-reason.mjs';
+import '../enums/price-tax-market-source.mjs';
+import '../enums/price-vocabulary-tone.mjs';
+import '../enums/price-vocabulary-name.mjs';
+import '../enums/price-vocabulary-source.mjs';
+import '../enums/price-vocabulary-ref-name.mjs';
+import '../enums/product-categories-source.mjs';
+import '../enums/product-grid-column-source.mjs';
+import '../enums/product-label-source.mjs';
+import '../enums/product-label-attribute-source.mjs';
+import '../enums/products-kind.mjs';
+import '../enums/purchase-request-status.mjs';
+import '../enums/purchase-request-event-name.mjs';
+import '../enums/purchase-request-item-type.mjs';
+import '../enums/purchase-request-item-create-request-type.mjs';
+import '../enums/purchase-request-item-update-request-type.mjs';
+import '../enums/reorder-point-source.mjs';
+import '../enums/reservation-status.mjs';
+import '../enums/price-on-request-reason.mjs';
+import '../enums/price-tax-basis.mjs';
+import '../enums/price-tax-basis-source.mjs';
+import '../enums/role-catalog-response-source.mjs';
+import '../enums/segment-rule-match.mjs';
+import '../enums/segment-member-source.mjs';
+import '../enums/segment-rule-operator.mjs';
+import '../enums/segment-rule-preview-request-rule-match.mjs';
+import '../enums/segment-rule-preview-request-target.mjs';
+import '../enums/segment-rule-preview-response-rule-match.mjs';
+import '../enums/segment-rule-preview-response-target.mjs';
+import '../enums/segment-rules-target.mjs';
+import '../enums/shipping-carrier-status.mjs';
+import '../enums/shipping-method-matrix-basis.mjs';
+import '../enums/shipping-method-pricing-type.mjs';
+import '../enums/shipping-carrier-source.mjs';
+import '../enums/shipping-rate-pricing-type.mjs';
+import '../enums/shipping-tax-source.mjs';
+import '../enums/shipping-free-above-basis.mjs';
+import '../enums/shipping-rates-basis-matrix-basis-default.mjs';
+import '../enums/shipping-service-level-create-request-tone.mjs';
+import '../enums/shipping-service-level-row-tone.mjs';
+import '../enums/shipping-service-level-update-request-tone.mjs';
+import '../enums/shipping-tax-unresolved-reason.mjs';
+import '../enums/shipping-tax-market-source.mjs';
+import '../enums/shipping-tax-context-via.mjs';
+import '../enums/shipping-tracking-carrier-status.mjs';
+import '../enums/shipping-vocabulary-default-tone.mjs';
+import '../enums/shipping-vocabulary-source.mjs';
+import '../enums/shipping-vocabulary-tone.mjs';
+import '../enums/shipping-weight-unit-create-request-tone.mjs';
+import '../enums/shipping-weight-unit-row-tone.mjs';
+import '../enums/shipping-weight-unit-update-request-tone.mjs';
+import '../enums/stock-movement-type.mjs';
+import '../enums/store-asset-request-visibility.mjs';
+import '../enums/submit-item-type.mjs';
+import '../enums/submit-result-outcome.mjs';
+import '../enums/validation-failed-response-status.mjs';
+import '../enums/vocabulary-default-tone.mjs';
+import '../enums/vocabulary-source.mjs';
+import '../enums/vocabulary-tone.mjs';
+import '../enums/attribute-boolean-status.mjs';
+import '../enums/attribute-datetime-status.mjs';
+import '../enums/attribute-email-status.mjs';
+import '../enums/attribute-enum-status.mjs';
+import '../enums/attribute-float-status.mjs';
+import '../enums/attribute-integer-status.mjs';
+import '../enums/attribute-ip-status.mjs';
+import '../enums/attribute-line-status.mjs';
+import '../enums/attribute-longtext-status.mjs';
+import '../enums/attribute-mediumtext-status.mjs';
+import '../enums/attribute-point-status.mjs';
+import '../enums/attribute-polygon-status.mjs';
+import '../enums/attribute-relationship-status.mjs';
+import '../enums/attribute-string-status.mjs';
+import '../enums/attribute-text-status.mjs';
+import '../enums/attribute-url-status.mjs';
+import '../enums/attribute-varchar-status.mjs';
+import '../enums/column-boolean-status.mjs';
+import '../enums/column-datetime-status.mjs';
+import '../enums/column-email-status.mjs';
+import '../enums/column-enum-status.mjs';
+import '../enums/column-float-status.mjs';
+import '../enums/column-integer-status.mjs';
+import '../enums/column-ip-status.mjs';
+import '../enums/column-line-status.mjs';
+import '../enums/column-longtext-status.mjs';
+import '../enums/column-mediumtext-status.mjs';
+import '../enums/column-point-status.mjs';
+import '../enums/column-polygon-status.mjs';
+import '../enums/column-relationship-status.mjs';
+import '../enums/column-string-status.mjs';
+import '../enums/column-text-status.mjs';
+import '../enums/column-url-status.mjs';
+import '../enums/column-varchar-status.mjs';
+import '../enums/database-type.mjs';
+import '../enums/deployment-status.mjs';
+import '../enums/execution-status.mjs';
+import '../enums/execution-trigger.mjs';
+import '../enums/health-antivirus-status.mjs';
+import '../enums/health-status-status.mjs';
+import '../enums/index-status.mjs';
+import '../enums/message-2-status.mjs';
+
+declare class PaymentsLedger {
+    client: Client;
+    constructor(client: Client);
+    /**
+     * The ledger, paged and filtered — the Payments screen, the reconciliation query and the way an order or a cart finds out what has been paid against it. Every column of the entity is an exact-match filter, which is what makes it useful: `?cart_id=` and `?contact_id=` are indexed, `?status=authorized&kind=self_managed` is the awaiting-payment queue the dunning scan classifies, and `?order_ref=` is the only way to resolve a payment by its external reference. Rows come back in the database's own order, so a newest-first list needs `?order=created_at.desc`. `error_message` is answered from the failure taxonomy rather than echoed out of the column, so what a driver or a PSP actually wrote is never serialized here.
+     *
+     * @param {number} params.limit - Page size (default 50, max 200).
+     * @param {number} params.offset - Row offset for pagination (default 0).
+     * @param {string} params.order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
+     * @param {string} params.cartId - The cart a payment pays for. Indexed.
+     * @param {string} params.contactId - The paying customer contact. Indexed.
+     * @param {PaymentStatus} params.status - Restrict to one lifecycle state. Indexed.
+     * @param {string} params.orderRef - Exact external order reference.
+     * @param {string} params.methodCode - Exact code of the method the payment was made with.
+     * @param {PaymentMethodKind} params.kind - Restrict to self-managed or PSP-backed payments.
+     * @param {string} params.provider - Exact PSP code.
+     * @param {PaymentDunningStage} params.dunningStage - Restrict to one dunning stage — what the daily scan wrote.
+     * @param {string} params.idempotencyKey - Exact idempotency key. Unique per tenant, so this answers at most one row.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsList(params?: {
+        limit?: number;
+        offset?: number;
+        order?: string;
+        cartId?: string;
+        contactId?: string;
+        status?: PaymentStatus;
+        orderRef?: string;
+        methodCode?: string;
+        kind?: PaymentMethodKind;
+        provider?: string;
+        dunningStage?: PaymentDunningStage;
+        idempotencyKey?: string;
+    }): Promise<{}>;
+    /**
+     * The ledger, paged and filtered — the Payments screen, the reconciliation query and the way an order or a cart finds out what has been paid against it. Every column of the entity is an exact-match filter, which is what makes it useful: `?cart_id=` and `?contact_id=` are indexed, `?status=authorized&kind=self_managed` is the awaiting-payment queue the dunning scan classifies, and `?order_ref=` is the only way to resolve a payment by its external reference. Rows come back in the database's own order, so a newest-first list needs `?order=created_at.desc`. `error_message` is answered from the failure taxonomy rather than echoed out of the column, so what a driver or a PSP actually wrote is never serialized here.
+     *
+     * @param {number} limit - Page size (default 50, max 200).
+     * @param {number} offset - Row offset for pagination (default 0).
+     * @param {string} order - Sort by one column: 'column' | 'column.asc' | 'column.desc'. A bare column sorts ascending. Anything else is refused with 400.
+     * @param {string} cartId - The cart a payment pays for. Indexed.
+     * @param {string} contactId - The paying customer contact. Indexed.
+     * @param {PaymentStatus} status - Restrict to one lifecycle state. Indexed.
+     * @param {string} orderRef - Exact external order reference.
+     * @param {string} methodCode - Exact code of the method the payment was made with.
+     * @param {PaymentMethodKind} kind - Restrict to self-managed or PSP-backed payments.
+     * @param {string} provider - Exact PSP code.
+     * @param {PaymentDunningStage} dunningStage - Restrict to one dunning stage — what the daily scan wrote.
+     * @param {string} idempotencyKey - Exact idempotency key. Unique per tenant, so this answers at most one row.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsList(limit?: number, offset?: number, order?: string, cartId?: string, contactId?: string, status?: PaymentStatus, orderRef?: string, methodCode?: string, kind?: PaymentMethodKind, provider?: string, dunningStage?: PaymentDunningStage, idempotencyKey?: string): Promise<{}>;
+    /**
+     * The checkout's write: it opens the ledger row and takes it as far as the named method allows, in one call. A create cannot omit `method_code` and `amount`; every other column is optional or defaulted by the database. Nothing else about the money is the caller's to choose: `kind`, `provider` and `fee_amount` are read off the method that `method_code` names, so a caller can neither pick an acquirer nor discount its own fee. `amount: 0` is legal (free orders); negative is 400. Eligibility is enforced HERE and not only in the checkout UI — the same country and order-value rules POST /payments/methods/eligible applies answer 422 if the method does not apply to this buyer. What comes back depends on the method: a self-managed one (invoice, prepayment) is `authorized` at once with the dunning clock already started, and a PSP one is `captured` or `authorized`, or `requires_action` with `next_action` — the instruction the storefront must carry out, typically a redirect, set at that status and at no other. Send an `idempotency_key` and a repeat of the same call answers 200 with the payment that key already named, unchanged and not re-authorized. What is never stored: the `instrument`, `token` or `card` is handed to the driver in-process and no token or PAN is written to the row.
+     *
+     * @param {number} params.amount - What the provider is asked to authorize, in `currency`. 0 is legal (a free order) and negative is refused by the handler and by the CHECK behind it. `fee_amount` is recorded beside this and is NOT added to it — a checkout that charges its payment surcharge sends a total that already includes it.
+     * @param {string} params.methodCode - The `code` of the payment method this payment was made with, copied at creation. Deliberately a code and not a foreign key: the ledger records what happened and has to outlive the configuration it happened under. It must name a method this tenant has configured; eligibility for the buyer context below is re-checked here, whatever the checkout showed.
+     * @param {string} params.cartId - The cart this payment pays for. Not a foreign key: the payment is a record of what happened and outlives the cart. Indexed, so it is the cheap way to find the payment behind a checkout.
+     * @param {string} params.contactId - The paying customer contact. Not a foreign key — a payment must survive a contact being merged or erased. Indexed.
+     * @param {string} params.country - The buyer's ISO 3166-1 alpha-2 country code, for the eligibility check. A method restricted to countries is refused with 422 without it.
+     * @param {string} params.currency - ISO 4217 code the amount and the fee are in. The database bounds the length at three characters and nothing else, so lower case is stored as written. Defaults to EUR.
+     * @param {string} params.idempotencyKey - The caller's own key for this creation attempt. Sending it again answers the SAME payment with 200 instead of creating a second one — which is what makes a retried checkout safe. Unique per tenant, so a filter on it answers at most one row. The replay answers 200, not 201.
+     * @param {object} params.metadata - Free-form data to keep on the payment. Merged with the keys this app writes itself (`provider_method`, `return_url`, later the cancel/refund reasons), which win on a collision.
+     * @param {string} params.orderRef - The external order reference the checkout wrote onto the payment. It is what POST /payments/orders/{order_ref}/capture resolves and the fallback key a PSP webhook is matched on when it carries no transaction id — so an integration that leaves it null gives up both. Free text with no uniqueness: several payments may share one reference.
+     * @param {string} params.returnUrl - Where the PSP sends the buyer back after a redirect or a 3-D Secure challenge. Kept in `metadata.return_url` and handed to the driver — a PSP method that needs a redirect and has none leaves the buyer stranded at the provider.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsCreate(params: {
+        amount: number;
+        methodCode: string;
+        cartId?: string;
+        contactId?: string;
+        country?: string;
+        currency?: string;
+        idempotencyKey?: string;
+        metadata?: object;
+        orderRef?: string;
+        returnUrl?: string;
+    }): Promise<Models.Payment>;
+    /**
+     * The checkout's write: it opens the ledger row and takes it as far as the named method allows, in one call. A create cannot omit `method_code` and `amount`; every other column is optional or defaulted by the database. Nothing else about the money is the caller's to choose: `kind`, `provider` and `fee_amount` are read off the method that `method_code` names, so a caller can neither pick an acquirer nor discount its own fee. `amount: 0` is legal (free orders); negative is 400. Eligibility is enforced HERE and not only in the checkout UI — the same country and order-value rules POST /payments/methods/eligible applies answer 422 if the method does not apply to this buyer. What comes back depends on the method: a self-managed one (invoice, prepayment) is `authorized` at once with the dunning clock already started, and a PSP one is `captured` or `authorized`, or `requires_action` with `next_action` — the instruction the storefront must carry out, typically a redirect, set at that status and at no other. Send an `idempotency_key` and a repeat of the same call answers 200 with the payment that key already named, unchanged and not re-authorized. What is never stored: the `instrument`, `token` or `card` is handed to the driver in-process and no token or PAN is written to the row.
+     *
+     * @param {number} amount - What the provider is asked to authorize, in `currency`. 0 is legal (a free order) and negative is refused by the handler and by the CHECK behind it. `fee_amount` is recorded beside this and is NOT added to it — a checkout that charges its payment surcharge sends a total that already includes it.
+     * @param {string} methodCode - The `code` of the payment method this payment was made with, copied at creation. Deliberately a code and not a foreign key: the ledger records what happened and has to outlive the configuration it happened under. It must name a method this tenant has configured; eligibility for the buyer context below is re-checked here, whatever the checkout showed.
+     * @param {string} cartId - The cart this payment pays for. Not a foreign key: the payment is a record of what happened and outlives the cart. Indexed, so it is the cheap way to find the payment behind a checkout.
+     * @param {string} contactId - The paying customer contact. Not a foreign key — a payment must survive a contact being merged or erased. Indexed.
+     * @param {string} country - The buyer's ISO 3166-1 alpha-2 country code, for the eligibility check. A method restricted to countries is refused with 422 without it.
+     * @param {string} currency - ISO 4217 code the amount and the fee are in. The database bounds the length at three characters and nothing else, so lower case is stored as written. Defaults to EUR.
+     * @param {string} idempotencyKey - The caller's own key for this creation attempt. Sending it again answers the SAME payment with 200 instead of creating a second one — which is what makes a retried checkout safe. Unique per tenant, so a filter on it answers at most one row. The replay answers 200, not 201.
+     * @param {object} metadata - Free-form data to keep on the payment. Merged with the keys this app writes itself (`provider_method`, `return_url`, later the cancel/refund reasons), which win on a collision.
+     * @param {string} orderRef - The external order reference the checkout wrote onto the payment. It is what POST /payments/orders/{order_ref}/capture resolves and the fallback key a PSP webhook is matched on when it carries no transaction id — so an integration that leaves it null gives up both. Free text with no uniqueness: several payments may share one reference.
+     * @param {string} returnUrl - Where the PSP sends the buyer back after a redirect or a 3-D Secure challenge. Kept in `metadata.return_url` and handed to the driver — a PSP method that needs a redirect and has none leaves the buyer stranded at the provider.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsCreate(amount: number, methodCode: string, cartId?: string, contactId?: string, country?: string, currency?: string, idempotencyKey?: string, metadata?: object, orderRef?: string, returnUrl?: string): Promise<Models.Payment>;
+    /**
+     * Classifies every unpaid self-managed payment (invoice, prepayment) as on time / reminder due / overdue from payment_reminder_after_days and overdue_after_days, writes the stage and the next due date, and reports PSP payments still waiting on a callback longer than webhook_stale_after_minutes. Pure function of each payment's age, so it is idempotent — it also runs daily as the 'dunning-scan' schedule. It classifies and does not send: a stage change emits payment.updated, and what a reminder looks like is the merchant's workflow.
+     *
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsDunningScan(): Promise<{}>;
+    /**
+     * Rows written before the failure taxonomy still store the provider's/runtime's raw text in error_message. API responses never repeat it (the read path projects), but the column is also read directly through Baseline, so it needs rewriting once per tenant. Dry-run by default — reports what it would touch and changes nothing until apply:true. Idempotent: rows already carrying a taxonomy message are skipped.
+     *
+     * @param {boolean} params.apply - Write the reclassified values. Defaults to false, which reports what WOULD change and touches nothing.
+     * @param {number} params.limit - How many payments to scan, oldest first. Defaults to 500, capped at 5000 — a tenant with more pre-taxonomy rows needs several runs, and re-running is free.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsErrorsRedact(params?: {
+        apply?: boolean;
+        limit?: number;
+    }): Promise<{}>;
+    /**
+     * Rows written before the failure taxonomy still store the provider's/runtime's raw text in error_message. API responses never repeat it (the read path projects), but the column is also read directly through Baseline, so it needs rewriting once per tenant. Dry-run by default — reports what it would touch and changes nothing until apply:true. Idempotent: rows already carrying a taxonomy message are skipped.
+     *
+     * @param {boolean} apply - Write the reclassified values. Defaults to false, which reports what WOULD change and touches nothing.
+     * @param {number} limit - How many payments to scan, oldest first. Defaults to 500, capped at 5000 — a tenant with more pre-taxonomy rows needs several runs, and re-running is free.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsErrorsRedact(apply?: boolean, limit?: number): Promise<{}>;
+    /**
+     * This is the hook the tenant's `auto_capture_policy: 'on_ship'` was written for: fulfilment knows the order it shipped and not the payment ids behind it, so the shipment calls this one route with the reference it already holds and the money for that order is collected in a single request. Resolves payments by their order_ref (the same key the PSP webhooks fall back to), captures every authorized one and reports the rest instead of failing — an order whose payment was already captured is a successful no-op, and a provider that refuses one payment lands in `skipped` rather than failing the call. Note that payments.order_ref is nullable with no foreign key: this route is exactly as good as the reference the checkout writes onto the payment.
+     *
+     * @param {string} params.orderRef - The external order reference the checkout wrote onto the payment, trimmed before it is resolved. Free text — the example is an invented shape, not a reference any tenant holds, and one no payment carries answers 404.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsOrdersCapture(params: {
+        orderRef: string;
+    }): Promise<{}>;
+    /**
+     * This is the hook the tenant's `auto_capture_policy: 'on_ship'` was written for: fulfilment knows the order it shipped and not the payment ids behind it, so the shipment calls this one route with the reference it already holds and the money for that order is collected in a single request. Resolves payments by their order_ref (the same key the PSP webhooks fall back to), captures every authorized one and reports the rest instead of failing — an order whose payment was already captured is a successful no-op, and a provider that refuses one payment lands in `skipped` rather than failing the call. Note that payments.order_ref is nullable with no foreign key: this route is exactly as good as the reference the checkout writes onto the payment.
+     *
+     * @param {string} orderRef - The external order reference the checkout wrote onto the payment, trimmed before it is resolved. Free text — the example is an invented shape, not a reference any tenant holds, and one no payment carries answers 404.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsOrdersCapture(orderRef: string): Promise<{}>;
+    /**
+     * The enums this app owns, four of them: statuses, method kinds, fee types and dunning stages. This is the index and carries a name and a title per set and nothing more — the values themselves, with their labels and badge tones, are one call further down at GET /payments/vocabularies/{name}, so a client that only needs to know which sets exist does not pay for all of them. Values come out of the CHECK constraints, so what is served is what the database enforces — a client renders a status this app adds without a release of its own.
+     *
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsVocabulariesList(): Promise<{}>;
+    /**
+     * One set in full: every value it permits, the label to show for each and the badge tone to render it in, which is what a client needs to draw a status chip without hard-coding this app's enums. The value set is parsed out of the CHECK constraint in schema.json, so what is served IS what the database enforces. Labels are curated on top and can only add words and colour — a permitted value nobody labelled still appears, titled from its own key, which is why `title` and `description` are a locale map on a labelled value and a plain string on an unlabelled one.
+     *
+     * @param {PaymentsVocabulariesGetName} params.name - Which vocabulary to read. The set is closed: GET /payments/vocabularies lists exactly these.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.PaymentVocabulary>}
+     */
+    paymentsVocabulariesGet(params: {
+        name: PaymentsVocabulariesGetName;
+    }): Promise<Models.PaymentVocabulary>;
+    /**
+     * One set in full: every value it permits, the label to show for each and the badge tone to render it in, which is what a client needs to draw a status chip without hard-coding this app's enums. The value set is parsed out of the CHECK constraint in schema.json, so what is served IS what the database enforces. Labels are curated on top and can only add words and colour — a permitted value nobody labelled still appears, titled from its own key, which is why `title` and `description` are a locale map on a labelled value and a plain string on an unlabelled one.
+     *
+     * @param {PaymentsVocabulariesGetName} name - Which vocabulary to read. The set is closed: GET /payments/vocabularies lists exactly these.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.PaymentVocabulary>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsVocabulariesGet(name: PaymentsVocabulariesGetName): Promise<Models.PaymentVocabulary>;
+    /**
+     * The sink a PSP callback ends up in, and an inbound ingress endpoint in the sense of ADR-0066: the provider never posts here directly, it posts to webhooks.revenexx.com, which verifies and captures the delivery and dispatches its envelope to this route through the gateway. That indirection is also what makes this the one override point for PSP callback handling — everything a callback does to the ledger happens here and nowhere else, so a deployment that needs a provider's callbacks normalized differently replaces this operation instead of touching the lifecycle routes. Consumes the dispatch envelope from webhooks.revenexx.com: normalizes the provider callback (stripe payment intents + a generic shape), resolves the payment by psp_payment_id or order_ref and moves the ledger. Facts only move forward — provider retries and redeliveries are idempotent no-ops; unverified envelopes are refused.
+     *
+     * @param {string} params.provider - The catalog provider code whose callback shape to normalize. Anything the normalizer does not recognise is read as the generic {event, psp_payment_id?, order_ref?, error?} envelope rather than refused.
+     * @param {any} params.id - The dispatcher's delivery id. Echoed back as `delivery_id` so a delivery and what the ledger did can be correlated.
+     * @param {object} params.request - The captured HTTP request as the PSP sent it.
+     * @param {any} params.verified - Whether the ingress verified the callback signature against the provider's `webhook_secret`. An explicit false is refused with 422: an endpoint may run in annotate mode, and the ledger stays sovereign over one that does.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     */
+    paymentsWebhooksIngest(params: {
+        provider: string;
+        id?: any;
+        request?: object;
+        verified?: any;
+    }): Promise<{}>;
+    /**
+     * The sink a PSP callback ends up in, and an inbound ingress endpoint in the sense of ADR-0066: the provider never posts here directly, it posts to webhooks.revenexx.com, which verifies and captures the delivery and dispatches its envelope to this route through the gateway. That indirection is also what makes this the one override point for PSP callback handling — everything a callback does to the ledger happens here and nowhere else, so a deployment that needs a provider's callbacks normalized differently replaces this operation instead of touching the lifecycle routes. Consumes the dispatch envelope from webhooks.revenexx.com: normalizes the provider callback (stripe payment intents + a generic shape), resolves the payment by psp_payment_id or order_ref and moves the ledger. Facts only move forward — provider retries and redeliveries are idempotent no-ops; unverified envelopes are refused.
+     *
+     * @param {string} provider - The catalog provider code whose callback shape to normalize. Anything the normalizer does not recognise is read as the generic {event, psp_payment_id?, order_ref?, error?} envelope rather than refused.
+     * @param {any} id - The dispatcher's delivery id. Echoed back as `delivery_id` so a delivery and what the ledger did can be correlated.
+     * @param {object} request - The captured HTTP request as the PSP sent it.
+     * @param {any} verified - Whether the ingress verified the callback signature against the provider's `webhook_secret`. An explicit false is refused with 422: an endpoint may run in annotate mode, and the ledger stays sovereign over one that does.
+     * @throws {RevenexxException}
+     * @returns {Promise<{}>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsWebhooksIngest(provider: string, id?: any, request?: object, verified?: any): Promise<{}>;
+    /**
+     * One ledger row in full: the amount and the fee that were computed at creation, the method code and PSP it was made through, where it stands in the lifecycle, the timestamp of each transition it has been through (`authorized_at`, `captured_at`, `failed_at`, `refunded_at`), the dunning columns the daily scan maintains and, while the buyer still has something to do, `next_action`. This is the call to poll after sending a buyer to a PSP redirect. Two things it does not do: `error_message` is answered from the failure taxonomy and never carries the provider's or the runtime's own words, and there is no route that resolves a payment by `order_ref` — that column is nullable and not unique, so it is a filter on the list (`GET /payments?order_ref=…`) which may legitimately answer several rows.
+     *
+     * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsGet(params: {
+        id: string;
+    }): Promise<Models.Payment>;
+    /**
+     * One ledger row in full: the amount and the fee that were computed at creation, the method code and PSP it was made through, where it stands in the lifecycle, the timestamp of each transition it has been through (`authorized_at`, `captured_at`, `failed_at`, `refunded_at`), the dunning columns the daily scan maintains and, while the buyer still has something to do, `next_action`. This is the call to poll after sending a buyer to a PSP redirect. Two things it does not do: `error_message` is answered from the failure taxonomy and never carries the provider's or the runtime's own words, and there is no route that resolves a payment by `order_ref` — that column is nullable and not unique, so it is a filter on the list (`GET /payments?order_ref=…`) which may legitimately answer several rows.
+     *
+     * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsGet(id: string): Promise<Models.Payment>;
+    /**
+     * Drops the claim before any money has been taken — the abandoned basket, the buyer who never came back from the redirect, the invoice an operator writes off. It is the only transition that starts from three statuses rather than one, because everything short of captured can still be released. A captured payment is not cancellable at all: that is a refund, and the lattice answers 400 rather than pretending. Unlike capture and refund this transition has no time window — the merchant's `capture_expiry_days` and `refund_window_days` do not apply, so a stale authorization can always be released even once it is too old to collect. On a PSP payment the provider is called and the `reason` in the body is passed to it, so it reaches the PSP's own cancellation-reason field as well as being stored under `metadata.cancel_reason`. Cancelling stops the dunning clock: the stage goes back to `none` and the due date is cleared.
+     *
+     * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @param {string} params.reason - The operator's own words for why. Kept on the payment (`metadata.cancel_reason` / `metadata.refund_reason`) AND handed to the provider's own cancellation or refund reason field, so it is readable in the PSP's dashboard too. Trimmed and cut at 500 characters.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsCancel(params: {
+        id: string;
+        reason?: string;
+    }): Promise<Models.Payment>;
+    /**
+     * Drops the claim before any money has been taken — the abandoned basket, the buyer who never came back from the redirect, the invoice an operator writes off. It is the only transition that starts from three statuses rather than one, because everything short of captured can still be released. A captured payment is not cancellable at all: that is a refund, and the lattice answers 400 rather than pretending. Unlike capture and refund this transition has no time window — the merchant's `capture_expiry_days` and `refund_window_days` do not apply, so a stale authorization can always be released even once it is too old to collect. On a PSP payment the provider is called and the `reason` in the body is passed to it, so it reaches the PSP's own cancellation-reason field as well as being stored under `metadata.cancel_reason`. Cancelling stops the dunning clock: the stage goes back to `none` and the due date is cleared.
+     *
+     * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @param {string} reason - The operator's own words for why. Kept on the payment (`metadata.cancel_reason` / `metadata.refund_reason`) AND handed to the provider's own cancellation or refund reason field, so it is readable in the PSP's dashboard too. Trimmed and cut at 500 characters.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsCancel(id: string, reason?: string): Promise<Models.Payment>;
+    /**
+     * Collects money that is currently only reserved. It starts from `authorized` and from nothing else — under `auto_capture_policy: 'immediate'` a payment is captured in the same request that created it and never passes through here, so this is the route for the 'manual' and 'on_ship' policies, and POST /payments/orders/{order_ref}/capture is the same operation addressed by the order reference a warehouse actually holds. There is no request body and no amount: the ledger carries one amount and one status, so a capture is the whole authorization or nothing. On a self-managed payment it takes no PSP anywhere near it — it records that an invoice or a prepayment was paid, and stops the dunning clock. Refused with 422 once the authorization is older than the tenant's `capture_expiry_days` (the message carries both numbers), because an expired authorization is declined by the provider anyway and a 422 here is the cheap version of finding out later.
+     *
+     * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsCapture(params: {
+        id: string;
+    }): Promise<Models.Payment>;
+    /**
+     * Collects money that is currently only reserved. It starts from `authorized` and from nothing else — under `auto_capture_policy: 'immediate'` a payment is captured in the same request that created it and never passes through here, so this is the route for the 'manual' and 'on_ship' policies, and POST /payments/orders/{order_ref}/capture is the same operation addressed by the order reference a warehouse actually holds. There is no request body and no amount: the ledger carries one amount and one status, so a capture is the whole authorization or nothing. On a self-managed payment it takes no PSP anywhere near it — it records that an invoice or a prepayment was paid, and stops the dunning clock. Refused with 422 once the authorization is older than the tenant's `capture_expiry_days` (the message carries both numbers), because an expired authorization is declined by the provider anyway and a 422 here is the cheap version of finding out later.
+     *
+     * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsCapture(id: string): Promise<Models.Payment>;
+    /**
+     * The other half of a redirect. POST /payments answered `requires_action` with a `next_action` the storefront carried out — a 3-D Secure step, a wallet approval, a bank login — and this is the call that asks the PSP how it went and writes the answer to the ledger. It starts from `requires_action` and from nothing else, so a payment that already came back authorized needs no confirm and the lattice answers 400 rather than repeating one. `next_action` is cleared by this call whatever the outcome. Where the tenant's `auto_capture_policy` is 'immediate' the money is taken straight after the authorization, in the same request, so a successful confirm can come back `captured` rather than `authorized`; a failed auto-capture does not fail the confirm, because a good authorization is worth more than a tidy status.
+     *
+     * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsConfirm(params: {
+        id: string;
+    }): Promise<Models.Payment>;
+    /**
+     * The other half of a redirect. POST /payments answered `requires_action` with a `next_action` the storefront carried out — a 3-D Secure step, a wallet approval, a bank login — and this is the call that asks the PSP how it went and writes the answer to the ledger. It starts from `requires_action` and from nothing else, so a payment that already came back authorized needs no confirm and the lattice answers 400 rather than repeating one. `next_action` is cleared by this call whatever the outcome. Where the tenant's `auto_capture_policy` is 'immediate' the money is taken straight after the authorization, in the same request, so a successful confirm can come back `captured` rather than `authorized`; a failed auto-capture does not fail the confirm, because a good authorization is worth more than a tidy status.
+     *
+     * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsConfirm(id: string): Promise<Models.Payment>;
+    /**
+     * Gives captured money back. It starts from `captured` and from nothing else — money that was only authorized is cancelled, not refunded, and the lattice answers 400 rather than guessing which was meant. All or nothing: the ledger carries one amount and one status, so there is no partial refund and no second one to express — a refunded payment is refunded in full, and a repeat is a 400 because `refunded` is not a status a refund starts from. The `reason` in the body is handed to the driver in the same call, so it reaches the PSP's own refund-reason field rather than being a note only this database ever sees, and it is stored under `metadata.refund_reason`. On a self-managed payment nothing is sent anywhere: it records that the merchant paid the buyer back by their own means. Refused with 422 once the capture is older than the tenant's `refund_window_days` (the message carries both numbers) — past that the provider stops accepting a refund against the transaction and it has to be made by bank transfer.
+     *
+     * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @param {string} params.reason - The operator's own words for why. Kept on the payment (`metadata.cancel_reason` / `metadata.refund_reason`) AND handed to the provider's own cancellation or refund reason field, so it is readable in the PSP's dashboard too. Trimmed and cut at 500 characters.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     */
+    paymentsRefund(params: {
+        id: string;
+        reason?: string;
+    }): Promise<Models.Payment>;
+    /**
+     * Gives captured money back. It starts from `captured` and from nothing else — money that was only authorized is cancelled, not refunded, and the lattice answers 400 rather than guessing which was meant. All or nothing: the ledger carries one amount and one status, so there is no partial refund and no second one to express — a refunded payment is refunded in full, and a repeat is a 400 because `refunded` is not a status a refund starts from. The `reason` in the body is handed to the driver in the same call, so it reaches the PSP's own refund-reason field rather than being a note only this database ever sees, and it is stored under `metadata.refund_reason`. On a self-managed payment nothing is sent anywhere: it records that the merchant paid the buyer back by their own means. Refused with 422 once the capture is older than the tenant's `refund_window_days` (the message carries both numbers) — past that the provider stops accepting a refund against the transaction and it has to be made by bank transfer.
+     *
+     * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
+     * @param {string} reason - The operator's own words for why. Kept on the payment (`metadata.cancel_reason` / `metadata.refund_reason`) AND handed to the provider's own cancellation or refund reason field, so it is readable in the PSP's dashboard too. Trimmed and cut at 500 characters.
+     * @throws {RevenexxException}
+     * @returns {Promise<Models.Payment>}
+     * @deprecated Use the object parameter style method for a better developer experience.
+     */
+    paymentsRefund(id: string, reason?: string): Promise<Models.Payment>;
+}
+
+export { PaymentsLedger };