@peable.to/contracts 3.0.0 → 4.0.0

package/dist/cjs/resources/payments/refunds.js

@@ -10,7 +10,8 @@ const route_1 = require("../../route");
 const money_1 = require("../../vocabulary/money");
 const payments_1 = require("../../vocabulary/payments");
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -56,23 +57,42 @@ exports.refundSchema = (0, objects_1.defineObject)('refund', 'Refund', zod_1.z
     ],
 });
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 exports.settlementSchema = (0, objects_1.defineObject)('settlement', 'Settlement', zod_1.z
     .object({
     object: zod_1.z.literal('settlement'),
     livemode: primitives_1.livemode,
-    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes (the refunded or disputed payment, for a refund or a dispute), or the PaymentIntent with `expand[]=payment_intent`.'),
+    refund: (0, objects_1.expandable)('refund', 'The `re_…` whose movement this is, or the Refund with `expand[]=refund`; `null` unless this is the settlement of a refund.').nullable(),
+    dispute: (0, objects_1.expandable)('dispute', 'The `dp_…` whose withdrawal this is, or the Dispute with `expand[]=dispute`; `null` unless this is the settlement of a dispute.').nullable(),
     status: zod_1.z
         .enum(payments_1.SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: primitives_1.amount.nullable().describe('Base units of `currency`.'),
-    fee: primitives_1.amount.nullable(),
-    net: primitives_1.signedAmount.nullable(),
-    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**. A dispute inquiry, which moves no money, and a refund that failed or was canceled are `unknown`.'),
+    gross: primitives_1.amount
+        .nullable()
+        .describe('The MAGNITUDE of the movement, never negative, in base units of `currency`: what the payment brought in, the refund took out or the dispute withdrew.'),
+    fee: primitives_1.signedAmount
+        .nullable()
+        .describe("The provider's fee on THIS movement, as the provider signs it: positive when charged to the balance (a payment's processing fee, a dispute fee), negative when returned to it (part of the original fee on some refunds). A refund's is usually `0`."),
+    net: primitives_1.signedAmount
+        .nullable()
+        .describe('The SIGNED effect on the balance: positive for a payment, negative for a refund or a dispute. Always `gross − fee` for a payment and `−gross − fee` for a refund or a dispute.'),
+    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217) every figure is in, which may differ from the payment's, refund's or dispute's."),
     available_on: primitives_1.unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: zod_1.z
         .number()
@@ -228,6 +248,21 @@ exports.refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveRefundSettlement',
+        method: 'get',
+        path: '/v1/refunds/{id}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a refund's settlement",
+        description: 'What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: params_1.expandOnlyQuery,
+        response: exports.settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     (0, route_1.defineRoute)({
         operationId: 'searchRefunds',
         method: 'get',

package/dist/cjs/vocabulary/checkout.js

@@ -4,7 +4,24 @@
 // the wallet import them without the schemas (`@peable.to/contracts/vocabulary`,
 // re-exported by `@peable.to/shared-types`).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_LINK_LIMITS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = void 0;
+exports.PAYMENT_LINK_LIMITS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = exports.FAIRCOIN_UNAVAILABLE_REASONS = void 0;
+/**
+ * Why FairCoin cannot be paid with on an order right now (ADR 0021). It is
+ * still offered — never hidden — and says why:
+ *
+ *  - `faircoin_wallet_missing` — the Peable wallet of the account that receives
+ *    (the merchant's owner, or the seller) isn't set up yet: no identity key;
+ *  - `faircoin_network_closed` — this deployment does not open payments on the
+ *    order's FairCoin network yet (ADR 0002's gate);
+ *  - `price_unavailable` — no fresh FairCoin price exists to quote a fiat order;
+ *  - `temporarily_unavailable` — whether the wallet exists could not be checked.
+ */
+exports.FAIRCOIN_UNAVAILABLE_REASONS = [
+    'faircoin_wallet_missing',
+    'faircoin_network_closed',
+    'price_unavailable',
+    'temporarily_unavailable',
+];
 exports.CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
 exports.CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
 exports.CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];

package/dist/cjs/vocabulary/errors.js

@@ -60,6 +60,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     parameter_missing: 'A required parameter is missing; `param` names it.',
     parameter_unknown: 'The request carries a parameter this route does not accept; `param` names it.',
     payment_intent_unexpected_state: 'The PaymentIntent is in a status that does not allow this operation.',
+    payment_method_locked: 'The payment method cannot be turned off or removed: FairCoin is always offered to every payer; `param` names the field.',
     payout_not_allowed: 'Payouts cannot be created for this account.',
     rate_limited: 'Too many requests; back off and retry.',
     refund_not_cancelable: 'The refund has already left a cancelable state.',
@@ -70,7 +71,6 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     test_mode_only: 'This operation exists in test mode only.',
     too_many_streams: 'Too many live streams are open for this merchant.',
     url_invalid: 'The URL is not an allowed https URL.',
-    watch_only_violation: 'The extended key carries a private key. Peable only ever accepts watch-only (public) keys.',
     webhook_endpoint_disabled: 'The webhook endpoint is disabled.',
     webhook_endpoint_limit_reached: 'The merchant already has the maximum number of webhook endpoints.',
     account_not_ready: 'The connected account cannot take this payment yet: its onboarding or a capability is incomplete.',
@@ -131,6 +131,9 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     promotion_code_minimum_amount: 'The purchase is below the promotion code minimum amount.',
     payment_method_missing: 'No payment method is available to charge.',
     faircoin_cannot_debit: 'A FairCoin invoice cannot be charged automatically: the payer signs every payment.',
+    faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
+    faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
+    faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',
     meter_event_customer_missing: 'The meter event names no customer of this merchant.',
@@ -143,8 +146,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     // Connect onboarding (ADR 0012 D3): the seller-facing refusals.
     link_expired: 'The onboarding link has expired or was already used; `refresh_url` is where the seller gets a fresh one.',
     wrong_seller: 'The onboarding link names a different Oxy account; sign in as the seller it was minted for.',
-    already_registered: 'The seller already registered a FairCoin key, and it cannot be changed.',
-    key_in_use: 'The key already receives payments for another account.',
+    already_registered: 'The seller already confirmed FairCoin payments into their Peable wallet.',
     no_faircoin_half: 'The connected account has no FairCoin half to register a key for.',
     // The dashboard routes (`/v1/dashboard/*`, Orbit): the signed-in person, not a credential.
     merchant_missing: 'The application has no merchant in this environment yet; register one (Orbit shows "Set up payments").',

package/dist/cjs/vocabulary/events.js

@@ -150,10 +150,15 @@ exports.WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
  *  - `delivery_failures`    — every delivery to it failed for three days
  *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
  *    starts the clock again.
+ *  - `url_refused`          — its stored `url` breaks the rules a URL is
+ *    registered under (https in live mode, ports 80/443, no private, loopback
+ *    or reserved address), judged again before every delivery, so Peable never
+ *    sent to it. It is re-enabled only together with a `url` that passes.
  */
 exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = [
     'disabled_by_merchant',
     'delivery_failures',
+    'url_refused',
 ];
 /** At most this many endpoints per merchant (per mode). */
 exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

package/dist/cjs/vocabulary/paymentMethodConfigurations.js

@@ -1,10 +1,18 @@
 "use strict";
-// Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
+// Payment method breadth (`pmc_…`, `pmd_…`): the merchant's card-rail methods,
+// and FairCoin, which is always offered (ADR 0021). Zod-free.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = void 0;
 const money_1 = require("./money");
 /**
- * The methods a configuration can turn on.
+ * The methods a configuration lists.
+ *
+ * `faircoin` is listed and LOCKED (ADR 0021 D2): every payer can always pay
+ * with FairCoin, so its entry is always `display_preference.value: 'on'` with
+ * `locked: true`, and a create or update that sets it `off` is refused with
+ * `payment_method_locked`. It is the chain rail, never a card-provider method:
+ * it is never pushed to the provider and never appears in a card PaymentIntent's
+ * `payment_method_types`. Every other method is the merchant's to turn on and off.
  *
  * `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
@@ -16,6 +24,7 @@ const money_1 = require("./money");
  * scheme).
  */
 exports.PAYMENT_METHOD_CONFIGURATION_TYPES = [
+    'faircoin',
     'card',
     'apple_pay',
     'google_pay',
@@ -29,18 +38,29 @@ exports.PAYMENT_METHOD_CONFIGURATION_TYPES = [
  * 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.
+ *  - `requires_card` — a wallet rides on card payments, and card is off;
+ *  - `faircoin_wallet_missing` — the Peable wallet of the account that owns
+ *    the merchant isn't set up yet (no identity key), so FairCoin cannot be
+ *    received (ADR 0021 D5); the owner sets it up in Peable;
+ *  - `faircoin_network_closed` — the deployment does not open the merchant's
+ *    FairCoin network yet (ADR 0002's gate);
+ *  - `temporarily_unavailable` — the wallet could not be checked just now.
  */
 exports.PAYMENT_METHOD_UNAVAILABLE_REASONS = [
     'provider_unsupported',
     'requires_card',
+    'faircoin_wallet_missing',
+    'faircoin_network_closed',
+    'temporarily_unavailable',
 ];
 /**
  * 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.
+ * payment, and a payer is never shown a method that would fail. FairCoin takes
+ * every currency: a `FAIR` order directly, a fiat one at a quoted price (ADR 0021).
  */
 exports.PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    faircoin: money_1.CURRENCY_CODES,
     card: money_1.FIAT_CURRENCY_CODES,
     apple_pay: money_1.FIAT_CURRENCY_CODES,
     google_pay: money_1.FIAT_CURRENCY_CODES,

package/dist/esm/resources/billingEngine/public.js

@@ -5,6 +5,7 @@ import { idParam } from '../../common/params.js';
 import { amount, currency, livemode, signedAmount, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { PORTAL_PAYMENT_METHOD_UPDATE_STATUSES } from '../../vocabulary/billingPortal.js';
+import { FAIRCOIN_UNAVAILABLE_REASONS } from '../../vocabulary/checkout.js';
 import { INVOICE_STATUSES, PUBLIC_INVOICE_PAYMENT_METHOD_TYPES } from '../../vocabulary/invoices.js';
 import { COLLECTION_METHODS, SUBSCRIPTION_STATUSES } from '../../vocabulary/subscriptions.js';
 import { billingPortalBusinessProfileSchema, billingPortalFeaturesSchema } from './billingPortal.js';
@@ -54,7 +55,17 @@ export const publicInvoiceSchema = defineObject('public_invoice', 'PublicInvoice
     paid_at: unixSeconds.nullable(),
     payment_method_types: z
         .array(z.enum(PUBLIC_INVOICE_PAYMENT_METHOD_TYPES))
-        .describe("Which rail pays it: a card through the provider's fields, FairCoin from the payer's wallet."),
+        .describe("What the payer may choose: `['card', 'faircoin']` on a fiat invoice, `['faircoin']` on a FAIR one. FairCoin is always offered (ADR 0021); on a fiat invoice it is quoted when chosen."),
+    faircoin: z
+        .object({
+        available: z.boolean(),
+        unavailable_reason: z
+            .enum(FAIRCOIN_UNAVAILABLE_REASONS)
+            .nullable()
+            .describe('Why FairCoin cannot be paid with right now; it is still shown, never hidden.'),
+    })
+        .strict()
+        .describe('Whether the payer can choose FairCoin now (ADR 0021).'),
     invoice_pdf: z.string(),
 })
     .strict());
@@ -178,7 +189,15 @@ export const portalPaymentMethodUpdateResultSchema = defineComponent('PortalPaym
 })
     .strict());
 // ---- Requests ------------------------------------------------------------------------
-export const payPublicInvoiceParams = emptyBody;
+/** How the payer pays the invoice (ADR 0021 D3). */
+export const payPublicInvoiceParams = z
+    .object({
+    payment_method_type: z
+        .enum(PUBLIC_INVOICE_PAYMENT_METHOD_TYPES)
+        .optional()
+        .describe("One of the invoice's `payment_method_types`. Default: the rail of its currency (`card` on a fiat invoice). `faircoin` on a fiat invoice quotes the amount due in FAIR for 10 minutes; paying again with the other method replaces a payment that has not started moving money."),
+})
+    .strict();
 /** A portal action on one of the customer's subscriptions. */
 export const portalSubscriptionParams = z.object({ subscription: idParam }).strict();
 /** Switch a (single-item) subscription to one of the configuration's plans, or change its quantity. */
@@ -221,7 +240,7 @@ export const publicBillingRoutes = [
         path: '/v1/invoices/public/{token}/pay',
         tag: 'Hosted invoices',
         summary: 'Pay a hosted invoice',
-        description: 'The PaymentIntent the payer completes — a card through the provider’s own fields, FairCoin from the payer’s wallet. The same invoice answers the same intent while it can still be paid.',
+        description: 'The PaymentIntent the payer completes in the method they chose — a card through the provider’s own fields, or FairCoin from the payer’s wallet (quoted on a fiat invoice, ADR 0021). The same invoice answers the same intent while it can still be paid in that method.',
         auth: 'public',
         params: invoiceToken,
         body: payPublicInvoiceParams,

package/dist/esm/resources/checkout/checkoutSessions.js

@@ -7,7 +7,7 @@ import { defineComponent, defineObject, expandable } from '../../common/objects.
 import { expandOnlyQuery, expandParam, listQuery, metadataCreateParam, metadataUpdateParam, } from '../../common/params.js';
 import { amount, currency, livemode, metadata, network, unixSeconds, } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
-import { CHECKOUT_CUSTOMER_CREATIONS, CHECKOUT_LIMITS, CHECKOUT_LOCALES, CHECKOUT_PAYMENT_STATUSES, CHECKOUT_SESSION_MODES, CHECKOUT_SESSION_STATUSES, CHECKOUT_SUBMIT_TYPES, CHECKOUT_TAX_ID_TYPES, CHECKOUT_UI_MODES, } from '../../vocabulary/checkout.js';
+import { CHECKOUT_CUSTOMER_CREATIONS, CHECKOUT_LIMITS, CHECKOUT_LOCALES, CHECKOUT_PAYMENT_STATUSES, CHECKOUT_SESSION_MODES, CHECKOUT_SESSION_STATUSES, CHECKOUT_SUBMIT_TYPES, CHECKOUT_TAX_ID_TYPES, CHECKOUT_UI_MODES, FAIRCOIN_UNAVAILABLE_REASONS, } from '../../vocabulary/checkout.js';
 import { adjustableIssues, adjustableQuantityParam, amountParam, checkoutAutomaticTaxSchema, checkoutBrandingSchema, checkoutConsentSchema, checkoutCustomerDetailsSchema, checkoutDiscountSchema, checkoutIdParam, checkoutLineItemSchema, checkoutShippingDetailsSchema, checkoutTotalDetailsSchema, collectionParams, collectionResponseFields, countryCodeParam, checkoutEmailParam, localeParam, merchantDisplaySchema, quantityParam, railSchema, redirectUrlParam, } from './shared.js';
 /**
  * Checkout Sessions (`cs_…`, Orbit Phase 3) — Stripe Checkout's session model:
@@ -30,8 +30,13 @@ const sessionFields = {
         .describe("The language checkout renders in; `null` follows the payer's browser."),
     submit_type: z.enum(CHECKOUT_SUBMIT_TYPES),
     currency,
-    rail: railSchema,
-    network: network.nullable().describe('FairCoin rail only; `null` on a card session.'),
+    rail: railSchema.describe("The rail that settles the order's currency: `faircoin` for a FAIR order, `card` for a fiat one. FairCoin is offered on every order beside it (`payment_method_types`, ADR 0021)."),
+    network: network
+        .nullable()
+        .describe('The FairCoin network a FairCoin payment of this order uses — the merchant’s (or the seller’s); `null` when the payee has no FairCoin key yet (test mode) and in `setup` mode.'),
+    payment_method_types: z
+        .array(railSchema)
+        .describe("What the payer may choose: `['card', 'faircoin']` on a fiat order, `['faircoin']` on a FAIR one. FairCoin is always offered (ADR 0021); `['card']` in `setup` mode."),
     amount_subtotal: amount,
     amount_total: amount,
     total_details: checkoutTotalDetailsSchema,
@@ -46,7 +51,6 @@ const sessionFields = {
 export const checkoutSessionSchema = defineObject('checkout_session', 'CheckoutSession', z
     .object({
     ...sessionFields,
-    payment_method_types: z.array(railSchema),
     discounts: z.array(checkoutDiscountSchema),
     customer: expandable('customer', '`cus_…` (expandable) — given on create, or created at completion.').nullable(),
     customer_email: z.string().nullable(),
@@ -90,8 +94,8 @@ export const checkoutSessionSchema = defineObject('checkout_session', 'CheckoutS
             submit_type: 'auto',
             currency: 'EUR',
             rail: 'card',
-            network: null,
-            payment_method_types: ['card'],
+            network: 'mainnet',
+            payment_method_types: ['card', 'faircoin'],
             amount_subtotal: '1999',
             amount_total: '1999',
             total_details: { amount_discount: '0', amount_tax: '0', amount_shipping: '0' },
@@ -179,6 +183,17 @@ export const checkoutSessionPublicSchema = defineComponent('CheckoutSessionPubli
         .string()
         .nullable()
         .describe("The card provider's PUBLIC key for this session's mode, so the payment fields can mount before the payment exists. `null` on FairCoin."),
+    faircoin: z
+        .object({
+        available: z.boolean(),
+        unavailable_reason: z
+            .enum(FAIRCOIN_UNAVAILABLE_REASONS)
+            .nullable()
+            .describe('Why FairCoin cannot be paid with right now; it is still shown, never hidden.'),
+    })
+        .strict()
+        .nullable()
+        .describe('Whether the payer can choose FairCoin now (ADR 0021). On a fiat order the FAIR amount is quoted when the payer chooses it (`payment_intent.faircoin.quote`). `null` in `setup` mode.'),
 })
     .strict());
 // ---- Merchant create/update ---------------------------------------------------
@@ -279,9 +294,9 @@ export const createCheckoutSessionParams = z
     payment_method_types: z
         .array(z.enum(['card', 'faircoin']))
         .min(1)
-        .max(1)
+        .max(2)
         .optional()
-        .describe("`['card']` or `['faircoin']` — the rail the line items' currency allows."),
+        .describe("Must include `faircoin`, which is always offered (ADR 0021; leaving it out is 400 `payment_method_locked`): `['card', 'faircoin']` on a fiat order, `['faircoin']` on a FAIR one. Omit it for exactly that. The fiat methods are chosen in the payment method configuration."),
     locale: localeParam.optional(),
     ui_mode: z.enum(CHECKOUT_UI_MODES).optional(),
     success_url: redirectUrlParam
@@ -425,8 +440,18 @@ export const updateCheckoutSessionPublicParams = z
         .optional(),
 })
     .strict();
-/** `POST /v1/checkout_sessions/{id}/public/confirm` takes nothing: the order is the session's. */
-export const confirmCheckoutSessionPublicParams = z.object({}).strict();
+/**
+ * `POST /v1/checkout_sessions/{id}/public/confirm` — the order is the
+ * session's; the payer only chooses how to pay it (ADR 0021 D3).
+ */
+export const confirmCheckoutSessionPublicParams = z
+    .object({
+    payment_method_type: z
+        .enum(['card', 'faircoin'])
+        .optional()
+        .describe("How the payer pays: one of the session's `payment_method_types`. Default: the rail of the order's currency (`card` on a fiat order). `faircoin` on a fiat order quotes its total in FAIR for 10 minutes; confirming again with the other method replaces a payment that has not started moving money."),
+})
+    .strict();
 /** `POST /v1/test_helpers/checkout_sessions/{id}/expire` takes nothing. */
 export const expireCheckoutSessionTestHelperParams = z.object({}).strict();
 const sessionId = { id: 'The Checkout Session (`cs_…`).' };

package/dist/esm/resources/checkout/merchants.js

@@ -17,13 +17,11 @@ export const merchantSchema = defineObject('merchant', 'Merchant', z
     livemode: livemode.describe('`true` for a `production` merchant (ADR 0017).'),
     oxy_app_id: z.string().describe('The Oxy application this merchant belongs to.'),
     environment: z.enum(MERCHANT_ENVIRONMENTS),
-    network: network
-        .nullable()
-        .describe('The FairCoin chain this merchant accepts on; `null` on a card-only merchant. Nullable together with `xpub`.'),
-    xpub: z
+    network: network.describe("The FairCoin network this merchant's payments use — its environment's: `mainnet` live, `testnet` otherwise (ADR 0021 D5)."),
+    owner_account: z
         .string()
         .nullable()
-        .describe('The watch-only account key receive addresses derive from; `null` on a card-only merchant.'),
+        .describe('The Oxy account (a person or an organization) that owns the application — its Peable wallet receives the merchant’s FairCoin (ADR 0021 D5). No key is ever registered. `null` until Peable has seen the owner.'),
     required_confirmations: z.number().int().positive(),
     display_name: z
         .string()
@@ -50,7 +48,7 @@ export const merchantSchema = defineObject('merchant', 'Merchant', z
             oxy_app_id: 'app_0193b8f2c1a87d3e9f4b',
             environment: 'development',
             network: 'testnet',
-            xpub: 'tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba',
+            owner_account: '0193b8f2-c1a8-7d3e-9f4a-5b6c7d8e9f01',
             required_confirmations: 6,
             display_name: 'Jenny’s Plants',
             created: 1793750400,
@@ -66,32 +64,21 @@ const displayName = z.string().min(1).max(64);
 const avatarFileId = z.string().min(1).max(128);
 const merchantDescription = z.string().min(1).max(512);
 /**
- * `POST /v1/merchants`. The FairCoin half is OPTIONAL — both `network` and
- * `xpub`, or neither: a card-only merchant supplies no key for a chain it
- * never intends to use.
+ * `POST /v1/merchants`. No FairCoin key and no network: the network is the
+ * environment's, and FairCoin is received into the Peable wallet of the
+ * account that owns the application (ADR 0021 D5).
  */
 export const registerMerchantParams = z
     .object({
-    network: network.optional(),
-    xpub: z
-        .string()
-        .min(1)
-        .optional()
-        .describe('A watch-only account xpub. A private extended key is refused.'),
     required_confirmations: z.number().int().positive().optional(),
     display_name: displayName.optional(),
     avatar_file_id: avatarFileId.optional(),
     description: merchantDescription.optional(),
 })
-    .strict()
-    .refine((body) => (body.network === undefined) === (body.xpub === undefined), {
-    message: 'accepting FairCoin needs both a network and a watch-only xpub, or neither — ' +
-        'omit both to register a card-only merchant',
-});
+    .strict();
 /**
- * `POST /v1/merchants/me`. `null` clears a field. The key, network and
- * environment never change: addresses already derived from the key, and the
- * test/live firewall, depend on them.
+ * `POST /v1/merchants/me`. `null` clears a field. The network and environment
+ * never change: the test/live firewall depends on them.
  */
 export const updateMerchantParams = z
     .object({

package/dist/esm/resources/checkout/paymentMethodConfigurations.js

@@ -2,15 +2,17 @@ import { z } from 'zod';
 import { listOf } from '../../common/envelopes.js';
 import { defineComponent, defineObject } from '../../common/objects.js';
 import { expandOnlyQuery, listQuery, queryBoolean } from '../../common/params.js';
-import { fiatCurrency, livemode, unixSeconds } from '../../common/primitives.js';
+import { currency, livemode, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_UNAVAILABLE_REASONS, } from '../../vocabulary/paymentMethodConfigurations.js';
 /**
- * Payment method breadth on the card rail — which methods a merchant's payers
- * are offered (`pmc_…`), and the web domains wallets may run on (`pmd_…`).
- * Both are Orbit's objects; the provider's configuration and domain are
- * bindings behind them (ADR 0016). Card data and bank credentials are entered
- * in the provider's hosted fields and never reach Peable (PCI SAQ-A).
+ * Payment method breadth — which methods a merchant's payers are offered
+ * (`pmc_…`), and the web domains wallets may run on (`pmd_…`). FairCoin is an
+ * entry of every configuration and is locked on (ADR 0021 D2); the card-rail
+ * methods are the merchant's choice. Both are Orbit's objects; the provider's
+ * configuration and domain are bindings behind them (ADR 0016). Card data and
+ * bank credentials are entered in the provider's hosted fields and never reach
+ * Peable (PCI SAQ-A).
  */
 /** The merchant's choice (`none`: Orbit's default) and what is in effect. */
 export const paymentMethodDisplayPreferenceSchema = z
@@ -25,13 +27,28 @@ export const paymentMethodConfigurationEntrySchema = defineComponent('PaymentMet
         .boolean()
         .describe('Whether payers can be offered this method: it is on and nothing prevents it.'),
     display_preference: paymentMethodDisplayPreferenceSchema,
+    locked: z
+        .boolean()
+        .describe('Whether the merchant can change it. Only `faircoin` is locked: it is always on, because every payer can always pay with FairCoin (ADR 0021), and setting it `off` is refused with `payment_method_locked`.'),
     unavailable_reason: z
         .enum(PAYMENT_METHOD_UNAVAILABLE_REASONS)
         .nullable()
         .describe('Why it cannot be offered whatever the merchant chooses; `null` when it can.'),
-    currencies: z.array(fiatCurrency).describe('The payment currencies it is offered on.'),
+    currencies: z.array(currency).describe('The payment currencies it is offered on.'),
 })
     .strict());
+/** One entry of the configuration's documented example (abbreviated currency lists). */
+function exampleEntry(preference, value, overrides = {}) {
+    const unavailable_reason = overrides.unavailable_reason ?? null;
+    return {
+        available: value === 'on' && unavailable_reason === null,
+        display_preference: { preference, value },
+        locked: false,
+        unavailable_reason,
+        currencies: ['EUR', 'USD', 'GBP'],
+        ...overrides,
+    };
+}
 const entryFields = Object.fromEntries(PAYMENT_METHOD_CONFIGURATION_TYPES.map((type) => [type, paymentMethodConfigurationEntrySchema]));
 export const paymentMethodConfigurationSchema = defineObject('payment_method_configuration', 'PaymentMethodConfiguration', z
     .object({
@@ -49,7 +66,32 @@ export const paymentMethodConfigurationSchema = defineObject('payment_method_con
     updated_at: unixSeconds,
     ...entryFields,
 })
-    .strict());
+    .strict(), {
+    examples: [
+        {
+            id: 'pmc_0193b8f2c1a87d3e9f4b',
+            object: 'payment_method_configuration',
+            livemode: false,
+            name: 'Default',
+            active: true,
+            is_default: true,
+            created: 1793750400,
+            updated_at: 1793750400,
+            faircoin: exampleEntry('on', 'on', { locked: true, currencies: ['FAIR', 'EUR', 'USD'] }),
+            card: exampleEntry('none', 'on'),
+            apple_pay: exampleEntry('none', 'on'),
+            google_pay: exampleEntry('none', 'on'),
+            sepa_debit: exampleEntry('on', 'on', { currencies: ['EUR'] }),
+            ideal: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            bancontact: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            eps: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            bizum: exampleEntry('none', 'off', {
+                currencies: ['EUR'],
+                unavailable_reason: 'provider_unsupported',
+            }),
+        },
+    ],
+});
 /** A wallet's standing on one domain. */
 export const paymentMethodDomainWalletStatusSchema = defineComponent('PaymentMethodDomainWalletStatus', z
     .object({
@@ -92,7 +134,11 @@ export const paymentMethodDomainSchema = defineObject('payment_method_domain', '
         },
     ],
 });
-/** One method's setting in a create or update. `none` returns it to Orbit's default. */
+/**
+ * One method's setting in a create or update. `none` returns it to Orbit's
+ * default. For `faircoin` only `on` and `none` are accepted, and neither stores
+ * anything: it is always on, and `off` is refused with `payment_method_locked`.
+ */
 export const paymentMethodConfigurationEntryParams = z
     .object({
     display_preference: z.object({ preference: z.enum(['on', 'off', 'none']) }).strict(),
@@ -150,7 +196,7 @@ export const paymentMethodConfigurationRoutes = [
         path: '/v1/payment_method_configurations',
         tag: 'Payment method configurations',
         summary: 'Create a payment method configuration',
-        description: 'An additional, non-default configuration. Turning `on` a method the processing provider does not offer is refused.',
+        description: 'An additional, non-default configuration. Turning `on` a method the processing provider does not offer is refused, and so is turning `faircoin` `off` (`payment_method_locked`): FairCoin is always offered.',
         auth: 'service',
         scope: 'payments:write',
         idempotent: true,
@@ -178,7 +224,7 @@ export const paymentMethodConfigurationRoutes = [
         path: '/v1/payment_method_configurations/{id}',
         tag: 'Payment method configurations',
         summary: 'Update a payment method configuration',
-        description: 'Method settings are merged; the default configuration is always active.',
+        description: 'Method settings are merged; the default configuration is always active. `faircoin` is locked on: setting it `off` is refused with `payment_method_locked`.',
         auth: 'service',
         scope: 'payments:write',
         idempotent: true,

package/dist/esm/resources/connect/balance.js

@@ -4,6 +4,7 @@ import { defineComponent, defineObject } from '../../common/objects.js';
 import { expandOnlyQuery, idParam, listQuery } from '../../common/params.js';
 import { livemode, signedAmount, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
+import { faircoinQuoteSchema } from '../payments/paymentIntents.js';
 import { BALANCE_TRANSACTION_FEE_TYPES, BALANCE_TRANSACTION_STATUSES, BALANCE_TRANSACTION_TYPES, RECONCILIATION_MISMATCH_KINDS, } from '../../vocabulary/connect.js';
 /**
  * Balance and balance transactions (ADR 0015 §3–§5).
@@ -87,6 +88,9 @@ export const balanceTransactionSchema = defineObject('balance_transaction', 'Bal
     created: unixSeconds.describe('When it happened at its source.'),
     description: z.string().nullable(),
     exchange_rate: z.number().nullable(),
+    faircoin_quote: faircoinQuoteSchema
+        .nullable()
+        .describe('A FairCoin payment of a fiat order: the quote it was priced at — its fiat equivalent (ADR 0021). Informational; no fiat moved.'),
     fee_details: z.array(balanceTransactionFeeDetailSchema),
     source: z
         .string()
@@ -118,6 +122,7 @@ export const balanceTransactionSchema = defineObject('balance_transaction', 'Bal
             created: 1793750400,
             description: 'Order 6735',
             exchange_rate: null,
+            faircoin_quote: null,
             fee_details: [{ amount: '88', currency: 'EUR', type: 'processing_fee' }],
             source: 'ch_0193b8f2f7c94b1d8e02',
             payout: null,