@peable.to/shared-types 0.10.0 → 0.11.0

package/dist/types/event.d.ts

@@ -1,73 +1,17 @@
+import type { Charge } from './charge';
+import type { Customer } from './customer';
 import type { Dispute } from './dispute';
 import type { PaymentIntent } from './paymentIntent';
-import type { ConnectedAccount } from './settlement';
-export type WebhookEventType = 'payment_intent.confirming' | 'payment_intent.settled' | 'payment_intent.failed' | 'payment_intent.rejected' | 'payment_intent.expired'
+import type { PaymentMethod } from './paymentMethod';
+import type { ConnectedAccount, Refund } from './settlement';
+import type { SetupIntent } from './setupIntent';
+import type { WebhookEndpoint } from './webhookEndpoint';
 /**
- * Money went back to the payer.
- *
- * Both of these exist for the refund a merchant did NOT initiate — one made
- * from the provider's own dashboard, or a dispute the network resolved
- * against the merchant. A merchant who only ever learned about their own
- * refunds would reconcile to a balance that disagrees with the provider's,
- * with nothing to explain the difference.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches them.
- */
- | 'payment_intent.refunded' | 'payment_intent.partially_refunded'
-/**
- * The network is holding this payment's money while a cardholder contests it.
- *
- * Two events and not one because the two moments demand different things of a
- * merchant. `disputed` is a DEADLINE — evidence is due, and a merchant who
- * learns about it late has already lost. `dispute_closed` carries the outcome,
- * which is when the money is finally theirs or finally gone.
- *
- * Neither is a payment-intent STATUS. A dispute is the network's process, not
- * a stage of the payment's lifecycle — the payment stayed `settled` throughout
- * and may end there. That is also how Stripe models it: a charge is
- * `disputed`, a PaymentIntent has no such status.
- *
- * These two carry a {@link Dispute} as their `data.object`, NOT the payment
- * intent — see {@link WebhookEventPayload}. The `paymentIntentId` on it is
- * how a consumer gets back to the payment.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches them.
- */
- | 'payment_intent.disputed' | 'payment_intent.dispute_closed'
-/**
- * A seller's account changed — their READINESS, in practice.
- *
- * The first event here that is not about a payment, and it exists because
- * readiness is the one fact about a seller a marketplace cannot act without
- * and could not learn: the gateway refreshed the account row from the
- * provider and told the merchant nothing, so the only ways to find out a
- * seller had finished onboarding were to poll `GET /v1/connected_accounts`
- * or to attempt a settlement and read the refusal.
- *
- * Emitted when the fields a merchant ACTS on change — payability, the two
- * capabilities, the requirement counts, the disabled reasons — and not on
- * every refresh. A periodic sync sweep re-reads every account whether or not
- * anything moved, and an event per sweep would be a stream a merchant learns
- * to ignore.
- *
- * It carries a {@link ConnectedAccount} and its delivery names NO payment
- * intent, which is why `WebhookDelivery.intentId` is nullable.
- *
- * Additive to a published contract: an existing consumer that switches on
- * this union keeps compiling and simply never matches it.
- */
- | 'connected_account.updated' | 'billing.observation.updated';
-/**
- * Which resource each event type carries under `data.object`.
- *
- * TOTAL over `WebhookEventType`, so a new event type cannot be added without
- * saying what it delivers. That matters more here than anywhere else in this
- * contract: `data.object` is the whole payload, and an event type added with
- * the default would silently ship a PaymentIntent to a consumer expecting
- * something else — which typechecks on both sides and fails only in production.
+ * The wire date every response names in `Peable-Version`, and the
+ * `api_version` an event is stored under (ADR 0014 D2/D4). One constant, so
+ * the header and the stored events cannot name two different wires.
  */
