@peable.to/shared-types 0.12.0 → 0.14.0

package/dist/types/dispute.d.ts

@@ -1,28 +1,88 @@
+import type { Charge } from './charge';
+import type { CurrencyCode } from './money';
 import type { PaymentIntent } from './paymentIntent';
 /**
- * A dispute — the card network holding a settled payment's money while a
- * cardholder contests it.
+ * A dispute — the card network holding a payment's money while a cardholder
+ * contests it. Stripe's Dispute object (`dp_…`), Orbit's row.
  *
- * Published because `charge.dispute.created`, `charge.dispute.updated` and
- * `charge.dispute.closed` carry it as their `data.object`. It was route-local at first, with the webhook
- * carrying the PaymentIntent and the detail reachable only through
- * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
- * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
- * make a second call to learn when evidence is due is a merchant who can miss it
- * while their integration is working exactly as documented.
- *
- * It is also what the provider does. Stripe's `charge.dispute.created` carries
- * the dispute, not the charge — the parity was half-applied.
+ * `charge.dispute.created|updated|closed|funds_withdrawn|funds_reinstated`
+ * carry it as `data.object`. A dispute is a DEADLINE: `created` carries
+ * `evidence_details.due_by`, so a merchant never needs a second call to learn
+ * when their response is due.
  */
 /**
  * Where the dispute stands.
  *
  * `needs_response` and `under_review` are open; `won` and `lost` are terminal
- * and are the only two that say where the money ended up. There is deliberately
- * no `closed`: a merchant who is told a dispute "closed" without being told
- * which way has been given a notification and no information.
+ * and are the only two that say where the money ended up. The provider's
+ * `warning_*` inquiry states collapse onto the state they warn about. There is
+ * deliberately no `closed`: a merchant told a dispute "closed" without being
+ * told which way has been given a notification and no information.
  */
 export type DisputeStatus = 'needs_response' | 'under_review' | 'won' | 'lost';
