@revenexx/node 0.1.1 → 0.2.0

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

@@ -5,6 +5,9 @@ import { PaymentMethodKind } from '../enums/payment-method-kind.js';
 import { PaymentDunningStage } from '../enums/payment-dunning-stage.js';
 import { PaymentsVocabulariesGetName } from '../enums/payments-vocabularies-get-name.js';
 import '../query.js';
+import '../enums/accept-line-decision.js';
+import '../enums/accept-result-origin.js';
+import '../enums/accept-result-status.js';
 import '../enums/address-type-row-tone.js';
 import '../enums/address-type-row-create-request-tone.js';
 import '../enums/address-type-row-update-request-tone.js';
@@ -18,12 +21,23 @@ import '../enums/approval-rule-update-request-approver-type.js';
 import '../enums/approval-rule-update-request-condition.js';
 import '../enums/approval-rule-update-request-effect.js';
 import '../enums/assets-source.js';
+import '../enums/assignment-role-tone.js';
+import '../enums/assignment-role-create-request-tone.js';
+import '../enums/assignment-role-update-request-tone.js';
+import '../enums/attach-request-direction.js';
+import '../enums/attach-request-visibility.js';
 import '../enums/attribute-value-bucket.js';
 import '../enums/auth-mail-source.js';
+import '../enums/auth-mfa-challenge-request-factor.js';
 import '../enums/recovery-mail-source.js';
 import '../enums/registration-status.js';
+import '../enums/availability-state-tone.js';
+import '../enums/banner-draft-layout.js';
+import '../enums/banner-draft-update-request-layout.js';
 import '../enums/budget-change-reason.js';
 import '../enums/budget-movement-result-status.js';
+import '../enums/budget-release-scope.js';
+import '../enums/budget-release-status.js';
 import '../enums/cart-status.js';
 import '../enums/cart-merge-strategy.js';
 import '../enums/cart-price-snapshot-mode.js';
@@ -51,18 +65,44 @@ import '../enums/channel-vocabulary-tone.js';
 import '../enums/channel-vocabulary-name.js';
 import '../enums/channel-vocabulary-source.js';
 import '../enums/channel-vocabulary-ref-name.js';
+import '../enums/consent-record-action.js';
+import '../enums/consent-record-surface.js';
+import '../enums/consent-record-create-request-action.js';
+import '../enums/consent-record-create-request-surface.js';
+import '../enums/consent-vocabulary-source.js';
+import '../enums/contact-order-approval-mode.js';
 import '../enums/contact-registration-status.js';
 import '../enums/contact-status.js';
 import '../enums/contact-activity-kind.js';
+import '../enums/order-approval-mode.js';
 import '../enums/contact-create-request-registration-status.js';
 import '../enums/contact-event-kind-tone.js';
 import '../enums/contact-event-kind-create-request-tone.js';
 import '../enums/contact-event-kind-update-request-tone.js';
-import '../enums/contact-update-request-registration-status.js';
+import '../enums/contact-point-kind-tone.js';
+import '../enums/contact-point-kind-create-request-tone.js';
+import '../enums/contact-point-kind-update-request-tone.js';
+import '../enums/cookie-kind.js';
+import '../enums/cookie-create-request-kind.js';
+import '../enums/cookie-update-request-kind.js';
 import '../enums/cost-center-budget-type.js';
+import '../enums/cost-center-create-request-budget-type.js';
 import '../enums/cost-center-restriction-type.js';
 import '../enums/cost-center-restriction-create-request-type.js';
 import '../enums/cost-center-restriction-update-request-type.js';
+import '../enums/cost-center-update-request-budget-type.js';
+import '../enums/cost-centers-vocabulary-tone.js';
+import '../enums/cost-centers-vocabulary-name.js';
+import '../enums/cost-centers-vocabulary-source.js';
+import '../enums/cost-centers-vocabulary-summary-name.js';
+import '../enums/direct-order-status.js';
+import '../enums/document-source.js';
+import '../enums/document-visibility.js';
+import '../enums/document-kind-tone.js';
+import '../enums/document-vocabulary-default-tone.js';
+import '../enums/document-vocabulary-name.js';
+import '../enums/document-vocabulary-source.js';
+import '../enums/document-vocabulary-tone.js';
 import '../enums/payment-fee-type.js';
 import '../enums/form-status.js';
 import '../enums/form-submission-status.js';