+export declare const PEABLE_API_VERSION = "2026-11-03";
 /** Wake-up only. Re-read the owner-bound SDK resource; this is never paid or grant authority. */
 export interface BillingObservation {
     object: 'billing_observation';
@@ -80,18 +24,81 @@ export interface BillingObservation {
     revision: number;
     observed_at: number;
 }
+/**
+ * Which resource each event type carries under `data.object`.
+ *
+ * TOTAL over {@link WebhookEventType} (which is derived from its keys), so a new
+ * event type cannot exist without saying what it delivers: an event added with
+ * a default would silently ship a PaymentIntent to a consumer expecting
+ * something else — which typechecks on both sides and fails only in production.
+ *
+ * The `payment_intent.*` events follow the status the intent reached
+ * (ADR 0019): `created` when it is minted, then one per transition —
+ * `requires_action`, `processing`, `amount_capturable_updated` (authorized,
+ * awaiting capture), `succeeded`, `payment_failed` (an attempt failed; a card
+ * returns to `requires_payment_method`, a FairCoin underpayment is also
+ * `canceled`) and `canceled` (by the merchant, by expiry — `abandoned` — or
+ * underpaid).
+ *
+ * Refunds are not PaymentIntent statuses: `refund.created|updated|failed` carry
+ * the Refund, and `charge.refunded` the Charge whose `amount_refunded` moved.
+ * A dispute is the network's process beside a payment that stays `succeeded`:
+ * `charge.dispute.created` is a DEADLINE (evidence is due), `closed` carries
+ * the outcome.
+ */
 export interface WebhookEventPayload {
-    'billing.observation.updated': BillingObservation;
-    'payment_intent.confirming': PaymentIntent;
-    'payment_intent.settled': PaymentIntent;
-    'payment_intent.failed': PaymentIntent;
-    'payment_intent.rejected': PaymentIntent;
-    'payment_intent.expired': PaymentIntent;
-    'payment_intent.refunded': PaymentIntent;
-    'payment_intent.partially_refunded': PaymentIntent;
-    'payment_intent.disputed': Dispute;
-    'payment_intent.dispute_closed': Dispute;
+    'payment_intent.created': PaymentIntent;
+    'payment_intent.requires_action': PaymentIntent;
+    'payment_intent.processing': PaymentIntent;
+    'payment_intent.amount_capturable_updated': PaymentIntent;
+    'payment_intent.succeeded': PaymentIntent;
+    'payment_intent.payment_failed': PaymentIntent;
+    'payment_intent.canceled': PaymentIntent;
+    'charge.refunded': Charge;
+    'charge.dispute.created': Dispute;
+    'charge.dispute.updated': Dispute;
+    'charge.dispute.closed': Dispute;
+    'refund.created': Refund;
+    'refund.updated': Refund;
+    'refund.failed': Refund;
+    'customer.created': Customer;
+    'customer.updated': Customer;
+    'customer.deleted': Customer;
+    'payment_method.attached': PaymentMethod;
+    'payment_method.detached': PaymentMethod;
+    'payment_method.updated': PaymentMethod;
+    'setup_intent.created': SetupIntent;
+    'setup_intent.requires_action': SetupIntent;
+    'setup_intent.succeeded': SetupIntent;
+    'setup_intent.setup_failed': SetupIntent;
+    'setup_intent.canceled': SetupIntent;
+    /**
+     * A seller's account changed — their READINESS, in practice. Emitted when the
+     * fields a merchant ACTS on change, not on every refresh. It names no payment
+     * intent.
+     */
     'connected_account.updated': ConnectedAccount;
+    'billing.observation.updated': BillingObservation;
+    /**
+     * A synthetic event sent to ONE endpoint when its owner asks to test it
+     * (Orbit's "send test event"). Stored like any other event, but it never fans
+     * out and it cannot be subscribed to: `enabled_events` refuses it. The
+     * endpoint being tested, as `GET /v1/webhook_endpoints/:id` returns it.
+     */
+    'webhook_endpoint.test': WebhookEndpoint;
+}
+/** Every event type, Stripe's names. */
+export type WebhookEventType = keyof WebhookEventPayload;
+/**
+ * What caused an event, when an API request did (Stripe's `event.request`).
+ * Both `null` for an event caused by something else — the chain watcher, the
+ * expiry sweeper, a provider's own notification.
+ */
+export interface WebhookEventRequest {
+    /** The `Request-Id` of the request whose change produced the event. */
+    id: string | null;
+    /** The `Idempotency-Key` that request carried, if any. */
+    idempotency_key: string | null;
 }
 /**
  * One delivered event.
@@ -100,20 +107,13 @@ export interface WebhookEventPayload {
  * a switch on `type` with no cast:
  *
  * ```ts
- * if (event.type === 'payment_intent.disputed') {
+ * if (event.type === 'charge.dispute.created') {
  *   event.data.object.evidence_due_at; // Dispute, not PaymentIntent
  * }
  * ```
  *
- * That correlation is the whole point of building it this way rather than as
- * `{ type: WebhookEventType; data: { object: PaymentIntent | Dispute } }`,
- * which typechecks identically at the boundary and then lets a consumer read a
- * `Dispute`'s fields off a settlement.
- *
- * The parameter narrows to a subset of event types — `WebhookEvent<'payment_intent.disputed'>`
- * is the dispute event alone. It takes an event TYPE and not a payload type,
- * because the payload is derivable from the event and the reverse is not: two
- * event types share `Dispute`.
+ * The parameter narrows to a subset of event types —
+ * `WebhookEvent<'payment_intent.succeeded'>` is that event alone.
  */
 export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
     [T in K]: {
@@ -126,13 +126,23 @@ export type WebhookEvent<K extends WebhookEventType = WebhookEventType> = {
         /**
          * The connected account (`ca_…`) this event is about — Stripe's
          * `event.account` (ADR 0012 D7). Present on every event for an on-behalf
-         * payment and on `connected_account.updated`; absent on events about the
-         * merchant's own payments. Lets a platform route an event to a seller
-         * without opening `data.object`.
+         * payment and on `connected_account.updated`; absent otherwise.
          */
         account?: string;
+        /**
+         * The wire version the event was rendered with — the `Peable-Version` of
+         * the deployment that stored it. An event is a stored snapshot; it is not
+         * re-rendered when the wire moves on.
+         */
+        api_version: string;
         data: {
             object: WebhookEventPayload[T];
+            /**
+             * The fields of `object` that this change moved, with their values
+             * BEFORE it. Absent when the event is not a change of an existing object.
+             */
+            previous_attributes?: Record<string, unknown>;
         };
+        request: WebhookEventRequest;
     };
 }[K];

package/dist/types/index.d.ts

@@ -1,8 +1,13 @@
 export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
 export type { ExpandParams, List, ListParams, RangeQuery } from './list';
-export { type PaymentIntentStatus, type PaymentIntentRail, type PaymentIntent, type CreatePaymentIntentParams, type UpdatePaymentIntentParams, isValidStatusTransition, canStillBePaid, reachesSettlementFromPayer, POST_SETTLEMENT_STATUSES, PAYMENT_INTENT_STATUSES, PAYMENT_INTENT_RAILS, CHAIN_ONLY_STATUSES, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, canExpire, } from './paymentIntent';
-export type { WebhookEventType, WebhookEvent, WebhookEventPayload, BillingObservation, } from './event';
+export { type Address, type AddressParams, type CancelPaymentIntentParams, type CapturePaymentIntentParams, type ConfirmPaymentIntentParams, type CreatePaymentIntentParams, type PaymentIntent, type PaymentIntentCancellationReason, type PaymentIntentCaptureMethod, type PaymentIntentFaircoin, type PaymentIntentLastPaymentError, type PaymentIntentNextAction, type PaymentIntentRail, type PaymentIntentSetupFutureUsage, type PaymentIntentStatus, type PaymentMethodType, type Shipping, type ShippingParams, type UpdatePaymentIntentParams, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, MERCHANT_CANCELLATION_REASONS, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, TERMINAL_STATUSES, canExpire, canStillBePaid, isValidStatusTransition, } from './paymentIntent';
+export type { CardDetails, Charge, ChargeOutcome } from './charge';
+export type { CreateCustomerParams, Customer, DeletedCustomer, UpdateCustomerParams, } from './customer';
+export type { AttachPaymentMethodParams, BillingDetails, PaymentMethod, UpdatePaymentMethodParams, } from './paymentMethod';
+export { type CancelSetupIntentParams, type CreateSetupIntentParams, type SetupIntent, type SetupIntentCancellationReason, type SetupIntentStatus, type SetupIntentUsage, SETUP_INTENT_STATUSES, } from './setupIntent';
+export { PEABLE_API_VERSION, type WebhookEventType, type WebhookEvent, type WebhookEventPayload, type WebhookEventRequest, type BillingObservation, } from './event';
+export { WEBHOOK_ENDPOINT_STATUSES, WEBHOOK_ENDPOINT_DISABLED_REASONS, WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT, WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS, type WebhookEnabledEvent, type WebhookEndpoint, type WebhookEndpointStatus, type WebhookEndpointDisabledReason, type DeletedWebhookEndpoint, type CreateWebhookEndpointParams, type UpdateWebhookEndpointParams, type RollWebhookEndpointSecretParams, } from './webhookEndpoint';
 export type { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
 export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';

package/dist/types/merchant.d.ts

@@ -23,7 +23,6 @@ export interface Merchant {
     network: NetworkType | null;
     /** `null` on a card-only merchant. Nullable together with `network`. */
     xpub: string | null;
-    webhook_url?: string;
     required_confirmations: number;
     /**
      * Payer-facing branding. Absent when unset — `MerchantDisplay` is what a

package/dist/types/paymentIntent.d.ts

@@ -1,6 +1,9 @@
-import type { ConnectedAccount } from './settlement';
+import type { Charge } from './charge';
+import type { Customer } from './customer';
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
+import type { PaymentMethod } from './paymentMethod';
+import type { ConnectedAccount } from './settlement';
 /**
  * Which rail moves the money (ADR 0001 D1).
  *
@@ -11,65 +14,157 @@ import type { NetworkType } from './network';
 export type PaymentIntentRail = 'faircoin' | 'card';
 /** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
 export declare const PAYMENT_INTENT_RAILS: readonly PaymentIntentRail[];
-export type PaymentIntentStatus = 'created' | 'awaiting_approval' | 'approved' | 'broadcast' | 'confirming' | 'requires_action' | 'processing' | 'settled' | 'refunded' | 'partially_refunded' | 'expired' | 'failed' | 'rejected';
 /**
- * Which statuses belong to which rail (ADR 0001 D5).
+ * Stripe's seven statuses, and no others (ADR 0019).
  *
- * The four chain states describe a transaction on a blockchain and the four
- * card states describe an authorization at a card acquirer; neither set is
- * expressible on the other rail. Mapping a card authorization onto `broadcast`
- * would be cheaper and would be a lie — nothing was broadcast, there is no
- * transaction, and `payment_intents_broadcast_requires_txid_check` would then
- * be demanding a txid from a payment that can never have one.
+ * The FairCoin rail walks four of them: it is created in `requires_action`
+ * (the payer must broadcast a transaction — `next_action.faircoin_payment`),
+ * moves to `processing` once a transaction is reported and while it confirms,
+ * and ends `succeeded` or `canceled`. A card walks all seven.
+ */
+export type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
+/**
+ * The statuses only a CARD payment can reach (ADR 0019).
  *
- * `db/schema/payments.ts` renders these two sets into CHECK constraints, so the
- * restriction holds against a write that skipped the application.
+ * A FairCoin payment has no payment method to require (the payer's wallet signs
+ * on their own device), nothing to confirm server-side, and no authorization
+ * to capture — coins either arrive or they do not. `db/schema/payments.ts`
+ * renders this set into a CHECK, so the restriction holds against a write that
+ * skipped the application.
  */
-export declare const CHAIN_ONLY_STATUSES: readonly PaymentIntentStatus[];
 export declare const CARD_ONLY_STATUSES: readonly PaymentIntentStatus[];
 export declare function isValidStatusTransition(from: PaymentIntentStatus, to: PaymentIntentStatus): boolean;
-/** Every legal `PaymentIntentStatus`, derived from `ALLOWED`'s keys — the
- * single source of truth consumed by the Gateway's list-route status filter. */
+/** Every `PaymentIntentStatus`, derived from `ALLOWED`'s keys. */
 export declare const PAYMENT_INTENT_STATUSES: readonly PaymentIntentStatus[];
+/** The statuses that end a payment: nothing leaves them (bar the reorg exception). */
+export declare const TERMINAL_STATUSES: readonly PaymentIntentStatus[];
 /**
  * Whether a payer can still complete a payment against an intent in this
- * status.
- *
- * `settled` answers `false`: it is where paying ENDS. `partially_refunded`
- * answers `false` too — money can still move, but not from the payer.
+ * status — every non-terminal one. Stated, not derived from reachability:
+ * `paymentIntent.test.ts` pins it against the table.
  */
 export declare function canStillBePaid(status: PaymentIntentStatus): boolean;
 /**
- * The statuses a payment reaches only AFTER the payer has finished.
+ * The statuses an intent may still EXPIRE from (ADR 0012 D9).
  *
- * Exported for the gate below rather than for production use: the property that
- * makes `PAYABLE_STATUSES` checkable is that a payable status reaches `settled`
- * without going through one of these.
+ * The gateway is waiting on a PERSON who has not paid: a FairCoin payer who has
+ * not broadcast (`requires_action`), or a card payer who has not completed a
+ * payment method or a challenge. Once a FairCoin payer has reported a
+ * transaction (`processing`) the intent NEVER expires, whatever `expires_at`
+ * says — coins are moving and the settlement watcher owns the row. An
+ * authorization held for capture (`requires_capture`) is the merchant's to
+ * capture or cancel and does not expire either.
+ *
+ * Expiry is a cancellation with `cancellation_reason: 'abandoned'`: a platform
+ * releases a reservation on `payment_intent.canceled`.
  */
-export declare const POST_SETTLEMENT_STATUSES: readonly PaymentIntentStatus[];
+export declare const EXPIRABLE_STATUSES: readonly PaymentIntentStatus[];
+/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
+export declare function canExpire(status: PaymentIntentStatus): boolean;
 /**
- * Whether `settled` is reachable from `status` without passing through a
- * post-settlement status. The derivation `canStillBePaid` used to BE, kept as
- * the thing that checks it rather than as the thing that answers it.
+ * Why an intent was cancelled — Stripe's reasons, plus `underpaid`.
+ *
+ *  - `abandoned` — it expired: the payer never paid (the expiry sweeper).
+ *  - `requested_by_customer` / `duplicate` / `fraudulent` — the merchant said so
+ *    through `POST /v1/payment_intents/:id/cancel`.
+ *  - `underpaid` — FairCoin only: a transaction arrived at the address and paid
+ *    less than the amount. Peable never holds those coins, so it cannot ask for
+ *    the difference on the same intent; `last_payment_error` says what happened.
+ *  - `automatic` — the provider cancelled it on its own.
+ *
+ * `null` on a cancelled intent whose cause was never recorded (one cancelled
+ * without a reason, or migrated from the pre-0019 `rejected`).
  */
-export declare function reachesSettlementFromPayer(status: PaymentIntentStatus): boolean;
+export type PaymentIntentCancellationReason = 'abandoned' | 'automatic' | 'duplicate' | 'fraudulent' | 'requested_by_customer' | 'underpaid';
+export declare const PAYMENT_INTENT_CANCELLATION_REASONS: readonly PaymentIntentCancellationReason[];
+/** The reasons a MERCHANT may give `POST /v1/payment_intents/:id/cancel`. */
+export declare const MERCHANT_CANCELLATION_REASONS: readonly ["abandoned", "duplicate", "fraudulent", "requested_by_customer"];
+/** When a card is captured: at confirmation, or by `POST …/capture` (card only). */
+export type PaymentIntentCaptureMethod = 'automatic' | 'manual';
+export declare const PAYMENT_INTENT_CAPTURE_METHODS: readonly PaymentIntentCaptureMethod[];
+/** Card only: keep the payment method on the customer for later (ADR 0016). */
+export type PaymentIntentSetupFutureUsage = 'on_session' | 'off_session';
+export declare const PAYMENT_INTENT_SETUP_FUTURE_USAGES: readonly PaymentIntentSetupFutureUsage[];
+/** The payment method types a rail accepts. One per rail today. */
+export type PaymentMethodType = 'card' | 'faircoin';
+/** Why the last attempt failed. Peable's words, never the provider's raw prose. */
+export interface PaymentIntentLastPaymentError {
+    /** `card_error` for a declined card; `payment_error` for a FairCoin underpayment. */
+    type: 'card_error' | 'payment_error' | 'api_error';
+    code: string | null;
+    decline_code: string | null;
+    message: string;
+}
+/** A postal address — Stripe's shape. */
+export interface Address {
+    line1: string | null;
+    line2: string | null;
+    city: string | null;
+    state: string | null;
+    postal_code: string | null;
+    /** ISO 3166-1 alpha-2. */
+    country: string | null;
+}
+export interface Shipping {
+    name: string;
+    phone: string | null;
+    address: Address;
+    carrier: string | null;
+    tracking_number: string | null;
+}
+/** An address as a request carries it: every field optional. */
+export interface AddressParams {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postal_code?: string;
+    country?: string;
+}
+/** Shipping as a request carries it: only `name` and `address` are required. */
+export interface ShippingParams {
+    name: string;
+    phone?: string;
+    address: AddressParams;
+    carrier?: string;
+    tracking_number?: string;
+}
 /**
- * The statuses an intent may still EXPIRE from (ADR 0012 D9).
+ * What the payer must do next (`status: 'requires_action'`).
  *
- * Exactly those whose transition list contains `expired`: the gateway is
- * waiting on a PERSON who has not paid. Once a FairCoin payer has reported a
- * broadcast (`broadcast`), or the chain is confirming it (`confirming`), the
- * intent NEVER expires, whatever `expiresAt` says — coins are moving and the
- * settlement watcher owns the row. A platform must therefore never cancel an
- * order because `expiresAt` passed: it releases a reservation on
- * `payment_intent.expired` (or `rejected`), and on nothing else.
+ *  - `faircoin_payment` — send exactly `amount` (base units) to `address` on
+ *    `network`; `uri` is the BIP21-style `faircoin:` URI a wallet scans.
+ *  - `use_peable_sdk` — a card challenge; `@peable.to/sdk/checkout` fetches the
+ *    provider's confirmation credential through `POST …/client_action` and
+ *    completes it. The credential is never on the intent itself.
+ */
+export type PaymentIntentNextAction = {
+    type: 'faircoin_payment';
+    faircoin_payment: {
+        address: string;
+        network: NetworkType;
+        amount: string;
+        currency: 'FAIR';
+        uri: string;
+    };
+} | {
+    type: 'use_peable_sdk';
+};
+/**
+ * The chain side of a FairCoin payment. `null` on a card payment.
  *
- * Stated rather than derived, for `PAYABLE_STATUSES`' reason; the gateway's
- * test suite pins it against the transition table.
+ * `txid` and `confirmations` describe the transaction the payer reported:
+ * `null`/`0` while the intent is `requires_action`, and the watcher's count
+ * against `required_confirmations` while it is `processing`.
  */
-export declare const EXPIRABLE_STATUSES: readonly PaymentIntentStatus[];
-/** Whether an intent in this status can still expire. See {@link EXPIRABLE_STATUSES}. */
-export declare function canExpire(status: PaymentIntentStatus): boolean;
+export interface PaymentIntentFaircoin {
+    network: NetworkType;
+    /** Watch-only receive address derived per intent from the merchant's (or seller's) xpub. */
+    address: string;
+    txid: string | null;
+    confirmations: number;
+    required_confirmations: number;
+}
 export interface PaymentIntent {
     id: string;
     object: 'payment_intent';
@@ -81,83 +176,119 @@ export interface PaymentIntent {
     status: PaymentIntentStatus;
     /** Which rail moves this payment. Decides which fields below are populated. */
     rail: PaymentIntentRail;
+    payment_method_types: PaymentMethodType[];
     /**
      * Amount in the currency's SMALLEST unit as a canonical integer string.
      * Never a float, and never interpretable without `currency`: m⊜ (10^-8 FAIR)
      * on the faircoin rail, cents on a fiat one.
      */
     amount: string;
+    /** What can still be captured: the authorized amount while `requires_capture`, else `"0"`. */
+    amount_capturable: string;
+    /** What was received: the captured amount once `succeeded`, else `"0"`. */
+    amount_received: string;
+    /** The sum of SUCCEEDED refunds on this payment. Refund state lives on the refunds. */
+    amount_refunded: string;
     currency: CurrencyCode;
-    /** FairCoin rail only. `null` on a card payment, which has no network. */
-    network: NetworkType | null;
-    /**
-     * Watch-only receive address derived per-intent from the merchant xpub.
-     * FairCoin rail only; `null` on a card payment, which reserves no address.
-     */
-    address: string | null;
+    capture_method: PaymentIntentCaptureMethod;
+    setup_future_usage: PaymentIntentSetupFutureUsage | null;
+    /** `cus_…`, or the {@link Customer} with `expand[]=customer`. */
+    customer: string | Customer | null;
+    /** `pm_…`, or the {@link PaymentMethod} with `expand[]=payment_method`. Card only. */
+    payment_method: string | PaymentMethod | null;
+    /** `ch_…`, or the {@link Charge} with `expand[]=latest_charge`. Card only. */
+    latest_charge: string | Charge | null;
+    next_action: PaymentIntentNextAction | null;
+    last_payment_error: PaymentIntentLastPaymentError | null;
+    cancellation_reason: PaymentIntentCancellationReason | null;
+    canceled_at: number | null;
+    description: string | null;
+    receipt_email: string | null;
+    /** Card only. */
+    statement_descriptor_suffix: string | null;
+    shipping: Shipping | null;
+    /** The chain side. FairCoin rail only; `null` on a card payment. */
+    faircoin: PaymentIntentFaircoin | null;
+    /** The merchant's PUBLIC `merch_…`. */
     merchant_id: string;
     /**
      * The seller this payment is made ON BEHALF OF (`ca_…`), or `null` for a
      * payment to the merchant itself (ADR 0012 D5). On-behalf payments are
-     * FairCoin only, and `address` derives from that seller's own key.
-     *
-     * The seller's `ca_…`, or the {@link ConnectedAccount} itself when the
-     * request asked for `expand[]=connected_account`.
+     * FairCoin only, and `faircoin.address` derives from that seller's own key.
      */
     connected_account: string | ConnectedAccount | null;
-    txid: string | null;
-    /** On-chain confirmations. Structurally `0` for the whole life of a card payment. */
-    confirmations: number;
     client_secret: string;
     metadata: Record<string, string>;
-    /**
-     * When an UNPAID intent expires. Meaningful only while {@link canExpire}
-     * is true for `status` — see `canExpire` below.
-     */
+    /** When an UNPAID intent expires. Meaningful only while `can_expire`. */
     expires_at: number;
-    /**
-     * Whether this intent can still expire (ADR 0012 D9). `false` once the payer
-     * has reported a broadcast: a FairCoin payment that is `broadcast` or
-     * `confirming` NEVER expires, so a platform must not cancel the order for it.
-     *
-     * Optional in the type only for fixtures written against earlier versions;
-     * a gateway at this version always sends it.
-     */
-    can_expire?: boolean;
+    /** Whether this intent can still expire (ADR 0012 D9). */
+    can_expire: boolean;
     created: number;
     updated_at: number;
 }
+/** `POST /v1/payment_intents`. */
 export interface CreatePaymentIntentParams {
     /** Amount in the currency's smallest unit, as a canonical integer string. */
     amount: string;
-    /**
-     * Defaults to `'faircoin'` — the rail this gateway shipped with, so every
-     * integration written before ADR 0001 keeps working unchanged.
-     */
+    /** Defaults to `'faircoin'`. */
     rail?: PaymentIntentRail;
     /** Required on the faircoin rail; refused on the card rail, which has none. */
     network?: NetworkType;
     /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
     currency?: CurrencyCode;
+    /** Must name the rail's own type: `['card']` or `['faircoin']`. */
+    payment_method_types?: PaymentMethodType[];
+    /** `cus_…`. */
+    customer?: string;
+    /** `pm_…`, card only. A saved payment method of `customer`. */
+    payment_method?: string;
+    /** Card only: confirm in the same call (needs `payment_method`). */
+    confirm?: boolean;
+    /** Card only, with `confirm`: the customer is not present (needs `customer`). */
+    off_session?: boolean;
+    /** Card only. */
+    setup_future_usage?: PaymentIntentSetupFutureUsage;
+    /** Card only. Defaults to `'automatic'`. */
+    capture_method?: PaymentIntentCaptureMethod;
+    receipt_email?: string;
+    description?: string;
+    /** Card only. */
+    statement_descriptor_suffix?: string;
+    shipping?: ShippingParams;
     metadata?: Record<string, string>;
     expires_in_seconds?: number;
-    /**
-     * Create the payment ON BEHALF OF this connected account (`ca_…`) — the
-     * address derives from the seller's own key and the coins go straight to
-     * their wallet (ADR 0012 D5). FairCoin only: combined with `rail: 'card'` it
-     * is refused. The account's FairCoin half must be `active` and `network`
-     * must be the account's network.
-     */
+    /** FairCoin only: pay this seller (`ca_…`, ADR 0012 D5). */
     connected_account?: string;
+    /** Card only, with `confirm`: where a redirect-based challenge returns. */
+    return_url?: string;
 }
 /**
- * `POST /v1/payment_intents/:id`. Only the merchant's own `metadata` is
- * mutable on an intent: everything else is either the payment itself or the
- * state machine's, which moves only through its own operations.
- *
- * `metadata` is a PATCH: named keys are set, a key sent as `""` is removed,
- * keys not named are kept.
+ * `POST /v1/payment_intents/:id`. The merchant's own bookkeeping only —
+ * the amount, rail and status are the payment and move through their own
+ * operations. `metadata` is a PATCH (`""` unsets a key).
  */
 export interface UpdatePaymentIntentParams {
     metadata?: Record<string, string>;
+    description?: string;
+    receipt_email?: string;
+    shipping?: ShippingParams;
+}
+/** `POST /v1/payment_intents/:id/confirm` (card only). */
+export interface ConfirmPaymentIntentParams {
+    /** `pm_…`; defaults to the intent's own. */
+    payment_method?: string;
+    off_session?: boolean;
+    setup_future_usage?: PaymentIntentSetupFutureUsage;
+    return_url?: string;
+    receipt_email?: string;
+    shipping?: ShippingParams;
+}
+/** `POST /v1/payment_intents/:id/capture` (card only, `requires_capture`). */
+export interface CapturePaymentIntentParams {
+    /** Base units, at most the authorized amount; defaults to all of it. */
+    amount_to_capture?: string;
+}
+/** `POST /v1/payment_intents/:id/cancel`. */
+export interface CancelPaymentIntentParams {
+    cancellation_reason?: (typeof MERCHANT_CANCELLATION_REASONS)[number];
 }