@sixtyninecommerce/admin 0.8.0 → 0.9.0

package/dist/payments/account-credit.d.ts

@@ -0,0 +1,171 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Unapplied cash: money a customer paid on an order OVER what the order bills,
+ * moved to their account and held there until it pays an invoice or is paid
+ * back. Never a credit note: nothing that was billed is credited.
+ *
+ * Every amount is in minor units of `currencyCode`, and
+ * `amount = applied + refunded + remaining`.
+ */
+export interface UnappliedCash {
+    id: string;
+    customerId: string;
+    /** The currency of the payment the money came from: its order's. */
+    currencyCode: string;
+    /** What was moved to the account. */
+    amount: number;
+    /** What of it has paid invoices. */
+    applied: number;
+    /** What of it was paid back to the customer. */
+    refunded: number;
+    /** What is still on the account, applied to nothing. */
+    remaining: number;
+    /** The order the money was paid on. */
+    orderId: string;
+    /** The payment of that order it was taken from. */
+    paymentId: string;
+    /** Date only (`YYYY-MM-DD`). */
+    receivedOn: string;
+    reference: string | null;
+    /** The reason given when the money was moved. */
+    notes: string | null;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+}
+export interface CreditOverpaymentInput {
+    orderId: string;
+    /**
+     * Minor units of the order's currency. Omit it to move everything the order
+     * holds over what it bills.
+     */
+    amount?: number;
+    /** Why, in your own words: shown on the receipt and in the order's history. */
+    reason?: string;
+}
+export interface ApplyUnappliedCashInput {
+    unappliedCashId: string;
+    /** The AR invoice to pay. Give exactly one of `invoiceId` and `orderId`. */
+    invoiceId?: string;
+    /** An order, paid through the live AR invoice that bills it. */
+    orderId?: string;
+    /**
+     * Minor units. Omit it to apply as much as fits: the lesser of what the cash
+     * still holds and what the invoice still owes.
+     */
+    amount?: number;
+}
+export interface RefundUnappliedCashInput {
+    unappliedCashId: string;
+    /** Minor units. Omit it to pay back everything the cash still holds. */
+    amount?: number;
+    /** Free text stored on the refund. Shown to nobody automatically. */
+    reason?: string;
+}
+/** A payout's refund, as this surface projects it. */
+export interface UnappliedCashRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Pending`, `Settled` or `Failed`. */
+    state: string;
+    method: string | null;
+    transactionId: string | null;
+    reason: string | null;
+}
+/** What of an order's money is on its customer's account now. */
+export interface OrderMoneyOnAccount {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /**
+     * Money that left the order for the customer's account and was not paid back
+     * since. Already taken off the order's `refundable` and `overpaid`.
+     */
+    creditedToAccount: number;
+    /** The same figure per payment of the order, newest first. */
+    perPayment: Array<{
+        paymentId: string;
+        creditedToAccount: number;
+    }>;
+}
+/**
+ * An order's overpayment on the customer's account (`admin.payments.accountCredit`).
+ *
+ * For a store that keeps its own accounts-receivable ledger and a customer with
+ * a credit account in it. Anywhere else an overpayment is refunded: the calls
+ * here are refused `AR_LEDGER_NOT_ENABLED`, `AR_ACCOUNT_REQUIRED` or
+ * `AR_ACCOUNT_IN_ERP`. The last one covers every customer of a store whose ERP
+ * integration is on, and any ERP-linked account: balances are kept in the ERP
+ * there, where a credit recorded here would not show.
+ *
+ * Needs `UpdateOrder` to write, `ReadOrder` to read. Every write honours
+ * `options.idempotencyKey`: a repeat under the same key answers the first
+ * call's result instead of running again.
+ */
+export interface AccountCreditModule {
+    /**
+     * Move money a customer paid on an order over what it bills onto their
+     * account. Answers one {@link UnappliedCash} per payment the money came from,
+     * newest payment first.
+     *
+     * Only money a settled payment still holds can move, net of every refund and
+     * of what was moved before, and at most what the order holds over its
+     * billable total. From then on that money is no longer the order's:
+     * `payments.refundPosition` takes it off `refundable` and `payments.position`
+     * no longer reports it as `overpaid` (read it with {@link onOrder}).
+     *
+     * An order that is already on a live AR invoice is refused
+     * `AR_ORDER_ALREADY_INVOICED`: refund its overpayment with `payments.refund`.
+     *
+     * Other refusals: `ACCOUNT_CREDIT_NOTHING_OVERPAID`,
+     * `ACCOUNT_CREDIT_EXCEEDS_OVERPAYMENT`, `ACCOUNT_CREDIT_AMOUNT_INVALID`,
+     * `ACCOUNT_CREDIT_NO_CUSTOMER`, `ACCOUNT_CREDIT_ORDER_NOT_FOUND`, and the three
+     * account refusals above.
+     */
+    creditOverpayment(input: CreditOverpaymentInput, options?: Call): Promise<UnappliedCash[]>;
+    /** A customer's unapplied cash in this store, oldest first. */
+    list(customerId: string, options?: Call): Promise<UnappliedCash[]>;
+    /**
+     * Pay an AR invoice with unapplied cash. The customer's balance does not
+     * move: the cash was already theirs.
+     *
+     * The invoice must be the same customer's, in the same currency, live and
+     * still owing. Refusals: `AR_INVOICE_NOT_FOUND`, `AR_CURRENCY_MISMATCH`,
+     * `AR_INVOICE_NOT_OPEN`, `AR_ORDER_NOT_INVOICED` (an order with no live
+     * invoice: invoice it first), `UNAPPLIED_CASH_EXCEEDED`,
+     * `UNAPPLIED_CASH_NOT_FOUND`, `UNAPPLIED_CASH_REFUND_UNRECONCILED` (a payout
+     * of the same cash has an unknown outcome), `AR_LEDGER_NOT_ENABLED`.
+     */
+    apply(input: ApplyUnappliedCashInput, options?: Call): Promise<UnappliedCash>;
+    /**
+     * Pay unapplied cash back to the customer: a refund of the payment it was
+     * taken from, with `payments.refund`'s rules and refusals. When one refuses,
+     * nothing has changed.
+     *
+     * At most what the cash still holds, and at most what the customer's account
+     * is in credit by in that currency (`UNAPPLIED_CASH_EXCEEDED`): cash is
+     * applied to what a customer owes before it is paid out.
+     *
+     * **`IDEMPOTENCY_OUTCOME_UNKNOWN`** means the payment provider was asked and
+     * never confirmed. The cash STAYS on the account and is frozen
+     * (`UNAPPLIED_CASH_REFUND_UNRECONCILED`). Find the attempt with
+     * `payments.unreconciledRefunds(orderId)`, check the provider, and record its
+     * answer with `payments.reconcileRefund(...)`: `MADE` takes the cash off the
+     * account then, `NOT_MADE` unfreezes it. Never pay out again on the
+     * assumption that nothing happened.
+     */
+    refund(input: RefundUnappliedCashInput, options?: Call): Promise<UnappliedCashRefund>;
+    /** What of an order's money is on its customer's account now. Needs `ReadOrder`. */
+    onOrder(orderId: string, options?: Call): Promise<OrderMoneyOnAccount>;
+}
+export declare const CREDIT_ORDER_OVERPAYMENT_MUTATION = "\n  mutation CreditOrderOverpaymentToAccount(\n    $input: CreditOrderOverpaymentInput!\n    $idempotencyKey: String\n  ) {\n    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const UNAPPLIED_CASH_QUERY = "\n  query ArUnappliedCash($customerId: ID!) {\n    arUnappliedCash(customerId: $customerId) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const APPLY_UNAPPLIED_CASH_MUTATION = "\n  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {\n    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  customerId\n  currencyCode\n  amount\n  applied\n  refunded\n  remaining\n  orderId\n  paymentId\n  receivedOn\n  reference\n  notes\n  createdAt\n\n    }\n  }\n";
+export declare const REFUND_UNAPPLIED_CASH_MUTATION = "\n  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {\n    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
+/**
+ * Its own query, never a field added to `payments.refundPosition`'s: an SDK
+ * released ahead of a server without `creditedToAccount` must not break that
+ * read.
+ */
+export declare const ORDER_MONEY_ON_ACCOUNT_QUERY = "\n  query OrderMoneyOnAccount($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      currencyCode\n      creditedToAccount\n      perPayment {\n        paymentId\n        creditedToAccount\n      }\n    }\n  }\n";
+export declare function createAccountCreditModule(transport: Transport): AccountCreditModule;

package/dist/payments/account-credit.js

@@ -0,0 +1,107 @@
+const UNAPPLIED_CASH_FIELDS = /* GraphQL */ `
+  id
+  customerId
+  currencyCode
+  amount
+  applied
+  refunded
+  remaining
+  orderId
+  paymentId
+  receivedOn
+  reference
+  notes
+  createdAt
+`;
+export const CREDIT_ORDER_OVERPAYMENT_MUTATION = /* GraphQL */ `
+  mutation CreditOrderOverpaymentToAccount(
+    $input: CreditOrderOverpaymentInput!
+    $idempotencyKey: String
+  ) {
+    creditOrderOverpaymentToAccount(input: $input, idempotencyKey: $idempotencyKey) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const UNAPPLIED_CASH_QUERY = /* GraphQL */ `
+  query ArUnappliedCash($customerId: ID!) {
+    arUnappliedCash(customerId: $customerId) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const APPLY_UNAPPLIED_CASH_MUTATION = /* GraphQL */ `
+  mutation ApplyArUnappliedCash($input: ApplyArUnappliedCashInput!, $idempotencyKey: String) {
+    applyArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {
+      ${UNAPPLIED_CASH_FIELDS}
+    }
+  }
+`;
+export const REFUND_UNAPPLIED_CASH_MUTATION = /* GraphQL */ `
+  mutation RefundArUnappliedCash($input: RefundArUnappliedCashInput!, $idempotencyKey: String) {
+    refundArUnappliedCash(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
+/**
+ * Its own query, never a field added to `payments.refundPosition`'s: an SDK
+ * released ahead of a server without `creditedToAccount` must not break that
+ * read.
+ */
+export const ORDER_MONEY_ON_ACCOUNT_QUERY = /* GraphQL */ `
+  query OrderMoneyOnAccount($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      currencyCode
+      creditedToAccount
+      perPayment {
+        paymentId
+        creditedToAccount
+      }
+    }
+  }
+`;
+export function createAccountCreditModule(transport) {
+    return {
+        async creditOverpayment(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CREDIT_ORDER_OVERPAYMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                // `undefined`, never an explicit null: `JSON.stringify` drops it, so an
+                // omitted key stays off the wire entirely.
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.creditOrderOverpaymentToAccount;
+        },
+        async list(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: UNAPPLIED_CASH_QUERY, variables: { customerId } }, options);
+            return data.arUnappliedCash;
+        },
+        async apply(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: APPLY_UNAPPLIED_CASH_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.applyArUnappliedCash;
+        },
+        async refund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REFUND_UNAPPLIED_CASH_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.refundArUnappliedCash;
+        },
+        async onOrder(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_MONEY_ON_ACCOUNT_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition;
+        },
+    };
+}