@@ -71,6 +111,7 @@ import '../enums/form-submission-prune-request-status.js';
 import '../enums/forms-vocabulary-tone.js';
 import '../enums/forms-vocabulary-name.js';
 import '../enums/forms-vocabulary-summary-name.js';
+import '../enums/inventory-receive-warning-code.js';
 import '../enums/inventory-vocabulary-default-tone.js';
 import '../enums/inventory-vocabulary-source.js';
 import '../enums/cart-io-apply-mode.js';
@@ -78,6 +119,7 @@ import '../enums/cart-io-direction.js';
 import '../enums/cart-io-entity.js';
 import '../enums/io-profile-resource-apply-mode.js';
 import '../enums/io-profile-resource-direction.js';
+import '../enums/inventory-unorderable-reason.js';
 import '../enums/lifecycle-stage-tone.js';
 import '../enums/lifecycle-stage-create-request-tone.js';
 import '../enums/lifecycle-stage-update-request-tone.js';
@@ -94,28 +136,40 @@ import '../enums/markets-vocabulary-tone.js';
 import '../enums/markets-vocabulary-name.js';
 import '../enums/markets-vocabulary-source.js';
 import '../enums/markets-vocabulary-summary-name.js';
+import '../enums/note-request-visibility.js';
 import '../enums/order-fulfillment-status.js';
 import '../enums/order-payment-status.js';
 import '../enums/order-status.js';
 import '../enums/order-cancellation-scope.js';
 import '../enums/order-comment-visibility.js';
+import '../enums/order-discount-target.js';
+import '../enums/order-discount-effect-kind.js';
+import '../enums/order-discount-placement.js';
+import '../enums/order-discount-source.js';
+import '../enums/order-discount-value-type.js';
 import '../enums/order-item-type.js';
 import '../enums/order-list-kind-tone.js';
 import '../enums/order-list-kind-row-tone.js';
+import '../enums/order-list-skip-reason.js';
 import '../enums/order-list-cart-mode.js';
 import '../enums/order-list-vocabulary-default-tone.js';
 import '../enums/order-list-vocabulary-name.js';
 import '../enums/order-list-vocabulary-source.js';
 import '../enums/order-list-vocabulary-tone.js';
+import '../enums/order-return-refund-mode.js';
 import '../enums/order-return-status.js';
 import '../enums/order-return-settlement.js';
-import '../enums/order-return-refusal.js';
 import '../enums/order-vocabulary-tone.js';
+import '../enums/order-return-refusal.js';
 import '../enums/order-vocabulary-name.js';
 import '../enums/order-vocabulary-source.js';
 import '../enums/order-vocabulary-summary-name.js';
 import '../enums/order-resolution-stage.js';
+import '../enums/organization-credit-limit-mode.js';
+import '../enums/organization-shipping-advice.js';
 import '../enums/organization-status.js';
+import '../enums/credit-limit-mode.js';
+import '../enums/shipping-advice.js';
 import '../enums/page-status.js';
 import '../enums/pages-vocabulary-app.js';
 import '../enums/pages-vocabulary-tone.js';
@@ -135,6 +189,7 @@ import '../enums/price-entries-adjust-response-rounding-mode.js';
 import '../enums/price-entries-bulk-mode.js';
 import '../enums/price-rounding-mode.js';
 import '../enums/price-entry-type.js';
+import '../enums/price-line-price-reason.js';
 import '../enums/price-list-status.js';
 import '../enums/price-list-tax-basis.js';
 import '../enums/price-currency-source.js';
@@ -146,22 +201,86 @@ import '../enums/price-vocabulary-tone.js';
 import '../enums/price-vocabulary-name.js';
 import '../enums/price-vocabulary-source.js';
 import '../enums/price-vocabulary-ref-name.js';
+import '../enums/procurement-vocabulary-default-tone.js';
+import '../enums/procurement-vocabulary-name.js';
+import '../enums/procurement-vocabulary-source.js';
+import '../enums/procurement-vocabulary-summary-name.js';
+import '../enums/procurement-vocabulary-value-tone.js';
 import '../enums/product-categories-source.js';
 import '../enums/product-grid-column-source.js';
 import '../enums/product-label-source.js';
 import '../enums/product-label-attribute-source.js';
 import '../enums/products-kind.js';
