@sixtyninecommerce/admin 0.7.0 → 0.9.0

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. */
@@ -51,6 +59,139 @@ export interface RecordPaymentInput {
      */
     metadata?: Record<string, unknown>;
 }
+/**
+ * One payment's contribution to an order's refund position.
+ */
+export interface RefundablePayment {
+    paymentId: string;
+    /** Vendure's payment state. */
+    state: string;
+    /** The payment method code, or null when the payment carries no label. */
+    method: string | null;
+    /** Gross amount taken, minor units. */
+    amount: number;
+    /**
+     * 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`, 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.
+     *
+     * True for a settled payment and for an authorized one on a real gateway — a
+     * card sale at a terminal rests authorized until the webhook settles it, and
+     * that hold is real money. False for an authorized payment on an offline or
+     * net-terms method, where authorized means the money has NOT arrived.
+     */
+    tookMoney: boolean;
+}
+/**
+ * What an order may still hand back, in minor units of its own currency.
+ *
+ * A different question from {@link OrderPaymentPosition}, and the two disagree
+ * on purpose: that one nets refunds against every authorization because it
+ * answers "what is this order covered for", while this one counts only money
+ * that was actually TAKEN, because that is all a refund can return.
+ */
+export interface OrderRefundPosition {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /** Money already given back out of money that was taken. */
+    refunded: number;
+    /**
+     * What may still be handed back for this order: the sum of every payment's
+     * own remaining headroom, each floored at zero.
+     *
+     * 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;
+    /** Minor units of the order's currency. Greater than zero. */
+    amount: number;
+    /**
+     * The payment to return the money to.
+     *
+     * Omit it and the platform allocates across the order's paying payments
+     * NEWEST FIRST: it picks the most recent one whose remaining headroom can
+     * carry the WHOLE amount. A part-paid order settles its remainder last, so
+     * that is the money a merchant means by "give some of it back".
+     *
+     * **One call refunds against ONE payment.** When the order can return the
+     * amount but no single payment can, the call is refused with
+     * `REFUND_EXCEEDS_PAYMENT` and `perPayment` shows exactly how to split it —
+     * rather than the platform spilling silently onto a payment you did not name,
+     * which is what the engine would do.
+     */
+    paymentId?: string;
+    /** Free text stored on the refund. Shown to nobody automatically. */
+    reason?: string;
+}
+/** A refund, as this surface projects it. */
+export interface IssuedRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Pending`, `Settled` or `Failed`. */
+    state: string;
+    /** The payment method the refund was booked against. */
+    method: string | null;
+    /** The gateway's own receipt, when it gave one. */
+    transactionId: string | null;
+    reason: string | null;
+}
 /** The order, as much of it as this surface projects. */
 export interface PaidOrder {
     id: string;
@@ -60,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).
@@ -79,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.
      *
@@ -96,8 +301,169 @@ export interface PaymentsModule {
     record(orderId: string, input: RecordPaymentInput, options?: Call): Promise<PaidOrder>;
     /** Read an order's payment position. */
     position(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
+    /**
+     * Hand money back to a customer, never more than the order took.
+     *
+     * The platform's own refund ceiling, and the one the four surfaces that issue
+     * refunds — returns settlement, credit notes, the till and the order importer
+     * — are measured against. Refuses `REFUND_EXCEEDS_SETTLED` when the amount is
+     * more than the whole ORDER can return, which is the check no per-payment
+     * arithmetic can make: another surface may have refunded the rest of it ten
+     * seconds ago.
+     *
+     * `options.idempotencyKey` is honoured — the Admin API takes it as a mutation
+     * 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.
+     *
+     * **`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`: 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
+     * reads it with `refundPosition(orderId)` rather than off the error.)
+     *
+     * Only money that was TAKEN can come back: a settled payment, or an
+     * authorized one on a real gateway. An offline or net-terms authorization
+     * took nothing and is refused with `REFUND_PAYMENT_HOLDS_NO_MONEY`.
+     *
+     * **The refund you get back is one that moved money.** On an OFFLINE method —
+     * bank transfer, invoice, cash, an imported order's historical tender — it
+     * comes back `Settled`, because there the money moves by hand and recording
+     * it is the settlement. On a live gateway it comes back `Pending` and settles
+     * when the gateway calls back. A method whose handler cannot be resolved at
+     * all, because it is disabled or no longer on this store, is refused
+     * `REFUND_METHOD_UNAVAILABLE` before anything is created, with the payment and
+     * the method in `extensions.details`.
+     *
+     * Other refusals: `REFUND_EXCEEDS_PAYMENT` (the order can return this much,
+     * but no single payment can — split it, using `perPayment`),
+     * `REFUND_PAYMENT_NOT_FOUND`, `REFUND_AMOUNT_NOT_POSITIVE`,
+     * `REFUND_ORDER_NOT_FOUND`, and `REFUND_REFUSED` when the money was there and
+     * the engine or the gateway said no anyway. Every refusal raised once the
+     * order has been read carries that order's position in
+     * `extensions.refundPosition`, so a till can correct itself without a second
+     * round trip.
+     */
+    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';

package/dist/payments/index.js

@@ -1,3 +1,4 @@
+import { createAccountCreditModule } from './account-credit.js';
 import { createProvidersModule } from './providers.js';
 const PAID_ORDER_FIELDS = /* GraphQL */ `
   id