package/dist/payments/index.d.ts

@@ -1,5 +1,6 @@
 import type { Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
+import { type AccountCreditModule } from './account-credit.js';
 import { type ProvidersModule } from './providers.js';
 /**
  * What an order has actually been paid, in minor units of its own currency.
@@ -16,13 +17,20 @@ export interface OrderPaymentPosition {
     settled: number;
     /** Money a payment handler may take and has not. */
     authorized: number;
+    /**
+     * Refunds recorded against the order's payments. Money moved to the
+     * customer's account (`payments.accountCredit`) is NOT a refund and is not
+     * counted here, though it is taken off `settled` like one.
+     */
     refunded: number;
     /** `total - covered`, floored at zero. */
     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, or a
-     * refund that landed after a second payment.
+     * 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
+     * (`payments.accountCredit.creditOverpayment`) no longer counts here.
      */
     overpaid: number;
     /** What a further payment may take. */
@@ -62,9 +70,18 @@ export interface RefundablePayment {
     method: string | null;
     /** Gross amount taken, minor units. */
     amount: number;
-    /** Non-failed refunds already recorded against it. A failed refund never left. */
+    /**
+     * Refunds already recorded against it that did not fail, plus failed ones
+     * whose outcome is unknown — reserved until the provider's answer is recorded
+     * (see {@link PaymentsModule.unreconciledRefunds}). A plainly failed refund
+     * never left.
+     */
     refunded: number;
-    /** `amount - refunded` when this payment took money, floored at zero; else zero. */
+    /**
+     * `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.
+     */
     refundable: number;
     /**
      * Whether this payment took money at all.
@@ -96,11 +113,49 @@ export interface OrderRefundPosition {
      * There is deliberately no credit-note deduction. A credit note that moved
      * money already has its refund on the payment; one that moved none has
      * nothing to deduct.
+     *
+     * 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.
      */
     refundable: number;
     /** Every payment on the order, NEWEST FIRST, with its own headroom. */
     perPayment: RefundablePayment[];
 }
+/**
+ * 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
+ * platform cannot say whether the money moved. Its amount is reserved — counted
+ * in the refund position's `refunded` — until
+ * {@link PaymentsModule.reconcileRefund} records the provider's answer.
+ */
+export interface UnreconciledRefund {
+    /** The refund to pass to `reconcileRefund`. */
+    refundId: string;
+    paymentId: string;
+    /** Minor units of the order's currency. */
+    amount: number;
+    /** ISO-8601 with offset. */
+    createdAt: string | null;
+}
+/** 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. */
+export interface ReconcileRefundInput {
+    refundId: string;
+    /**
+     * `MADE`: the money went back. `NOT_MADE`: nothing moved. Checked with the
+     * provider — never guessed.
+     */
+    outcome: RefundProviderOutcome;
+    /**
+     * The provider's reference for its answer: its refund id when it made one, or
+     * where the answer was checked. Required, at most 200 characters.
+     */
+    providerReference: string;
+    /** Optional context for the order's history, at most 1000 characters. */
+    note?: string;
+}
 /** Money handed back to a customer. */
 export interface RefundPaymentInput {
     orderId: string;
@@ -146,6 +201,65 @@ export interface PaidOrder {
     total: number;
     totalWithTax: number;
 }
+/** 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. */
+export interface ReportAppPaymentInput {
+    /**
+     * What the provider did. An authorized payment can be reported `Settled`,
+     * `Declined` or `Cancelled`; a payment whose outcome is unknown (see
+     * {@link AppPayment}) only `Settled` or `Declined` — the provider knows
+     * whether it took the money.
+     *
+     * `Authorized` is for ONE case: you answered `create` `Authorized` with a
+     * `redirect_url`, and the buyer finished your hosted page with the money
+     * authorized, to be captured later (pay later, capture at shipment). Until
+     * you report, the order stays the buyer's unplaced cart; this report places
+     * it (`PaymentAuthorized`) when the payment covers it. A later `Settled`
+     * report, or the store capturing it (your `capture` hook), settles it. Any
+     * other payment reported `Authorized` is `PAYMENT_STATE_NOT_REPORTABLE`.
+     */
+    state: AppPaymentReportState;
+    /**
+     * The provider's reference for the payment, at most 255 characters. When the
+     * app answered `create` with one, it must be that one.
+     */
+    providerReference: string;
+    /** Minor units of the order's currency. Must equal the payment's amount. */
+    amount: number;
+}
+/** A payment an app took, as the installation that took it reads it. */
+export interface AppPayment {
+    id: string;
+    orderId: string;
+    orderCode: string;
+    /** Vendure's payment state: `Authorized`, `Settled`, `Declined`, `Error`, `Cancelled`. */
+    state: string;
+    /** Minor units. */
+    amount: number;
+    currencyCode: string;
+    /** The provider's reference — the payment's `transactionId` — once the app gave one. */
+    providerReference: string | null;
+    methodCode: string;
+    /**
+     * The platform asked the app (create, or capture) and never heard back, so
+     * whether the money moved is unknown. The platform does NOT ask again (a
+     * second request could be a second charge): report the outcome with
+     * {@link PaymentsModule.reportAppPayment}.
+     */
+    outcomeUnknown: boolean;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+}
+/** The payment as it stands after an app's report. */
+export interface ReportedAppPayment {
+    id: string;
+    state: string;
+    /** Minor units. */
+    amount: number;
+    method: string;
+    transactionId: string | null;
+}
 /**
  * Payments: money against an order (spec §8.2), and the provider accounts
  * it runs through (spec §8.9).
@@ -165,6 +279,11 @@ export interface PaidOrder {
 export interface PaymentsModule {
     /** Provider onboarding, terminals and readiness (spec §8.9). */
     providers: ProvidersModule;
+    /**
+     * An order's overpayment on the customer's account: move it there, apply it
+     * to an invoice, pay it back.
+     */
+    accountCredit: AccountCreditModule;
     /**
      * Record part (or all) of what an order owes, and return the order.
      *
@@ -196,15 +315,38 @@ export interface PaymentsModule {
      * argument — so a retry under the same key returns the FIRST call's refund
      * instead of raising a second one. Use a fresh key per intended refund.
      *
-     * **`IDEMPOTENCY_OUTCOME_UNKNOWN` is neither success nor refusal.** The engine
-     * calls the payment gateway from inside the transaction that writes the refund
+     * **`error.outcomeUnknown` has two causes here, and they recover differently.**
+     *
+     * 1. **No answer came back** (a timeout, your own signal aborting the call
+     *    after it was sent, a dropped connection, a proxy's 502/504). The first
+     *    call may still be running on the server and its key is NOT spent, so
+     *    repeat the call under the SAME key, never a new one. The
+     *    platform then answers with the first call's refund, with
+     *    `IDEMPOTENCY_IN_PROGRESS` (wait, then repeat again under that key), or
+     *    with `IDEMPOTENCY_OUTCOME_UNKNOWN` (case 2). A NEW key here can refund
+     *    twice: the second request waits on the order lock until the first one
+     *    commits, and then both fit under the ceiling. A call made without a key
+     *    has no safe repeat: once the first call can have finished, read
+     *    `payments.refundPosition(orderId)` and reconcile against the gateway.
+     * 2. **`IDEMPOTENCY_OUTCOME_UNKNOWN`** is neither success nor refusal. It
+     *    arrives as a `ConflictError` (409) because the key is spent, but the class
+     *    is not the message: branch on the code, or on `error.outcomeUnknown`. The
+     *    engine calls the payment gateway from inside the transaction that writes the refund
      * row, so a failure after that call leaves an outcome nobody can read off the
      * database: the money may be on its way back with no row to show for it. You
      * get this code on the FIRST call when that happens, and on every repeat under
      * the same key — the key is spent rather than released, so the refund never
-     * runs again. Do NOT treat it as `REFUND_REFUSED`: read
-     * `payments.refundPosition(orderId)`, reconcile against the gateway, and only
-     * then decide. If the money did not move, issue a new request under a NEW key.
+     * runs again. Do NOT treat it as `REFUND_REFUSED`: the attempt is recorded as
+     * a refund whose outcome is unknown, and its amount stays RESERVED in the
+     * position — this call, the till, credit notes, returns and core's own
+     * `refundOrder` mutation (the dashboard's Refund button) no longer refund
+     * the order or that payment past what they took. The reservation does NOT
+     * stop a new request for the same
+     * partial amount while headroom remains, so never retry under a new key
+     * blindly. Find the attempt with `payments.unreconciledRefunds(orderId)`,
+     * check the gateway, and record the answer with `payments.reconcileRefund(...)`.
+     * After `MADE` the spent key replays that refund; after `NOT_MADE` it may run
+     * again, and the amount is refundable again.
      *
      * (The server also attaches the position to that error, but `PlatformError`
      * carries only `code`, `message`, `details` and `traceId`, so an SDK caller
@@ -235,10 +377,93 @@ export interface PaymentsModule {
     refund(input: RefundPaymentInput, options?: Call): Promise<IssuedRefund>;
     /** Read what an order may still hand back. */
     refundPosition(orderId: string, options?: Call): Promise<OrderRefundPosition>;
+    /**
+     * The order's refunds whose outcome is unknown, oldest first — the ones
+     * {@link reconcileRefund} resolves. Each one's amount is already reserved in
+     * {@link refundPosition}.
+     *
+     * A refund lands here when its payment provider was asked and never
+     * confirmed: `refund` answered `IDEMPOTENCY_OUTCOME_UNKNOWN`, or a till card
+     * refund, a credit note or a return settlement did. Needs `ReadOrder`.
+     */
+    unreconciledRefunds(orderId: string, options?: Call): Promise<UnreconciledRefund[]>;
+    /**
+     * Record the payment provider's answer for a refund whose outcome is unknown.
+     * Needs `UpdateOrder` — the permission refunds take.
+     *
+     * - `MADE`: the money went back. The refund becomes `Settled` as if the
+     *   provider had confirmed it at the time: it counts as returned, a return
+     *   parked on it completes its settlement, and `payment.refunded` is
+     *   announced. The key that spent itself on the attempt now replays it.
+     * - `NOT_MADE`: nothing moved. The refund stays `Failed`, its reservation is
+     *   released and a retry is allowed — the spent key, a till refund, the credit
+     *   note, or settling the parked return again.
+     *
+     * The outcome is kept on the refund's metadata, which the Shop API serves, so
+     * nothing else goes there: `providerReference`, `note` and who recorded it go
+     * to a private order note and the audit trail.
+     *
+     * Refusals: `REFUND_NOT_FOUND`, `REFUND_OUTCOME_NOT_UNKNOWN` (the outcome is
+     * already known — never unknown, or reconciled already),
+     * `REFUND_RECONCILIATION_INVALID` (a blank or oversized `providerReference`,
+     * an oversized `note`), and `REFUND_EXCEEDS_PAYMENT` when `MADE` would have
+     * the payment return more than it took (another refund on record against it
+     * cannot be right).
+     *
+     * `options.idempotencyKey` is honoured: a repeat under the same key returns
+     * the first call's refund.
+     */
+    reconcileRefund(input: ReconcileRefundInput, options?: Call): Promise<IssuedRefund>;
+    /**
+     * **For a payment app, with its installation token.** Report what happened to
+     * a payment your app took (spec §8.14 `payment.provider`): the asynchronous
+     * pattern — you answered `create` `Authorized`, and the money lands later —
+     * and the reconciliation of a payment whose outcome is unknown (you were
+     * asked and the platform never received your answer; it will not ask again).
+     *
+     * The platform moves the payment through its own payment processes, exactly
+     * as for any provider callback: a covered order is settled and placed, money
+     * for a held (parked) order lands where the order stands, and
+     * `payment.settled` is published with your installation as its actor. A
+     * hosted page that only authorized is reported `Authorized` (see
+     * {@link ReportAppPaymentInput.state}): the order is placed on it.
+     *
+     * `options.idempotencyKey` is REQUIRED: a repeat of the same report under it
+     * answers the payment as it now is, for as long as the payment exists; a
+     * DIFFERENT report under it is refused `IDEMPOTENCY_CONFLICT` (409). Use one
+     * key per event you received from your provider.
+     *
+     * Refusals: `PAYMENT_NOT_OWNED_BY_INSTALLATION` (a `PermissionDeniedError`,
+     * 403: not a payment this installation took on this store — one answer
+     * whatever the reason),
+     * `PAYMENT_AMOUNT_MISMATCH`, `PAYMENT_STATE_NOT_REPORTABLE` (the payment
+     * cannot move to that state from where it is, `extensions.details.state`),
+     * `APP_PAYMENT_REPORT_INVALID` (a malformed report, or a reference other than
+     * the one `create` answered), `APP_PAYMENT_METHOD_DISABLED` (the store took
+     * your app off as its payment provider; a decline is still recorded),
+     * `IDEMPOTENCY_KEY_INVALID`.
+     */
+    reportAppPayment(paymentId: string, input: ReportAppPaymentInput, options: Call & {
+        idempotencyKey: string;
+    }): Promise<ReportedAppPayment>;
+    /**
+     * **For a payment app, with its installation token.** Your installation's
+     * payments on one order of this store, oldest first: how you find a
+     * payment's id, which the `create` call cannot carry because the payment
+     * does not exist until you answer. Match on `providerReference`. An order the
+     * store does not have answers `[]`; any caller but an installation is refused
+     * `PAYMENT_NOT_OWNED_BY_INSTALLATION`.
+     */
+    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_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 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 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 { ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, } from './providers.js';