+import '../enums/promotion-condition-match.js';
+import '../enums/promotion-reach.js';
+import '../enums/promotion-recurrence-kind.js';
+import '../enums/promotion-return-behaviour.js';
+import '../enums/promotion-status.js';
+import '../enums/promotion-bundle-allocation.js';
+import '../enums/promotion-bundle-patch-allocation.js';
+import '../enums/promotion-bundle-write-allocation.js';
+import '../enums/promotion-condition-kind.js';
+import '../enums/promotion-condition-match-mode.js';
+import '../enums/promotion-condition-patch-kind.js';
+import '../enums/promotion-condition-patch-match-mode.js';
+import '../enums/promotion-condition-write-kind.js';
+import '../enums/promotion-condition-write-match-mode.js';
+import '../enums/promotion-effect-kind.js';
+import '../enums/promotion-effect-target-scope.js';
+import '../enums/promotion-effect-unit-choice.js';
+import '../enums/promotion-effect-value-type.js';
+import '../enums/promotion-effect-patch-kind.js';
+import '../enums/promotion-effect-patch-target-scope.js';
+import '../enums/promotion-effect-patch-unit-choice.js';
+import '../enums/promotion-effect-patch-value-type.js';
+import '../enums/promotion-effect-write-kind.js';
+import '../enums/promotion-effect-write-target-scope.js';
+import '../enums/promotion-effect-write-unit-choice.js';
+import '../enums/promotion-effect-write-value-type.js';
+import '../enums/promotion-patch-condition-match.js';
+import '../enums/promotion-patch-reach.js';
+import '../enums/promotion-patch-recurrence-kind.js';
+import '../enums/promotion-patch-return-behaviour.js';
+import '../enums/promotion-patch-status.js';
+import '../enums/promotion-release-request-reason.js';
+import '../enums/promotion-write-condition-match.js';
+import '../enums/promotion-write-reach.js';
+import '../enums/promotion-write-recurrence-kind.js';
+import '../enums/promotion-write-return-behaviour.js';
+import '../enums/promotion-write-status.js';
+import '../enums/punchout-entry-probe-result-entry-probe-status.js';
+import '../enums/punchout-entry-test-result-protocol.js';
+import '../enums/punchout-field-mapping-import-request-protocol.js';
+import '../enums/punchout-return-preview-protocol.js';
 import '../enums/purchase-request-status.js';
 import '../enums/purchase-request-event-name.js';
 import '../enums/purchase-request-item-type.js';
 import '../enums/purchase-request-item-create-request-type.js';
 import '../enums/purchase-request-item-update-request-type.js';
+import '../enums/purpose-legal-basis.js';
+import '../enums/purpose-create-request-legal-basis.js';
+import '../enums/purpose-update-request-legal-basis.js';
+import '../enums/quote-origin.js';
+import '../enums/quote-status.js';
+import '../enums/quote-attachment-direction.js';
+import '../enums/quote-attachment-visibility.js';
+import '../enums/quote-detail-origin.js';
+import '../enums/quote-detail-status.js';
+import '../enums/quote-event-visibility.js';
+import '../enums/quote-item-decision.js';
+import '../enums/quote-item-price-reason.js';
+import '../enums/quote-line-input-price-reason.js';
+import '../enums/redemption-state.js';
 import '../enums/reorder-point-source.js';
 import '../enums/reservation-status.js';
 import '../enums/price-on-request-reason.js';
 import '../enums/price-tax-basis.js';
 import '../enums/price-tax-basis-source.js';
 import '../enums/role-catalog-response-source.js';
+import '../enums/sales-rep-vocabulary-default-tone.js';
+import '../enums/sales-rep-vocabulary-source.js';
+import '../enums/seed-request-mode.js';
+import '../enums/seed-result-mode.js';
 import '../enums/segment-rule-match.js';
 import '../enums/segment-member-source.js';
 import '../enums/segment-rule-operator.js';
@@ -191,14 +310,35 @@ import '../enums/shipping-vocabulary-tone.js';
 import '../enums/shipping-weight-unit-create-request-tone.js';
 import '../enums/shipping-weight-unit-row-tone.js';
 import '../enums/shipping-weight-unit-update-request-tone.js';
