@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/payments/index.d.ts

@@ -1,8 +1,12 @@
-import type { Transport } from '@sixtyninecommerce/core';
+import { type Transport } from '@sixtyninecommerce/core';
+import type { InvoiceCorrectionLedger } from '../documents/index.js';
 import type { Call } from '../types.js';
 import { type AccountCreditModule } from './account-credit.js';
+import { type ArPaymentsModule } from './ar.js';
 import { type PaymentMethodsModule } from './methods.js';
+import { type PaymentLinksModule } from './payment-links.js';
 import { type ProvidersModule } from './providers.js';
+import { type PaymentRequestsModule } from './requests.js';
 /**
  * What an order has actually been paid, in minor units of its own currency.
  *
@@ -10,7 +14,11 @@ import { type ProvidersModule } from './providers.js';
  * is a second source of truth that drifts the first time a refund lands.
  */
 export interface OrderPaymentPosition {
-    /** The order's own gross total, carrying the order's rounding rule. */
+    /**
+     * The order's own gross total, carrying the order's rounding rule. 0 for a `Cancelled` order:
+     * a cancelled order bills nothing. A credit note does not change it: see `creditNoted` and
+     * `owed`.
+     */
     total: number;
     /** Settled plus authorized, less refunds: what is accounted for. */
     covered: number;
@@ -24,13 +32,38 @@ export interface OrderPaymentPosition {
      * counted here, though it is taken off `settled` like one.
      */
     refunded: number;
-    /** `total - covered`, floored at zero. */
+    /**
+     * What the order's credit notes took off what it bills: `total` less what its invoices bill net
+     * of their credit notes (a part credited, an invoice voided with no replacement), never more
+     * than `total`; 0 for an order with no invoice. A correction never restates the order, so
+     * `total` keeps reading what it first billed. Taken off `owed` only.
+     *
+     * Read by {@link PaymentsModule.position}, `orders.paymentPosition` and the cancel-with-money
+     * preview and answer. Against an engine that does not serve it those calls resend their document
+     * without it (`creditNotedAware`), so it is absent and reads as zero; absent from a settlement's
+     * position too.
+     */
+    creditNoted?: number;
+    /**
+     * What the customer still owes once the credit notes are counted: `total - creditNoted -
+     * covered`, floored at zero. A refund that went back with a credit note is owed by nobody.
+     * Equals `outstanding` when nothing was credited. Read by the same calls as `creditNoted`; where
+     * it is absent, the customer owes `outstanding`.
+     */
+    owed?: number;
+    /**
+     * `total - covered`, floored at zero: what the payments are short of the order's total, and
+     * what `record` caps a payment at. On an order whose credit notes took part of its bill off,
+     * `owed` is what the customer still owes.
+     */
     outstanding: number;
     /**
      * `covered - total`, floored at zero. Over-payment is refused at the door, so
      * this is non-zero only for imported history, rows predating the guard, a
-     * refund that landed after a second payment, or an edit that lowered the
-     * total of a paid order. Money moved to the customer's account
+     * refund that landed after a second payment, an edit that lowered the
+     * total of a paid order, or money kept on a cancelled order (a cancelled
+     * order bills nothing; `orders.cancelWithMoney` with `retain`), which can
+     * still be credited to the account. Money moved to the customer's account
      * (`payments.accountCredit.creditOverpayment`) no longer counts here.
      */
     overpaid: number;
@@ -81,7 +114,10 @@ export interface RefundablePayment {
     /**
      * `amount - refunded`, less what of this payment is on the customer's account
      * (`payments.accountCredit.onOrder`), when this payment took money; floored
-     * at zero, else zero.
+     * at zero, else zero. Less, too, this payment's share of what the gift cards
+     * sold on the order hold: a live card's value, and a voided card's spent (or
+     * expired) value, which stays held for good. How much, and on which payment:
+     * {@link PaymentsModule.refundGiftCardHold}.
      */
     refundable: number;
     /**
@@ -118,11 +154,43 @@ export interface OrderRefundPosition {
      * Money moved to the customer's account as unapplied cash IS deducted: it is
      * paid back from the account (`payments.accountCredit.refund`), never from
      * the order a second time.
+     *
+     * What the gift cards sold on the order hold is deducted too: a live card's
+     * value, and a voided card's spent (or expired) value, which stays held for
+     * good. A refund of it is refused `REFUND_HELD_BY_GIFT_CARD`;
+     * {@link PaymentsModule.refundGiftCardHold} says how much, and on which payment.
      */
     refundable: number;
     /** Every payment on the order, NEWEST FIRST, with its own headroom. */
     perPayment: RefundablePayment[];
 }
+/**
+ * What the gift cards sold on an order hold of its money: why its refund position's `refundable`
+ * is lower than what its payments took ({@link PaymentsModule.refundGiftCardHold}).
+ */
+export interface RefundGiftCardHold {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /**
+     * What the cards hold: each card its face value less what a void released, and a void releases
+     * at most what the card had not spent, so a card's spent (or expired) value stays held for good.
+     * Already counted out of `refundable`, so `refundable` plus this is what the payments would hand
+     * back with no card. A refund of it is refused `REFUND_HELD_BY_GIFT_CARD`. 0 when no card holds
+     * any.
+     */
+    giftCardHold: number;
+    /**
+     * How many of the cards sold on the order are still live (not voided); null while
+     * `giftCardHold` is 0. Above 0, voiding a card releases what it has not spent; 0 means every
+     * card is voided, and what they hold is spent value that stays with the store.
+     */
+    liveGiftCards: number | null;
+    /** Each payment's share of the hold, NEWEST FIRST, as `refundPosition` lists them. */
+    perPayment: Array<{
+        paymentId: string;
+        giftCardHold: number;
+    }>;
+}
 /**
  * A refund whose outcome is unknown: it reached its payment provider and was
  * never confirmed (a timeout, a dropped connection, a server error), so the
@@ -139,6 +207,30 @@ export interface UnreconciledRefund {
     /** ISO-8601 with offset. */
     createdAt: string | null;
 }
+/**
+ * The invoice a refund of an order must go through, so a credit note says what the money was for
+ * (see {@link PaymentsModule.refundCreditNoteRequirement}).
+ */
+export interface RefundCreditNoteRequirement {
+    /** The live invoice billing the order: plan and commit the correction on it. */
+    invoiceId: string;
+    /** As printed on the invoice. */
+    invoiceNumber: string;
+    /**
+     * The ledger to plan the correction on (`documents.planCorrection({ ledger, invoiceId })`).
+     * `RETAIL` is named first when the order has both: its correction can carry the refund.
+     */
+    ledger: InvoiceCorrectionLedger;
+    /**
+     * Minor units of the order's currency: what its payments hold over what it bills (a duplicate
+     * payment, say), net of every refund. "What it bills" is the larger of the order's total and
+     * what its live invoices bill. {@link PaymentsModule.refund} gives back up to this much
+     * without a credit note, recorded as an overpayment refund (the invoice never billed it); a
+     * larger refund goes through the correction. `0` when the order is not overpaid. Only payments
+     * that took money count, and a refund of unknown outcome stays reserved.
+     */
+    refundableOverpayment: number;
+}
 /** What the payment provider says happened to a refund whose outcome was unknown. */
 export type RefundProviderOutcome = 'MADE' | 'NOT_MADE';
 /** The provider's answer for a refund whose outcome is unknown. */
@@ -202,6 +294,18 @@ export interface PaidOrder {
     total: number;
     totalWithTax: number;
 }
+/** A payment, as {@link PaymentsModule.settle} and {@link PaymentsModule.cancel} answer it. */
+export interface OrderPaymentRecord {
+    id: string;
+    /** Vendure's payment state: `Settled` after a capture, `Cancelled` after a void. */
+    state: string;
+    /** The payment method code. */
+    method: string;
+    /** Minor units of the order's currency. */
+    amount: number;
+    /** The provider's reference for the payment, when it gave one. */
+    transactionId: string | null;
+}
 /** What a payment app reports happened to a payment it took (`reportAppPayment`). */
 export type AppPaymentReportState = 'Authorized' | 'Settled' | 'Declined' | 'Cancelled';
 /** An app's report on one of its payments. */
@@ -285,11 +389,27 @@ export interface PaymentsModule {
      * to an invoice, pay it back.
      */
     accountCredit: AccountCreditModule;
+    /**
+     * Money on the accounts-receivable ledger: customer payments against AR invoices, the ledger,
+     * prepaid drawdowns and SEPA direct debit collection.
+     */
+    ar: ArPaymentsModule;
     /**
      * The store's payment methods, as staff choose one: the `method` code
      * {@link PaymentsModule.record} takes, and the codes a deposit policy names.
      */
     methods: PaymentMethodsModule;
+    /**
+     * Hosted payment requests: ask the customer to pay a chosen amount of a held
+     * order or a committed draft through a stable link that opens the payment
+     * provider's checkout. See {@link PaymentRequestsModule}.
+     */
+    requests: PaymentRequestsModule;
+    /**
+     * The store's payment links (Tikkie): the connection's settings and checks, and the links an
+     * order was sent by invoice e-mail. See {@link PaymentLinksModule}.
+     */
+    paymentLinks: PaymentLinksModule;
     /**
      * Record part (or all) of what an order owes, and return the order.
      *
@@ -303,9 +423,16 @@ export interface PaymentsModule {
      * store that has not turned deposits on; paying the whole outstanding balance
      * is not a deposit and always works — `METADATA_KEY_RESERVED`,
      * `PAYMENT_METHOD_NOT_FOUND`, `ORDER_NOT_FOUND`.
+     *
+     * @effect money
      */
     record(orderId: string, input: RecordPaymentInput, options?: Call): Promise<PaidOrder>;
-    /** Read an order's payment position. */
+    /**
+     * Read an order's payment position: what it bills, what was paid and refunded, what its credit
+     * notes took off (`creditNoted`) and what the customer still owes after them (`owed`).
+     *
+     * @effect read
+     */
     position(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
     /**
      * Hand money back to a customer, never more than the order took.
@@ -379,10 +506,118 @@ export interface PaymentsModule {
      * order has been read carries that order's position in
      * `extensions.refundPosition`, so a till can correct itself without a second
      * round trip.
+     *
+     * **An invoiced order is refunded through its invoice, not here.** While the
+     * order has a live invoice, this refuses `REFUND_REQUIRES_CREDIT_NOTE` (a
+     * `ConflictError`, 409) before anything else: a refund made here issues no
+     * document, and the invoice would stand with no credit note for the money.
+     * Ask {@link refundCreditNoteRequirement} first; it names the invoice, and
+     * `documents.commitCorrection` on it issues the credit note and then refunds.
+     * Not refused: an amount within the order's overpayment
+     * (`refundableOverpayment`, money the invoice never billed), refunded here
+     * and recorded as an overpayment refund; and a customer with a credit
+     * account on a store that keeps the accounts-receivable ledger, whose refund
+     * is documented when it settles: by an AR credit note for what an invoice
+     * billed, and by none for money no invoice billed (a duplicate payment given
+     * back), which is recorded as an overpayment refund. The refusal's `details`
+     * name the invoice and the overpayment still refundable. Needs an engine that knows
+     * the rule (vendure-server deployed first); an older one refunds as before.
+     *
+     * @effect money
      */
     refund(input: RefundPaymentInput, options?: Call): Promise<IssuedRefund>;
+    /**
+     * Capture an authorized payment at its provider ("mark as paid"), and return the payment.
+     *
+     * At most once per payment, whoever asks and however often: the engine keys every capture of a
+     * payment under ONE key of its own (`payment:<id>:capture`), so this method takes no
+     * `idempotencyKey`. A repeat while the payment is `Settled` captures nothing and is refused
+     * `PAYMENT_STATE_TRANSITION_ERROR` ("already settled"); a repeat while the first capture is
+     * still running is refused `IDEMPOTENCY_IN_PROGRESS`. A capture whose answer was lost after it
+     * reached the provider is refused `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`) on
+     * that call and on every capture for the key's retention (24 hours): check the payment with the
+     * provider before doing anything else with it, and never retry this blind. Once the key is
+     * swept a capture asks the provider again, so an automatic retry after a day can capture a
+     * second time; the provider's own report (`reportAppPayment`) still settles it meanwhile.
+     *
+     * Refusals, as coded errors (the Admin API answers some as a result union; this method throws
+     * every one):
+     * - `PAYMENT_SETTLE_DECLINED` (`BusinessRuleError`, 422): the provider declined the capture.
+     *   The message is the provider's reason. Nothing was captured, and a later capture may be
+     *   tried.
+     * - `PAYMENT_STATE_TRANSITION_ERROR` (422): the payment is not `Authorized` (settled, cancelled
+     *   or declined already). The message says which.
+     * - `ORDER_STATE_TRANSITION_ERROR` (422): the capture went through the provider's gate but the
+     *   order could not move on as it stands.
+     * - `ORDER_CANCELLED_PAYMENT_CONFLICT` (409): the payment's order is cancelled, and a cancelled
+     *   order is never paid. Cancel the payment instead to release it.
+     * - `PAYMENT_SETTLE_CONFLICT` (409): the payment moved while it was being captured. Read it
+     *   again.
+     * - `ENTITY_NOT_FOUND` (404): no payment of an order of this store has that id.
+     *
+     * Needs `UpdateOrder`.
+     *
+     * @effect money
+     */
+    settle(paymentId: string, options?: Call): Promise<OrderPaymentRecord>;
+    /**
+     * Void an authorized payment (release the hold), and return the payment.
+     *
+     * A cancel takes turns with the payment's capture: one that reaches a payment that is no
+     * longer authorized, or one whose capture may have reached its provider with no answer, is
+     * refused `PAYMENT_CANCEL_CONFLICT` (409) and nothing is asked of the provider. A `Settled`
+     * payment is never voided: its money was taken, so it is refunded ({@link refund}).
+     *
+     * Other refusals, as coded errors:
+     * - `PAYMENT_CANCEL_DECLINED` (`BusinessRuleError`, 422): the provider refused the void. The
+     *   message is the provider's reason; the hold may still stand at the provider.
+     * - `PAYMENT_STATE_TRANSITION_ERROR` (422): the payment cannot move to `Cancelled` from where
+     *   it is.
+     * - `ENTITY_NOT_FOUND` (404): no payment of an order of this store has that id.
+     *
+     * Needs `UpdateOrder`.
+     *
+     * @effect money
+     */
+    cancel(paymentId: string, options?: Call): Promise<OrderPaymentRecord>;
+    /**
+     * Whether {@link refund} (and core's `refundOrder`, and the till's refund) is
+     * refused for this order with `REFUND_REQUIRES_CREDIT_NOTE`, and which invoice
+     * the refund goes through instead; `null` when a plain refund may go ahead.
+     *
+     * The order has a live invoice in this store, so a refund needs a credit note
+     * saying what it is for, beyond `refundableOverpayment` (what the order was
+     * paid over what it bills, which {@link refund} still gives back). Plan the
+     * correction with
+     * `documents.planCorrection({ ledger, invoiceId, outcome, refundPaymentId })` and
+     * issue it with `documents.commitCorrection`: the credit note is issued, then
+     * the money refunded. `null` for an order with no live invoice, and for a
+     * customer with a credit account on a store that keeps the
+     * accounts-receivable ledger (their refunds are documented when they settle:
+     * by an AR credit note, except the part no invoice billed, which gets none).
+     * Needs `ReadOrder`.
+     *
+     * Its own query rather than a field of {@link refundPosition}, so a release of
+     * this SDK reading an older engine fails only this call. The answer is read
+     * without a lock: the refund doors judge again when they run.
+     *
+     * @effect read
+     */
+    refundCreditNoteRequirement(orderId: string, options?: Call): Promise<RefundCreditNoteRequirement | null>;
     /** Read what an order may still hand back. */
     refundPosition(orderId: string, options?: Call): Promise<OrderRefundPosition>;
+    /**
+     * What the gift cards sold on an order hold of its money, on the order and per payment, and
+     * how many of them are still live: why {@link refundPosition}'s `refundable` is lower than the
+     * money taken. Needs `ReadOrder`.
+     *
+     * Its own query rather than fields of {@link refundPosition}, so a release of this SDK reading
+     * an older engine fails only this call. Needs an engine that serves
+     * `OrderRefundPosition.giftCardHold`.
+     *
+     * @effect read
+     */
+    refundGiftCardHold(orderId: string, options?: Call): Promise<RefundGiftCardHold>;
     /**
      * The order's refunds whose outcome is unknown, oldest first — the ones
      * {@link reconcileRefund} resolves. Each one's amount is already reserved in
@@ -418,6 +653,8 @@ export interface PaymentsModule {
      *
      * `options.idempotencyKey` is honoured: a repeat under the same key returns
      * the first call's refund.
+     *
+     * @effect money
      */
     reconcileRefund(input: ReconcileRefundInput, options?: Call): Promise<IssuedRefund>;
     /**
@@ -463,14 +700,23 @@ export interface PaymentsModule {
     appPayments(orderId: string, options?: Call): Promise<AppPayment[]>;
 }
 export declare const RECORD_ORDER_PAYMENT_MUTATION = "\n  mutation RecordOrderPayment($orderId: ID!, $input: RecordPaymentInput!, $idempotencyKey: String) {\n    recordOrderPayment(orderId: $orderId, input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  code\n  state\n  currencyCode\n  total\n  totalWithTax\n\n    }\n  }\n";
-export declare const ORDER_PAYMENT_POSITION_QUERY = "\n  query OrderPaymentPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      \n  total\n  covered\n  settled\n  authorized\n  refunded\n  outstanding\n  overpaid\n  availableToCharge\n\n    }\n  }\n";
+export declare const ORDER_PAYMENT_POSITION_QUERY = "\n  query OrderPaymentPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      \n  total\n  covered\n  settled\n  authorized\n  refunded\n  creditNoted\n  owed\n  outstanding\n  overpaid\n  availableToCharge\n\n    }\n  }\n";
 export declare const ORDER_REFUND_POSITION_QUERY = "\n  query OrderRefundPosition($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      \n  currencyCode\n  refunded\n  refundable\n  perPayment {\n    paymentId\n    state\n    method\n    amount\n    refunded\n    refundable\n    tookMoney\n  }\n\n    }\n  }\n";
 export declare const REFUND_ORDER_PAYMENT_MUTATION = "\n  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {\n    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
 export declare const UNRECONCILED_REFUNDS_QUERY = "\n  query UnreconciledRefunds($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      unreconciled {\n        refundId\n        paymentId\n        amount\n        createdAt\n      }\n    }\n  }\n";
+export declare const REFUND_GIFT_CARD_HOLD_QUERY = "\n  query RefundGiftCardHold($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      currencyCode\n      giftCardHold\n      liveGiftCards\n      perPayment {\n        paymentId\n        giftCardHold\n      }\n    }\n  }\n";
+export declare const REFUND_CREDIT_NOTE_REQUIREMENT_QUERY = "\n  query RefundCreditNoteRequirement($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      creditNoteRequired {\n        invoiceId\n        invoiceNumber\n        ledger\n        refundableOverpayment\n      }\n    }\n  }\n";
 export declare const RECONCILE_REFUND_OUTCOME_MUTATION = "\n  mutation ReconcileRefundOutcome($input: ReconcileRefundOutcomeInput!, $idempotencyKey: String) {\n    reconcileRefundOutcome(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
+export declare const SETTLE_PAYMENT_MUTATION = "\n  mutation SettlePayment($id: ID!) {\n    settlePayment(id: $id) {\n      __typename\n      ... on Payment {\n        \n  id\n  state\n  method\n  amount\n  transactionId\n\n      }\n      ... on SettlePaymentError {\n        paymentErrorMessage\n      }\n      ... on PaymentStateTransitionError {\n        transitionError\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const CANCEL_PAYMENT_MUTATION = "\n  mutation CancelPayment($id: ID!) {\n    cancelPayment(id: $id) {\n      __typename\n      ... on Payment {\n        \n  id\n  state\n  method\n  amount\n  transactionId\n\n      }\n      ... on CancelPaymentError {\n        paymentErrorMessage\n      }\n      ... on PaymentStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
 export declare const REPORT_APP_PAYMENT_MUTATION = "\n  mutation ReportAppPayment(\n    $paymentId: ID!\n    $input: ReportAppPaymentInput!\n    $idempotencyKey: String!\n  ) {\n    reportAppPayment(paymentId: $paymentId, input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      state\n      amount\n      method\n      transactionId\n    }\n  }\n";
 export declare const APP_PAYMENTS_QUERY = "\n  query AppPayments($orderId: ID!) {\n    appPayments(orderId: $orderId) {\n      id\n      orderId\n      orderCode\n      state\n      amount\n      currencyCode\n      providerReference\n      methodCode\n      outcomeUnknown\n      createdAt\n    }\n  }\n";
 export declare function createPaymentsModule(transport: Transport): PaymentsModule;
-export type { AccountCreditModule, ApplyUnappliedCashInput, CreditOverpaymentInput, OrderMoneyOnAccount, RefundUnappliedCashInput, UnappliedCash, UnappliedCashRefund, } from './account-credit.js';
-export type { PaymentMethod, PaymentMethodsModule } from './methods.js';
-export type { ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, } from './providers.js';
+export type { AccountCreditModule, ApplyUnappliedCashInput, CreditOverpaymentInput, OrderMoneyOnAccount, RefundUnappliedCashInput, StoreCreditMove, UnappliedCash, UnappliedCashRefund, } from './account-credit.js';
+export type { ConnectedAccountModule, StripeConnectedAccount, } from './connected-account.js';
+export type { CreatePaymentMethodInput, PaymentMethod, PaymentMethodCredential, PaymentMethodCredentialPath, PaymentMethodsModule, PaymentMethodTranslation, PaymentMethodTranslationInput, UpdatePaymentMethodInput, } from './methods.js';
+export type { MollieDiagnosis, MollieDiagnosisMethod, MollieDiagnosisVerdict, MollieDirectDebitDiagnosis, MollieMethod, MollieMethodList, MollieMethodsModule, MollieProbeError, MollieProbeErrorKind, SetMollieMethodsInput, } from './mollie-methods.js';
+export type { PaymentProviderKey, ProviderKeyProvider, ProviderKeysModule, ProviderKeyTest, SetProviderKeyInput, } from './provider-keys.js';
+export type { PaymentProviderAccount, ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, } from './providers.js';
+export type { CreatePaymentRequestInput, PaymentRequest, PaymentRequestCloseReason, PaymentRequestStatus, PaymentRequestsModule, } from './requests.js';
+export { PAYMENT_REQUEST_CLOSE_REASONS, PAYMENT_REQUEST_DEFAULT_EXPIRY_DAYS, PAYMENT_REQUEST_MAX_EXPIRY_DAYS, PAYMENT_REQUEST_STATUSES, } from './requests.js';

package/dist/payments/index.js

@@ -1,6 +1,11 @@
+import { BusinessRuleError, errorFromErrorResult, isErrorResult, } from '@sixtyninecommerce/core';
 import { createAccountCreditModule } from './account-credit.js';
+import { createArPaymentsModule } from './ar.js';
+import { creditNotedAware } from './credit-noted-fields.js';
 import { createPaymentMethodsModule } from './methods.js';
+import { createPaymentLinksModule } from './payment-links.js';
 import { createProvidersModule } from './providers.js';
+import { createPaymentRequestsModule } from './requests.js';
 const PAID_ORDER_FIELDS = /* GraphQL */ `
   id
   code
@@ -15,6 +20,8 @@ const POSITION_FIELDS = /* GraphQL */ `
   settled
   authorized
   refunded
+  creditNoted
+  owed
   outstanding
   overpaid
   availableToCharge
@@ -78,6 +85,31 @@ export const UNRECONCILED_REFUNDS_QUERY = /* GraphQL */ `
     }
   }
 `;
+export const REFUND_GIFT_CARD_HOLD_QUERY = /* GraphQL */ `
+  query RefundGiftCardHold($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      currencyCode
+      giftCardHold
+      liveGiftCards
+      perPayment {
+        paymentId
+        giftCardHold
+      }
+    }
+  }
+`;
+export const REFUND_CREDIT_NOTE_REQUIREMENT_QUERY = /* GraphQL */ `
+  query RefundCreditNoteRequirement($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      creditNoteRequired {
+        invoiceId
+        invoiceNumber
+        ledger
+        refundableOverpayment
+      }
+    }
+  }
+`;
 export const RECONCILE_REFUND_OUTCOME_MUTATION = /* GraphQL */ `
   mutation ReconcileRefundOutcome($input: ReconcileRefundOutcomeInput!, $idempotencyKey: String) {
     reconcileRefundOutcome(input: $input, idempotencyKey: $idempotencyKey) {
@@ -90,6 +122,81 @@ export const RECONCILE_REFUND_OUTCOME_MUTATION = /* GraphQL */ `
     }
   }
 `;
+const PAYMENT_RECORD_FIELDS = /* GraphQL */ `
+  id
+  state
+  method
+  amount
+  transactionId
+`;
+// The concrete members are selected for their sentences: the `ErrorResult` interface carries
+// only a generic per-code `message`, and the provider's reason and the refusing gate's live on
+// the concrete type alone.
+export const SETTLE_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation SettlePayment($id: ID!) {
+    settlePayment(id: $id) {
+      __typename
+      ... on Payment {
+        ${PAYMENT_RECORD_FIELDS}
+      }
+      ... on SettlePaymentError {
+        paymentErrorMessage
+      }
+      ... on PaymentStateTransitionError {
+        transitionError
+      }
+      ... on OrderStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+export const CANCEL_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation CancelPayment($id: ID!) {
+    cancelPayment(id: $id) {
+      __typename
+      ... on Payment {
+        ${PAYMENT_RECORD_FIELDS}
+      }
+      ... on CancelPaymentError {
+        paymentErrorMessage
+      }
+      ... on PaymentStateTransitionError {
+        transitionError
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+/** The union members that mean "the provider said no", renamed so a caller branches on intent. */
+const DECLINE_CODES = {
+    SETTLE_PAYMENT_ERROR: 'PAYMENT_SETTLE_DECLINED',
+    CANCEL_PAYMENT_ERROR: 'PAYMENT_CANCEL_DECLINED',
+};
+/**
+ * Throw a refusal member as a coded error, carrying the concrete type's sentence (the provider's
+ * reason, the gate's reason) rather than Vendure's per-code template.
+ */
+function paymentOrThrow(result) {
+    if (!isErrorResult(result)) {
+        const { __typename: _typename, ...payment } = result;
+        return payment;
+    }
+    const reason = result.paymentErrorMessage ?? result.transitionError;
+    const message = typeof reason === 'string' && reason.trim() !== '' ? reason : result.message;
+    const declined = DECLINE_CODES[result.errorCode];
+    if (declined) {
+        throw new BusinessRuleError({ code: declined, message, status: 422, service: 'vendure' });
+    }
+    throw errorFromErrorResult({ ...result, message });
+}
 export const REPORT_APP_PAYMENT_MUTATION = /* GraphQL */ `
   mutation ReportAppPayment(
     $paymentId: ID!
@@ -125,7 +232,10 @@ export function createPaymentsModule(transport) {
     return {
         providers: createProvidersModule(transport),
         accountCredit: createAccountCreditModule(transport),
+        ar: createArPaymentsModule(transport),
         methods: createPaymentMethodsModule(transport),
+        requests: createPaymentRequestsModule(transport),
+        paymentLinks: createPaymentLinksModule(transport),
         async record(orderId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
@@ -140,7 +250,8 @@ export function createPaymentsModule(transport) {
             return data.recordOrderPayment;
         },
         async position(orderId, options) {
-            const data = await transport.graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
+            // The credit fields fall away on an engine before them: the position itself still reads.
+            const data = await creditNotedAware(transport).graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
         async refund(input, options) {
@@ -154,10 +265,28 @@ export function createPaymentsModule(transport) {
             }, options);
             return data.refundOrderPayment;
         },
+        async settle(paymentId, options) {
+            const data = await transport.graphql({ api: 'admin', query: SETTLE_PAYMENT_MUTATION, variables: { id: paymentId } }, options);
+            return paymentOrThrow(data.settlePayment);
+        },
+        async cancel(paymentId, options) {
+            const data = await transport.graphql({ api: 'admin', query: CANCEL_PAYMENT_MUTATION, variables: { id: paymentId } }, options);
+            return paymentOrThrow(data.cancelPayment);
+        },
         async refundPosition(orderId, options) {
             const data = await transport.graphql({ api: 'admin', query: ORDER_REFUND_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderRefundPosition;
         },
+        // Its own query rather than fields on `refundPosition`'s: an SDK released ahead of an engine
+        // without them must not break that read.
+        async refundGiftCardHold(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: REFUND_GIFT_CARD_HOLD_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition;
+        },
+        async refundCreditNoteRequirement(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: REFUND_CREDIT_NOTE_REQUIREMENT_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition.creditNoteRequired;
+        },
         // Its own query rather than a field on `refundPosition`'s: an SDK released
         // ahead of a server without `unreconciled` must not break that read.
         async unreconciledRefunds(orderId, options) {
@@ -193,3 +322,4 @@ export function createPaymentsModule(transport) {
         },
     };
 }
+export { PAYMENT_REQUEST_CLOSE_REASONS, PAYMENT_REQUEST_DEFAULT_EXPIRY_DAYS, PAYMENT_REQUEST_MAX_EXPIRY_DAYS, PAYMENT_REQUEST_STATUSES, } from './requests.js';