@@ -31,9 +32,98 @@ export const ORDER_PAYMENT_POSITION_QUERY = /* GraphQL */ `
     }
   }
 `;
+const REFUND_POSITION_FIELDS = /* GraphQL */ `
+  currencyCode
+  refunded
+  refundable
+  perPayment {
+    paymentId
+    state
+    method
+    amount
+    refunded
+    refundable
+    tookMoney
+  }
+`;
+export const ORDER_REFUND_POSITION_QUERY = /* GraphQL */ `
+  query OrderRefundPosition($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      ${REFUND_POSITION_FIELDS}
+    }
+  }
+`;
+export const REFUND_ORDER_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {
+    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
+export const UNRECONCILED_REFUNDS_QUERY = /* GraphQL */ `
+  query UnreconciledRefunds($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      unreconciled {
+        refundId
+        paymentId
+        amount
+        createdAt
+      }
+    }
+  }
+`;
+export const RECONCILE_REFUND_OUTCOME_MUTATION = /* GraphQL */ `
+  mutation ReconcileRefundOutcome($input: ReconcileRefundOutcomeInput!, $idempotencyKey: String) {
+    reconcileRefundOutcome(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
+export const REPORT_APP_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation ReportAppPayment(
+    $paymentId: ID!
+    $input: ReportAppPaymentInput!
+    $idempotencyKey: String!
+  ) {
+    reportAppPayment(paymentId: $paymentId, input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      state
+      amount
+      method
+      transactionId
+    }
+  }
+`;
+export const APP_PAYMENTS_QUERY = /* GraphQL */ `
+  query AppPayments($orderId: ID!) {
+    appPayments(orderId: $orderId) {
+      id
+      orderId
+      orderCode
+      state
+      amount
+      currencyCode
+      providerReference
+      methodCode
+      outcomeUnknown
+      createdAt
+    }
+  }
+`;
 export function createPaymentsModule(transport) {
     return {
         providers: createProvidersModule(transport),
+        accountCredit: createAccountCreditModule(transport),
         async record(orderId, input, options) {
             const data = await transport.graphql({
                 api: 'admin',
@@ -51,5 +141,53 @@ export function createPaymentsModule(transport) {
             const data = await transport.graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
+        async refund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REFUND_ORDER_PAYMENT_MUTATION,
+                // Forwarded as a VARIABLE, not a header: the Admin API has no header
+                // for it. `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.refundOrderPayment;
+        },
+        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 a field on `refundPosition`'s: an SDK released
+        // ahead of a server without `unreconciled` must not break that read.
+        async unreconciledRefunds(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: UNRECONCILED_REFUNDS_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition.unreconciled;
+        },
+        async reconcileRefund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: RECONCILE_REFUND_OUTCOME_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.reconcileRefundOutcome;
+        },
+        async reportAppPayment(paymentId, input, options) {
+            // Refused here rather than sent: the argument is non-null on the wire, and
+            // a report without a key could never be safely repeated.
+            if (typeof options?.idempotencyKey !== 'string' || options.idempotencyKey.trim() === '') {
+                throw new TypeError('reportAppPayment needs options.idempotencyKey: one key per provider event.');
+            }
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REPORT_APP_PAYMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: { paymentId, input, idempotencyKey: options.idempotencyKey },
+            }, options);
+            return data.reportAppPayment;
+        },
+        async appPayments(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: APP_PAYMENTS_QUERY, variables: { orderId } }, options);
+            return data.appPayments;
+        },
     };
 }