+import '../enums/stacking-group-mode.js';
+import '../enums/stacking-group-patch-mode.js';
+import '../enums/stacking-group-write-mode.js';
 import '../enums/stock-movement-type.js';
 import '../enums/store-asset-request-visibility.js';
 import '../enums/submit-item-type.js';
 import '../enums/submit-result-outcome.js';
+import '../enums/tag-manager-container-check-reason.js';
+import '../enums/tag-manager-marketing-tag-kind.js';
+import '../enums/tag-manager-marketing-tag-load.js';
+import '../enums/tag-manager-marketing-tag-input-kind.js';
+import '../enums/tag-manager-marketing-tag-input-load.js';
+import '../enums/tag-manager-trigger-kind.js';
+import '../enums/tag-manager-trigger-input-kind.js';
+import '../enums/tag-manager-variable-kind.js';
+import '../enums/tag-manager-variable-input-kind.js';
 import '../enums/validation-failed-response-status.js';
+import '../enums/vendor-legal-basis-override.js';
+import '../enums/vendor-create-request-legal-basis-override.js';
+import '../enums/vendor-update-request-legal-basis-override.js';
 import '../enums/vocabulary-default-tone.js';
 import '../enums/vocabulary-source.js';
 import '../enums/vocabulary-tone.js';
+import '../enums/voucher-status.js';
+import '../enums/voucher-batch-status.js';
+import '../enums/voucher-batch-patch-status.js';
+import '../enums/voucher-batch-write-status.js';
+import '../enums/voucher-patch-status.js';
+import '../enums/voucher-write-status.js';
 import '../enums/attribute-boolean-status.js';
 import '../enums/attribute-datetime-status.js';
 import '../enums/attribute-email-status.js';
@@ -246,13 +386,14 @@ 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.
+     * 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. On a buyer's own call the list holds that buyer's payments only, and a `contact_id` naming anyone else answers 400 `buyer_mismatch`.
      *
      * @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 {string} params.orderId - The order a payment is for, as the orders app knows it. Indexed — this is how an order finds what has been paid against it.
      * @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.