+/**
+ * Why the cardholder disputed — Stripe's enum. A network reason code the
+ * provider does not map to one of these reads `general`; the row keeps the
+ * provider's own word, so nothing is lost by the normalisation.
+ */
+export declare const DISPUTE_REASONS: readonly ["bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized"];
+export type DisputeReason = (typeof DISPUTE_REASONS)[number];
+/** Map any provider reason onto {@link DisputeReason}: unknown or absent is `general`. */
+export declare function normalizeDisputeReason(reason: string | null | undefined): DisputeReason;
+/**
+ * The TEXT evidence fields — the network's names, spelled the way the rest of
+ * these contracts spell things, never a Peable paraphrase: a merchant assembling
+ * a defence is reading their acquirer's guidance, and renamed fields would make
+ * that guidance not apply.
+ *
+ * Declared ONCE. The route's schema is `satisfies Record<DisputeTextEvidenceField, …>`
+ * and the Stripe adapter's name map is a total `Record`, so a field added here
+ * does not compile until both carry it — the drift that would let a merchant
+ * send a field the network never sees.
+ */
+export declare const DISPUTE_TEXT_EVIDENCE_FIELDS: readonly ["access_activity_log", "billing_address", "cancellation_policy_disclosure", "cancellation_rebuttal", "customer_email_address", "customer_name", "customer_purchase_ip", "duplicate_charge_explanation", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "shipping_address", "shipping_carrier", "shipping_date", "shipping_tracking_number", "uncategorized_text"];
+export type DisputeTextEvidenceField = (typeof DISPUTE_TEXT_EVIDENCE_FIELDS)[number];
+/**
+ * The FILE evidence fields. Each names a `file_…` of purpose `dispute_evidence`
+ * uploaded by the same merchant; its bytes go to the provider when the response
+ * is submitted, and only then.
+ */
+export declare const DISPUTE_FILE_EVIDENCE_FIELDS: readonly ["cancellation_policy", "customer_communication", "customer_signature", "duplicate_charge_documentation", "receipt", "refund_policy", "service_documentation", "shipping_documentation", "uncategorized_file"];
+export type DisputeFileEvidenceField = (typeof DISPUTE_FILE_EVIDENCE_FIELDS)[number];
+export type DisputeEvidenceField = DisputeTextEvidenceField | DisputeFileEvidenceField;
+/**
+ * A merchant's evidence as the dispute holds it: every field, `null` when unset.
+ *
+ * Present ONLY on a live read — `GET /v1/disputes/:id` and the answers of
+ * `POST /v1/disputes/:id` and `…/close`. The text half is read from the
+ * provider, which is where a draft lives (Peable never stores it); the file half
+ * is the `file_…` ids the merchant attached. Lists and event payloads never
+ * carry it: an event is stored, and evidence carries a customer's name, email,
+ * address and correspondence.
+ */
+export type DisputeEvidence = Record<DisputeEvidenceField, string | null>;
+/**
+ * `evidence` on `POST /v1/disputes/:id`: any subset of the fields. A text field
+ * is the merchant's words; a file field is a `file_…`. An empty string UNSETS
+ * the field, as on Stripe.
+ */
+export type DisputeEvidenceParams = Partial<Record<DisputeEvidenceField, string>>;
+/** The response's bookkeeping — Stripe's `evidence_details`, plus when it was submitted. */
+export interface DisputeEvidenceDetails {
+    /**
+     * When the network stops accepting evidence, Unix seconds. `null` once the
+     * dispute is closed — there is no deadline for a decision already made.
+     */
+    due_by: number | null;
+    /** Whether any evidence has been staged or submitted. */
+    has_evidence: boolean;
+    /** Whether the deadline passed without a submission. */
+    past_due: boolean;
+    /** `0` or `1`: a response is one-shot at the network. */
+    submission_count: number;
+    /** When the response reached the network, Unix seconds; `null` while it has not. */
+    submitted_at: number | null;
+}
 export interface Dispute {
     id: string;
     object: 'dispute';
@@ -31,100 +91,47 @@ export interface Dispute {
      * `true` for a `production` merchant, `false` for every other environment.
      */
     livemode: boolean;
-    /** The disputed payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
-    payment_intent: string | PaymentIntent;
     /**
-     * Amount in the currency's smallest unit as a canonical integer string —
-     * the same encoding every other money field on these contracts uses.
-     *
-     * It is the DISPUTED amount, which may be less than the payment's: a
-     * cardholder can contest part of a charge.
+     * The DISPUTED amount in the currency's smallest unit, as a canonical integer
+     * string. It may be less than the payment's: a cardholder can contest part of
+     * a charge.
      */
     amount: string;
-    currency: string;
+    currency: CurrencyCode;
+    /** `ch_…`, or the {@link Charge} with `expand[]=charge`. */
+    charge: string | Charge | null;
+    /** The disputed payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     status: DisputeStatus;
+    reason: DisputeReason;
     /**
-     * The network's reason, verbatim and unmapped.
-     *
-     * Deliberately an open string rather than a closed set. It is the one field a
-     * merchant argues against, and a gateway paraphrase would be the words they
-     * quote while the acquirer holds different ones. `null` when the network sent
-     * none.
-     */
-    reason: string | null;
-    /**
-     * When the network stops accepting evidence, Unix seconds.
-     *
-     * `null` once the dispute is closed — there is no deadline for a decision
-     * already made, and a closed dispute still showing one would put a response
-     * in front of a merchant that can no longer be given.
-     */
-    evidence_due_at: number | null;
-    /**
-     * When the merchant's response reached the network, Unix seconds. `null` while
-     * none has been submitted.
-     *
-     * The timestamp and nothing else: the evidence itself is forwarded to the
-     * acquirer and never stored here. What it SAID is readable there, by someone
-     * with their own authorization — this gateway does not keep a copy of a
-     * customer's name, address and correspondence.
-     *
-     * Together with `evidenceDueAt` it answers the only two questions a merchant
-     * has about a live dispute: whether they still owe a response, and by when.
+     * Whether the disputed payment can still be refunded. Once it has been in
+     * full, no further funds are withdrawn because of this dispute.
      */
-    evidence_submitted_at: number | null;
+    is_charge_refundable: boolean;
+    evidence_details: DisputeEvidenceDetails;
+    /** Live reads only — see {@link DisputeEvidence}. */
+    evidence?: DisputeEvidence;
+    metadata: Record<string, string>;
     created: number;
     updated_at: number;
 }
 /**
- * A merchant's response to a dispute — the whole field set, declared once.
+ * `POST /v1/disputes/:id`.
  *
- * ## Why this is the wire contract and not four private copies
- *
- * It was four: the backend's provider port, the route's zod schema, the Stripe
- * adapter's name map, and the SDK's params type. Every one of them is the SAME
- * list, and the cost of them drifting is specific and silent — a field added to
- * three of the four is one a merchant sends, the gateway accepts, and the
- * network never sees. They find out when the dispute is decided against them.
- *
- * So the set lives here, with the wire contracts, and the other three are
- * pinned to it: `provider.ts` aliases it, `routes/disputes.ts` declares its
- * schema `satisfies Record<keyof DisputeEvidence, …>`, and the Stripe adapter's
- * map is a total `Record<keyof DisputeEvidence, …>`. Adding a field here makes
- * all three fail to compile until they carry it.
- *
- * ## What is not here
- *
- * The field NAMES are the network's, spelled the way the rest of these
- * contracts spell things. They are not a Peable vocabulary and are not mapped
- * to one: a merchant assembling a defence is reading their acquirer's guidance,
- * and a gateway that renamed the fields would make that guidance not apply.
- *
- * FILE attachments are deliberately absent. They need the provider's upload
- * API, a size and type policy, and somewhere for the bytes to live on the way
- * through — and offering half of that would let a merchant submit a defence
- * missing the receipt it rests on.
- *
- * None of it is ever stored. It carries a customer's name, their email, a
- * billing address and correspondence; it is forwarded to the acquirer and
- * forgotten. What is recorded is `evidenceSubmittedAt` and nothing more.
+ * `submit: false` (the default) STAGES the evidence: text goes to the provider
+ * as a draft, files are attached by id. `submit: true` uploads the attached
+ * files to the provider and submits everything — ONCE; a second submission is
+ * refused, because the network takes one response.
  */
-export interface DisputeEvidence {
-    product_description?: string;
-    customer_name?: string;
-    customer_email_address?: string;
-    customer_purchase_ip?: string;
-    billing_address?: string;
-    shipping_address?: string;
-    shipping_carrier?: string;
-    shipping_date?: string;
-    shipping_tracking_number?: string;
-    service_date?: string;
-    access_activity_log?: string;
-    cancellation_policy_disclosure?: string;
-    cancellation_rebuttal?: string;
-    duplicate_charge_explanation?: string;
-    refund_policy_disclosure?: string;
-    refund_refusal_explanation?: string;
-    uncategorized_text?: string;
+export interface UpdateDisputeParams {
+    evidence?: DisputeEvidenceParams;
+    /** A PATCH (`""` unsets a key). */
+    metadata?: Record<string, string>;
+    submit?: boolean;
+}
+/** `GET /v1/disputes`. */
+export interface ListDisputesParams {
+    payment_intent?: string;
+    charge?: string;
 }

package/dist/types/event.d.ts

@@ -44,8 +44,10 @@ export interface BillingObservation {
  * 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.
+ * `charge.dispute.created` is a DEADLINE (evidence is due), `updated` follows
+ * a staged or submitted response, `closed` carries the outcome, and
+ * `funds_withdrawn` / `funds_reinstated` the money's movement — never the
+ * evidence, which is not stored and so is never in an event.
  */
 export interface WebhookEventPayload {
     'payment_intent.created': PaymentIntent;
@@ -59,6 +61,10 @@ export interface WebhookEventPayload {
     'charge.dispute.created': Dispute;
     'charge.dispute.updated': Dispute;
     'charge.dispute.closed': Dispute;
+    /** The network took the disputed amount from the balance. */
+    'charge.dispute.funds_withdrawn': Dispute;
+    /** The network returned it (the dispute was won, or withdrawn by the cardholder). */
+    'charge.dispute.funds_reinstated': Dispute;
     'refund.created': Refund;
     'refund.updated': Refund;
     'refund.failed': Refund;

package/dist/types/file.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What a file is FOR. Decided at upload and never changed: the purpose is what
+ * sets the type and size policy, who may see the bytes, and which objects may
+ * reference the file — a `business_logo` is public, a `dispute_evidence` file
+ * is private and can only be attached to the merchant's own disputes.
+ */
+export declare const FILE_PURPOSES: readonly ["dispute_evidence", "business_logo", "identity_document", "additional_verification"];
+export type FilePurpose = (typeof FILE_PURPOSES)[number];
+/** The stored format, by its conventional extension (Stripe's `type`). */
+export declare const FILE_TYPES: readonly ["pdf", "png", "jpg"];
+export type FileType = (typeof FILE_TYPES)[number];
+/**
+ * Whether the bytes can be used right now.
+ *
+ *  - `available` — Oxy serves the file; it can be shown or forwarded.
+ *  - `withheld` — the file still exists and is not being served (its owner
+ *    trashed it or made it private); it can come back.
+ *  - `removed` — Oxy said the file is gone for good (deleted, taken down, lost).
+ *    The object stays so whatever referenced it can say why it stopped working.
+ */
+export declare const FILE_STATUSES: readonly ["available", "withheld", "removed"];
+export type FileStatus = (typeof FILE_STATUSES)[number];
+/**
+ * The upload policy of each purpose: the formats it takes, recognised from the
+ * bytes and never from a client's `Content-Type`, and the largest file.
+ *
+ * The provider's own ceilings, restated where the upload is parsed, so a file
+ * the card network would refuse is refused at upload — not at the one-shot
+ * dispute submission it was meant for.
+ */
+export declare const FILE_PURPOSE_POLICIES: Readonly<Record<FilePurpose, {
+    readonly types: readonly FileType[];
+    readonly max_bytes: number;
+}>>;
+/**
+ * The API's `file` object. Named `FileObject` rather than `File` so it never
+ * shadows the DOM's `File` in a browser that imports both.
+ */
+export interface FileObject {
+    /** `file_…`. */
+    id: string;
+    object: 'file';
+    /** The mode of the merchant that uploaded it (ADR 0017). */
+    livemode: boolean;
+    purpose: FilePurpose;
+    /** The name it was uploaded with, if it had a printable one. */
+    filename: string | null;
+    /** Bytes. */
+    size: number;
+    type: FileType;
+    status: FileStatus;
+    /**
+     * A public URL for a `business_logo` that is `available` — what a payer
+     * surface renders. `null` for every other purpose: evidence and identity
+     * documents are never addressable by URL, and their bytes leave Peable only
+     * to the provider they are submitted to.
+     */
+    url: string | null;
+    created: number;
+}
+/**
+ * `POST /v1/files` — exactly one source:
+ *
+ *  - the bytes, as `multipart/form-data` with a `purpose` field and a `file`
+ *    part (the SDK's `files.create({ purpose, file })` builds it);
+ *  - `oxy_file`: as JSON, an Oxy file the caller already owns (their
+ *    application's, or an account they are or act for). Its ownership is
+ *    checked once, here, and never again.
+ */
+export interface CreateFileFromOxyParams {
+    purpose: FilePurpose;
+    /** Oxy file id. */
+    oxy_file: string;
+}
+/** `GET /v1/files`. */
+export interface ListFilesParams {
+    purpose?: FilePurpose;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, decimalsFor, isCurrencyCode, } from './money';
+export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, type FiatCurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, FIAT_CURRENCY_CODES, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
 export type { ExpandParams, List, ListParams, RangeQuery } from './list';
 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';
@@ -9,9 +9,13 @@ export { type CancelSetupIntentParams, type CreateSetupIntentParams, type SetupI
 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 { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERVALS, RECURRING_USAGE_TYPES, PRICE_TAX_BEHAVIORS, TRANSFORM_QUANTITY_ROUNDS, COUPON_DURATIONS, CATALOG_LIMITS, type PriceBillingScheme, type PriceTiersMode, type PriceType, type RecurringInterval, type RecurringUsageType, type PriceTaxBehavior, type TransformQuantityRound, type CouponDuration, type ProductMarketingFeature, type Product, type DeletedProduct, type PriceTier, type PriceTransformQuantity, type PriceRecurring, type Price, type Coupon, type DeletedCoupon, type PromotionCodeRestrictions, type PromotionCode, type RecurringParams, type PriceTierParams, type PriceDataParams, type DefaultPriceDataParams, type CreateProductParams, type UpdateProductParams, type ProductListParams, type CreatePriceParams, type UpdatePriceParams, type PriceListParams, type CreateCouponParams, type UpdateCouponParams, type CouponListParams, type CreatePromotionCodeParams, type UpdatePromotionCodeParams, type PromotionCodeListParams, } from './catalog';
-export type { Dispute, DisputeEvidence, DisputeStatus } from './dispute';
+export { DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_TEXT_EVIDENCE_FIELDS, normalizeDisputeReason, type Dispute, type DisputeEvidence, type DisputeEvidenceDetails, type DisputeEvidenceField, type DisputeEvidenceParams, type DisputeFileEvidenceField, type DisputeReason, type DisputeStatus, type DisputeTextEvidenceField, type ListDisputesParams, type UpdateDisputeParams, } from './dispute';
+export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_STATUSES, FILE_TYPES, type CreateFileFromOxyParams, type FileObject, type FilePurpose, type FileStatus, type FileType, type ListFilesParams, } from './file';
+export { CARD_RAIL_PAYMENT_METHOD_TYPES, PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_CURRENCIES, type CardRailPaymentMethodType, type CreatePaymentMethodConfigurationParams, type CreatePaymentMethodDomainParams, type ListPaymentMethodDomainsParams, type PaymentMethodConfiguration, type PaymentMethodConfigurationEntry, type PaymentMethodConfigurationEntryParams, type PaymentMethodConfigurationType, type PaymentMethodDisplayPreference, type PaymentMethodDomain, type PaymentMethodDomainWalletStatus, type PaymentMethodUnavailableReason, type UpdatePaymentMethodConfigurationParams, type UpdatePaymentMethodDomainParams, } from './paymentMethodConfiguration';
 export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';
+export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, type RequestLog, type RequestLogListParams, type RequestLogMethod, type RequestLogStatusFilter, } from './requestLog';
+export { SIMULATED_FAIRCOIN_OUTCOMES, type SimulatedFaircoinOutcome, type SimulateFaircoinPaymentParams, } from './testHelpers';
 export { signWebhook, verifyWebhook } from './webhookSigner';
 export { type MerchantEnvironment, type Merchant, MERCHANT_ENVIRONMENTS, } from './merchant';
 export type { MerchantDisplay } from './merchantDisplay';

package/dist/types/merchant.d.ts

@@ -35,6 +35,13 @@ export interface Merchant {
      * Absent again once Oxy reports the file deleted or taken down.
      */
     avatar_file_id?: string;
+    /**
+     * The wide wordmark payer surfaces show in their header: a `file_…` of
+     * purpose `business_logo`. Beside the avatar, never instead of it — the avatar
+     * is the square identity image (Stripe's branding `icon`), the logo is the
+     * wordmark (Stripe's branding `logo`). Absent when unset.
+     */
+    business_logo?: string;
     description?: string;
     created: number;
     updated_at: number;

package/dist/types/merchantDisplay.d.ts

@@ -3,5 +3,7 @@ export interface MerchantDisplay {
     name: string;
     /** Resolved server-side via the canonical media chokepoint; `null` when the merchant has no avatar. */
     avatar_url: string | null;
+    /** The merchant's `business_logo`, resolved; `null` when unset or not being served. */
+    logo_url: string | null;
     description: string | null;
 }

package/dist/types/money.d.ts

@@ -1,5 +1,9 @@
 /**
- * The currencies this gateway can denominate a payment in.
+ * The currencies this gateway can denominate a payment in: FairCoin on the
+ * chain rail, and on the card rail the fiat set the provider settles for the
+ * payment methods Orbit offers (cards, wallets, SEPA Debit, iDEAL, Bancontact,
+ * EPS). A local method narrows it further per payment
+ * (`PAYMENT_METHOD_CURRENCIES` in `paymentMethodConfiguration.ts`).
  *
  * A closed set, and the database mirrors it as a CHECK
  * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
@@ -7,7 +11,7 @@
  * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
  * used to interpret a fiat amount.
  */
-export declare const CURRENCY_CODES: readonly ["FAIR", "EUR", "USD"];
+export declare const CURRENCY_CODES: readonly ["FAIR", "EUR", "USD", "GBP", "CHF", "SEK", "NOK", "DKK", "PLN", "CZK", "CAD", "AUD", "JPY"];
 export type CurrencyCode = (typeof CURRENCY_CODES)[number];
 /** Whether an arbitrary string is a currency this gateway knows. */
 export declare function isCurrencyCode(value: string): value is CurrencyCode;
@@ -15,11 +19,15 @@ export declare function isCurrencyCode(value: string): value is CurrencyCode;
  * How many decimal places each currency's smallest unit represents — i.e. an
  * amount of `1` means `10^-decimals` of one whole unit.
  *
- * FairCoin's 8 is a consensus constant and is pinned against
+ * ISO 4217's minor units for every fiat member (JPY has none). FairCoin's 8 is a consensus constant and is pinned against
  * {@link UNITS_PER_COIN} by this package's own tests, so the two spellings of
  * one fact cannot drift.
  */
 export declare const CURRENCY_DECIMALS: Readonly<Record<CurrencyCode, number>>;
+/** A currency the card rail can denominate a payment in. */
+export type FiatCurrencyCode = Exclude<CurrencyCode, 'FAIR'>;
+/** The fiat members — every currency the card rail can denominate a payment in. */
+export declare const FIAT_CURRENCY_CODES: readonly FiatCurrencyCode[];
 /** The decimal places of `currency`'s smallest unit. */
 export declare function decimalsFor(currency: CurrencyCode): number;
 export declare const UNITS_PER_COIN = 100000000n;

package/dist/types/paymentIntent.d.ts

@@ -1,3 +1,4 @@
+import type { CardRailPaymentMethodType } from './paymentMethodConfiguration';
 import type { Charge } from './charge';
 import type { Customer } from './customer';
 import type { CurrencyCode } from './money';
@@ -85,8 +86,12 @@ export declare const PAYMENT_INTENT_CAPTURE_METHODS: readonly PaymentIntentCaptu
 /** 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';
+/**
+ * The payment method types a PaymentIntent can carry: `faircoin` on the chain
+ * rail, and on the card rail the card and the local methods the provider
+ * collects in its hosted fields. Wallets (Apple Pay, Google Pay) are `card`.
+ */
+export type PaymentMethodType = 'faircoin' | CardRailPaymentMethodType;
 /** 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. */
@@ -176,7 +181,16 @@ export interface PaymentIntent {
     status: PaymentIntentStatus;
     /** Which rail moves this payment. Decides which fields below are populated. */
     rail: PaymentIntentRail;
+    /**
+     * What the payer may pay with: `['faircoin']` on the chain; on the card rail
+     * the types named at creation, or those the configuration offers in this
+     * currency.
+     */
     payment_method_types: PaymentMethodType[];
+    /** The `pmc_…` whose methods this card payment offers; `null` on the chain and when types were named. */
+    payment_method_configuration_details: {
+        id: string;
+    } | null;
     /**
      * Amount in the currency's SMALLEST unit as a canonical integer string.
      * Never a float, and never interpretable without `currency`: m⊜ (10^-8 FAIR)
@@ -236,8 +250,13 @@ export interface CreatePaymentIntentParams {
     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']`. */
+    /**
+     * `['faircoin']` on the chain rail. On the card rail, any of the card-rail
+     * types the provider offers in `currency` — instead of a configuration.
+     */
     payment_method_types?: PaymentMethodType[];
+    /** Card only: the `pmc_…` whose methods to offer. Defaults to the merchant's default configuration. */
+    payment_method_configuration?: string;
     /** `cus_…`. */
     customer?: string;
     /** `pm_…`, card only. A saved payment method of `customer`. */

package/dist/types/paymentMethodConfiguration.d.ts

@@ -0,0 +1,116 @@
+import { type FiatCurrencyCode } from './money';
+/**
+ * The methods a configuration can turn on.
+ *
+ * `apple_pay` and `google_pay` are WALLETS over a card: a payment made with one
+ * is a `card` payment, so they appear here and never in a PaymentIntent's
+ * `payment_method_types`. `bizum` is listed because merchants ask for it and the
+ * honest answer is a reason, not an absence: the provider does not offer it.
+ *
+ * Deliberately absent: the provider's own consumer wallet (its brand on Orbit's
+ * checkout, `payment-provider-boundary.md`) and giropay (discontinued by the
+ * scheme).
+ */
+export declare const PAYMENT_METHOD_CONFIGURATION_TYPES: readonly ["card", "apple_pay", "google_pay", "sepa_debit", "ideal", "bancontact", "eps", "bizum"];
+export type PaymentMethodConfigurationType = (typeof PAYMENT_METHOD_CONFIGURATION_TYPES)[number];
+/** The card-rail types a PaymentIntent can carry in `payment_method_types`. */
+export declare const CARD_RAIL_PAYMENT_METHOD_TYPES: readonly ["card", "sepa_debit", "ideal", "bancontact", "eps"];
+export type CardRailPaymentMethodType = (typeof CARD_RAIL_PAYMENT_METHOD_TYPES)[number];
+/**
+ * Why a method cannot be offered whatever the merchant chooses.
+ *
+ *  - `provider_unsupported` — the processing provider does not offer it;
+ *  - `requires_card` — a wallet rides on card payments, and card is off.
+ */
+export type PaymentMethodUnavailableReason = 'provider_unsupported' | 'requires_card';
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+export declare const PAYMENT_METHOD_CURRENCIES: Readonly<Record<PaymentMethodConfigurationType, readonly FiatCurrencyCode[]>>;
+/** The merchant's choice (`none`: Orbit's default) and what is in effect. */
+export interface PaymentMethodDisplayPreference {
+    preference: 'on' | 'off' | 'none';
+    value: 'on' | 'off';
+}
+export interface PaymentMethodConfigurationEntry {
+    /** Whether payers can be offered this method: it is on and nothing prevents it. */
+    available: boolean;
+    display_preference: PaymentMethodDisplayPreference;
+    /** Why it cannot be offered whatever the merchant chooses; `null` when it can. */
+    unavailable_reason: PaymentMethodUnavailableReason | null;
+    /** The payment currencies it is offered on. */
+    currencies: readonly FiatCurrencyCode[];
+}
+export type PaymentMethodConfiguration = {
+    /** `pmc_…`. */
+    id: string;
+    object: 'payment_method_configuration';
+    livemode: boolean;
+    name: string;
+    /** An inactive configuration cannot be named on a new PaymentIntent. The default is always active. */
+    active: boolean;
+    /** The configuration a PaymentIntent uses when it names none. Exactly one per merchant. */
+    is_default: boolean;
+    created: number;
+    updated_at: number;
+} & {
+    [K in PaymentMethodConfigurationType]: PaymentMethodConfigurationEntry;
+};
+/** One method's setting in a create or update. */
+export interface PaymentMethodConfigurationEntryParams {
+    display_preference: {
+        preference: 'on' | 'off' | 'none';
+    };
+}
+/** `POST /v1/payment_method_configurations`. */
+export type CreatePaymentMethodConfigurationParams = {
+    name?: string;
+} & {
+    [K in PaymentMethodConfigurationType]?: PaymentMethodConfigurationEntryParams;
+};
+/** `POST /v1/payment_method_configurations/:id`. */
+export type UpdatePaymentMethodConfigurationParams = CreatePaymentMethodConfigurationParams & {
+    active?: boolean;
+};
+/** A wallet's standing on one domain. */
+export interface PaymentMethodDomainWalletStatus {
+    /** `active`: the wallet can run on pages served from this domain. */
+    status: 'active' | 'inactive';
+    /** Present while `inactive`: what the wallet's verification said, in Peable's words. */
+    status_details: {
+        error_message: string;
+    } | null;
+}
+/**
+ * A web domain the merchant serves payment pages from (`pmd_…`), registered so
+ * Apple Pay and Google Pay run there. Peable's own hosted checkout needs none:
+ * its domain is Peable's.
+ */
+export interface PaymentMethodDomain {
+    id: string;
+    object: 'payment_method_domain';
+    livemode: boolean;
+    /** Lowercase hostname, no scheme, port or path. */
+    domain_name: string;
+    /** Whether wallets may run on it at all. */
+    enabled: boolean;
+    apple_pay: PaymentMethodDomainWalletStatus;
+    google_pay: PaymentMethodDomainWalletStatus;
+    created: number;
+}
+/** `POST /v1/payment_method_domains`. */
+export interface CreatePaymentMethodDomainParams {
+    domain_name: string;
+    enabled?: boolean;
+}
+/** `POST /v1/payment_method_domains/:id`. */
+export interface UpdatePaymentMethodDomainParams {
+    enabled?: boolean;
+}
+/** `GET /v1/payment_method_domains`. */
+export interface ListPaymentMethodDomainsParams {
+    domain_name?: string;
+    enabled?: boolean;
+}

package/dist/types/requestLog.d.ts

@@ -0,0 +1,40 @@
+import type { ListParams } from './list';
+/**
+ * One merchant API request, as Peable recorded it (`req_…`) — the request log
+ * Orbit and `peable logs tail` read.
+ *
+ * Its `id` IS the `Request-Id` that request was answered with, so the id a
+ * merchant quotes to support and the log row are the same thing.
+ *
+ * Deliberately thin: method, path (no query string), status, duration and the
+ * `Idempotency-Key` it carried. No body, no headers, no query string, no
+ * caller address — a log a merchant can read is a log that must not hold what
+ * a request carried. Kept 30 days.
+ */
+export declare const REQUEST_LOG_METHODS: readonly ["GET", "POST", "DELETE", "PATCH", "PUT"];
+export type RequestLogMethod = (typeof REQUEST_LOG_METHODS)[number];
+export interface RequestLog {
+    /** The request's `Request-Id` (`req_…`). */
+    id: string;
+    object: 'request_log';
+    livemode: boolean;
+    method: RequestLogMethod;
+    /** The path that was requested, without its query string. */
+    path: string;
+    /** The HTTP status it was answered with. */
+    status: number;
+    /** How long the gateway took to answer, in milliseconds. */
+    duration_ms: number;
+    /** The `Idempotency-Key` the request carried, if it carried a valid one. */
+    idempotency_key: string | null;
+    /** When it was answered, Unix seconds. */
+    created: number;
+}
+/** `status`: one code (`404`) or a class (`2xx`, `4xx`, `5xx`). */
+export type RequestLogStatusFilter = number | '2xx' | '3xx' | '4xx' | '5xx';
+export interface RequestLogListParams extends ListParams {
+    status?: RequestLogStatusFilter;
+    method?: RequestLogMethod;
+}
+/** How long a request log is kept (and served). */
+export declare const REQUEST_LOG_RETENTION_DAYS = 30;