@@ -260,6 +401,8 @@ declare class PaymentsLedger {
      * @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.
+     * @param {string} params.externalId - Exact key of the system that booked the payment — the ERP's document number, not the provider's own transaction id. This is the reconciliation lookup. Not unique: a payment cannot be updated here, so several rows may legitimately carry one key, and this may answer more than one.
+     * @param {string} params.sourceSyncedAt - Exact instant a payment was last confirmed against its source. The index behind it is what makes a delta run cheap, and a delta run SORTS (`?order=source_synced_at.desc`) rather than naming one instant — `external_refs` and `source_data` carry no parameter at all, because such a column is compared as a whole document.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      */
@@ -269,6 +412,7 @@ declare class PaymentsLedger {
         order?: string;
         cartId?: string;
         contactId?: string;
+        orderId?: string;
         status?: PaymentStatus;
         orderRef?: string;
         methodCode?: string;
@@ -276,15 +420,18 @@ declare class PaymentsLedger {
         provider?: string;
         dunningStage?: PaymentDunningStage;
         idempotencyKey?: string;
+        externalId?: string;
+        sourceSyncedAt?: 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.
+     * 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. On a buyer's own call the list holds that buyer's payments only, and a `contact_id` naming anyone else answers 400 `buyer_mismatch`.
      *
      * @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 {string} orderId - The order a payment is for, as the orders app knows it. Indexed — this is how an order finds what has been paid against it.
      * @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.
@@ -292,13 +439,15 @@ declare class PaymentsLedger {
      * @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.
+     * @param {string} externalId - Exact key of the system that booked the payment — the ERP's document number, not the provider's own transaction id. This is the reconciliation lookup. Not unique: a payment cannot be updated here, so several rows may legitimately carry one key, and this may answer more than one.
+     * @param {string} sourceSyncedAt - Exact instant a payment was last confirmed against its source. The index behind it is what makes a delta run cheap, and a delta run SORTS (`?order=source_synced_at.desc`) rather than naming one instant — `external_refs` and `source_data` carry no parameter at all, because such a column is compared as a whole document.
      * @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<{}>;
+    paymentsList(limit?: number, offset?: number, order?: string, cartId?: string, contactId?: string, orderId?: string, status?: PaymentStatus, orderRef?: string, methodCode?: string, kind?: PaymentMethodKind, provider?: string, dunningStage?: PaymentDunningStage, idempotencyKey?: string, externalId?: string, sourceSyncedAt?: 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.
+     * 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; the same key with another method, amount or currency is 409 `idempotency_key_reused`. On a buyer's own call — the gateway resolved a contact — only the checkout's routes answer (eligibility, creating and confirming a payment, the buyer's own payments, vocabularies, catalog, logos); every other route answers 403 `buyer_not_permitted`. 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.
@@ -306,10 +455,15 @@ declare class PaymentsLedger {
      * @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.externalId - The key this payment has in the system that BOOKED it — the ERP's own document number for the receipt. A different thing from `psp_payment_id`, which is the provider's own transaction id: one payment is known to two systems and this is the merchant's side of that pair, which is what makes a reconciliation run possible at all. Free text, nullable, and deliberately NOT unique — a payment cannot be updated here, so there is no upsert for a uniqueness rule to serve, and an import that must not book twice sends its key as `idempotency_key` too and gets the same payment back with 200. null for a payment a checkout made, which is the ordinary case.
+     * @param {object} params.externalRefs - Every OTHER system that knows this payment, keyed by system name — a second ERP, a bank statement reference, a dunning platform. `external_id` is the leading system and `psp_payment_id` is the provider's own; this is the rest. Free jsonb: the database constrains neither the keys nor the values. Not a query parameter — such a column is compared as a WHOLE document, so a filter over part of one is refused rather than answered.
      * @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.orderId - The order this payment is for, as the orders app knows it (its uuid). Optional. When it is sent, the payment is checked against the order before anything is written: its currency must be the order's (409 `currency_mismatch`), and together with every payment of the order that is created, requires_action, authorized or captured it must not exceed the order's `grand_total` (409 `amount_exceeds_order`) — several payments per order are fine. A `cancelled` order takes no payment (409 `order_not_payable`); every other order status passes. An order that does not exist is 400 `unknown_order`; an orders app that cannot be asked is 502 `orders_unavailable` and nothing is created. On a buyer's own call the order must be the buyer's (400 `buyer_mismatch`). Left out, the payment is accepted unchecked, as before 1.0 — a purchase under approval has no order yet.
      * @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.
+     * @param {object} params.sourceData - What the source said about this payment, kept as it said it. `system` names it, `etag` is the token an `If-Match` write-back has to hand back — there is nowhere else to keep it between two runs — and `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost. Free jsonb; nothing here is read by this app.
+     * @param {string} params.sourceSyncedAt - When this payment was last confirmed against the system that booked it. What a delta run asks for changes since, and what tells an operator a feed has gone quiet — a capture or a refund does not touch it, because it says when the SOURCE was last seen and not when the row moved. Indexed, and null for a payment no source owns.
      * @throws {RevenexxException}
      * @returns {Promise<Models.Payment>}
      */
@@ -320,13 +474,18 @@ declare class PaymentsLedger {
         contactId?: string;
         country?: string;
         currency?: string;
+        externalId?: string;
+        externalRefs?: object;
         idempotencyKey?: string;
         metadata?: object;
+        orderId?: string;
         orderRef?: string;
         returnUrl?: string;
+        sourceData?: object;
+        sourceSyncedAt?: 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.
+     * 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; the same key with another method, amount or currency is 409 `idempotency_key_reused`. On a buyer's own call — the gateway resolved a contact — only the checkout's routes answer (eligibility, creating and confirming a payment, the buyer's own payments, vocabularies, catalog, logos); every other route answers 403 `buyer_not_permitted`. 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.
@@ -334,15 +493,20 @@ declare class PaymentsLedger {
      * @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} externalId - The key this payment has in the system that BOOKED it — the ERP's own document number for the receipt. A different thing from `psp_payment_id`, which is the provider's own transaction id: one payment is known to two systems and this is the merchant's side of that pair, which is what makes a reconciliation run possible at all. Free text, nullable, and deliberately NOT unique — a payment cannot be updated here, so there is no upsert for a uniqueness rule to serve, and an import that must not book twice sends its key as `idempotency_key` too and gets the same payment back with 200. null for a payment a checkout made, which is the ordinary case.
+     * @param {object} externalRefs - Every OTHER system that knows this payment, keyed by system name — a second ERP, a bank statement reference, a dunning platform. `external_id` is the leading system and `psp_payment_id` is the provider's own; this is the rest. Free jsonb: the database constrains neither the keys nor the values. Not a query parameter — such a column is compared as a WHOLE document, so a filter over part of one is refused rather than answered.
      * @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} orderId - The order this payment is for, as the orders app knows it (its uuid). Optional. When it is sent, the payment is checked against the order before anything is written: its currency must be the order's (409 `currency_mismatch`), and together with every payment of the order that is created, requires_action, authorized or captured it must not exceed the order's `grand_total` (409 `amount_exceeds_order`) — several payments per order are fine. A `cancelled` order takes no payment (409 `order_not_payable`); every other order status passes. An order that does not exist is 400 `unknown_order`; an orders app that cannot be asked is 502 `orders_unavailable` and nothing is created. On a buyer's own call the order must be the buyer's (400 `buyer_mismatch`). Left out, the payment is accepted unchecked, as before 1.0 — a purchase under approval has no order yet.
      * @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.
+     * @param {object} sourceData - What the source said about this payment, kept as it said it. `system` names it, `etag` is the token an `If-Match` write-back has to hand back — there is nowhere else to keep it between two runs — and `raw` holds the source fields this app does not model, so they survive a round trip instead of being lost. Free jsonb; nothing here is read by this app.
+     * @param {string} sourceSyncedAt - When this payment was last confirmed against the system that booked it. What a delta run asks for changes since, and what tells an operator a feed has gone quiet — a capture or a refund does not touch it, because it says when the SOURCE was last seen and not when the row moved. Indexed, and null for a payment no source owns.
      * @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>;
+    paymentsCreate(amount: number, methodCode: string, cartId?: string, contactId?: string, country?: string, currency?: string, externalId?: string, externalRefs?: object, idempotencyKey?: string, metadata?: object, orderId?: string, orderRef?: string, returnUrl?: string, sourceData?: object, sourceSyncedAt?: 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.
      *
@@ -423,7 +587,7 @@ declare class PaymentsLedger {
      * @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.
+     * @param {any} params.verified - Whether the ingress verified the callback signature against the provider's `webhook_secret`. Only `true` is applied; false, missing or anything else is refused with 422: an endpoint may run in annotate mode, and the ledger stays sovereign over one that does.
      * @throws {RevenexxException}
      * @returns {Promise<{}>}
      */
@@ -439,14 +603,14 @@ declare class PaymentsLedger {
      * @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.
+     * @param {any} verified - Whether the ingress verified the callback signature against the provider's `webhook_secret`. Only `true` is applied; false, missing or anything else 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.
+     * 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. On a buyer's own call a payment of another contact answers 404.
      *
      * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
      * @throws {RevenexxException}
@@ -456,7 +620,7 @@ declare class PaymentsLedger {
         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.
+     * 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. On a buyer's own call a payment of another contact answers 404.
      *
      * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
      * @throws {RevenexxException}
@@ -506,7 +670,7 @@ declare class PaymentsLedger {
      */
     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.
+     * 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. On a buyer's own call a payment of another contact answers 404.
      *
      * @param {string} params.id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
      * @throws {RevenexxException}
@@ -516,7 +680,7 @@ declare class PaymentsLedger {
         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.
+     * 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. On a buyer's own call a payment of another contact answers 404.
      *
      * @param {string} id - The payment. A uuid — the data plane casts this segment and answers 400, not 404, for anything else.
      * @throws {RevenexxException}

package/dist/services/payments-ledger.js

@@ -17,13 +17,16 @@ class PaymentsLedger {
         order: rest[1],
         cartId: rest[2],
         contactId: rest[3],
-        status: rest[4],
-        orderRef: rest[5],
-        methodCode: rest[6],
-        kind: rest[7],
-        provider: rest[8],
-        dunningStage: rest[9],
-        idempotencyKey: rest[10]
+        orderId: rest[4],
+        status: rest[5],
+        orderRef: rest[6],
+        methodCode: rest[7],
+        kind: rest[8],
+        provider: rest[9],
+        dunningStage: rest[10],
+        idempotencyKey: rest[11],
+        externalId: rest[12],
+        sourceSyncedAt: rest[13]
       };
     }
     const limit = params.limit;
@@ -31,6 +34,7 @@ class PaymentsLedger {
     const order = params.order;
     const cartId = params.cartId;
     const contactId = params.contactId;
+    const orderId = params.orderId;
     const status = params.status;
     const orderRef = params.orderRef;
     const methodCode = params.methodCode;
@@ -38,6 +42,8 @@ class PaymentsLedger {
     const provider = params.provider;
     const dunningStage = params.dunningStage;
     const idempotencyKey = params.idempotencyKey;
+    const externalId = params.externalId;
+    const sourceSyncedAt = params.sourceSyncedAt;
     const apiPath = "/v1/payments";
     const apiPayload = {};
     if (typeof limit !== "undefined") {
@@ -55,6 +61,9 @@ class PaymentsLedger {
     if (typeof contactId !== "undefined") {
       apiPayload["contact_id"] = contactId;
     }
+    if (typeof orderId !== "undefined") {
+      apiPayload["order_id"] = orderId;
+    }
     if (typeof status !== "undefined") {
       apiPayload["status"] = status;
     }
@@ -76,6 +85,12 @@ class PaymentsLedger {
     if (typeof idempotencyKey !== "undefined") {
       apiPayload["idempotency_key"] = idempotencyKey;
     }
+    if (typeof externalId !== "undefined") {
+      apiPayload["external_id"] = externalId;
+    }
+    if (typeof sourceSyncedAt !== "undefined") {
+      apiPayload["source_synced_at"] = sourceSyncedAt;
+    }
     const uri = new URL(this.client.config.endpoint + apiPath);
     const apiHeaders = {};
     return this.client.call(
@@ -97,10 +112,15 @@ class PaymentsLedger {
         contactId: rest[2],
         country: rest[3],
         currency: rest[4],
-        idempotencyKey: rest[5],
-        metadata: rest[6],
-        orderRef: rest[7],
-        returnUrl: rest[8]
+        externalId: rest[5],
+        externalRefs: rest[6],
+        idempotencyKey: rest[7],
+        metadata: rest[8],
+        orderId: rest[9],
+        orderRef: rest[10],
+        returnUrl: rest[11],
+        sourceData: rest[12],
+        sourceSyncedAt: rest[13]
       };
     }
     const amount = params.amount;
@@ -109,10 +129,15 @@ class PaymentsLedger {
     const contactId = params.contactId;
     const country = params.country;
     const currency = params.currency;
+    const externalId = params.externalId;
+    const externalRefs = params.externalRefs;
     const idempotencyKey = params.idempotencyKey;
     const metadata = params.metadata;
+    const orderId = params.orderId;
     const orderRef = params.orderRef;
     const returnUrl = params.returnUrl;
+    const sourceData = params.sourceData;
+    const sourceSyncedAt = params.sourceSyncedAt;
     if (typeof amount === "undefined") {
       throw new client.RevenexxException('Missing required parameter: "amount"');
     }
@@ -136,6 +161,12 @@ class PaymentsLedger {
     if (typeof currency !== "undefined") {
       apiPayload["currency"] = currency;
     }
+    if (typeof externalId !== "undefined") {
+      apiPayload["external_id"] = externalId;
+    }
+    if (typeof externalRefs !== "undefined") {
+      apiPayload["external_refs"] = externalRefs;
+    }
     if (typeof idempotencyKey !== "undefined") {
       apiPayload["idempotency_key"] = idempotencyKey;
     }
@@ -145,12 +176,21 @@ class PaymentsLedger {
     if (typeof methodCode !== "undefined") {
       apiPayload["method_code"] = methodCode;
     }
+    if (typeof orderId !== "undefined") {
+      apiPayload["order_id"] = orderId;
+    }
     if (typeof orderRef !== "undefined") {
       apiPayload["order_ref"] = orderRef;
     }
     if (typeof returnUrl !== "undefined") {
       apiPayload["return_url"] = returnUrl;
     }
+    if (typeof sourceData !== "undefined") {
+      apiPayload["source_data"] = sourceData;
+    }
+    if (typeof sourceSyncedAt !== "undefined") {
+      apiPayload["source_synced_at"] = sourceSyncedAt;
+    }
     const uri = new URL(this.client.config.endpoint + apiPath);
     const apiHeaders = {
       "content-type": "application/json"