@peable.to/contracts 3.1.0 → 4.0.0

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,

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

@@ -15,25 +15,24 @@ import { accountLinkSchema, accountRequirementsSchema } from './account.js';
  * ADR 0001 D3: a merchant integrates against Peable and never learns which
  * acquirer sat behind their seller, because the day that changes should be a
  * Peable deploy and not a merchant migration. No `acct_…`, no provider name —
- * and no seller xpub (ADR 0012 D6): an account xpub reveals every address of
- * that account, so a platform holding it would learn the seller's whole history
- * and balance. Nothing a platform does needs it; each payment carries its own
+ * and no key of any kind: a seller's FairCoin is paid into the Peable wallet
+ * of their own Oxy account (ADR 0021 D5), and each payment carries its own
  * address.
  */
 const capabilityStatus = z.enum(ACCOUNT_CAPABILITY_STATUSES);
-/** The FairCoin half of a seller's account. The seller's xpub is deliberately ABSENT (ADR 0012 D6). */
+/** The FairCoin half of a seller's account: paid into the Peable wallet of the seller's own Oxy account (ADR 0021 D5). */
 export const connectedAccountFaircoinSchema = defineComponent('ConnectedAccountFaircoin', z
     .object({
     network: network.describe('The chain the seller is paid on. Fixed when the half was opened.'),
     status: z
         .enum(CONNECTED_ACCOUNT_FAIRCOIN_STATUSES)
-        .describe('`pending`: the seller has not registered a key yet (an on-behalf payment is refused, `account_not_ready`). `active`: payments derive addresses from their key.'),
+        .describe('`pending`: the seller has not confirmed yet (an on-behalf payment is refused, `account_not_ready`). `active`: the seller confirmed, and payments go to the Peable wallet of their Oxy account.'),
     oxy_user_id: z
         .string()
-        .describe('The Oxy user who may register the key — and, once `active`, who did.'),
+        .describe('The seller’s Oxy account — the only one that may confirm, and the one whose Peable wallet receives.'),
     registered_at: unixSeconds
         .nullable()
-        .describe('When the seller registered their key. `null` while `pending`.'),
+        .describe('When the seller confirmed. `null` while `pending`.'),
 })
     .strict());
 export const connectedAccountSchema = defineObject('connected_account', 'ConnectedAccount', z
@@ -109,9 +108,9 @@ const OXY_USER_ID_MAX = 128;
  * `POST /v1/connected_accounts`: open (or return) the account for one seller.
  *
  * Two halves, at least one: the CARD half (`country` + `business_type`, both or
- * neither) and the FAIRCOIN half (`faircoin`). There is deliberately no `xpub`
- * here: the key comes from the SELLER's own session, never from the platform
- * (ADR 0012 D3).
+ * neither) and the FAIRCOIN half (`faircoin`). There is no key: the seller's
+ * FairCoin goes to their own account's Peable wallet, confirmed only from the
+ * SELLER's own session (ADR 0012 D3, ADR 0021 D5).
  */
 export const createConnectedAccountParams = z
     .object({
@@ -138,7 +137,7 @@ export const createConnectedAccountParams = z
             .string()
             .min(1)
             .max(OXY_USER_ID_MAX)
-            .describe("The seller's Oxy user id — the only person who may register the key."),
+            .describe("The seller's Oxy account id — the only one that may confirm, and whose Peable wallet receives."),
     })
         .strict()
         .optional()
@@ -162,7 +161,7 @@ export const createConnectedAccountLinkParams = z
     rail: z
         .enum(CONNECTED_ACCOUNT_RAILS)
         .optional()
-        .describe("Which half to onboard: `card` (the default) is the provider's hosted onboarding; `faircoin` is Peable's own page where the SELLER registers their watch-only key."),
+        .describe("Which half to onboard: `card` (the default) is the provider's hosted onboarding; `faircoin` is Peable's own page where the SELLER confirms, in their own Oxy session, that their FairCoin is paid into their Peable wallet."),
 })
     .strict();
 const accountIdParam = { accountId: 'The connected account (`ca_…`).' };

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

@@ -7,10 +7,10 @@ import { merchantDisplaySchema } from '../checkout/shared.js';
  * The SELLER-facing half of FairCoin connected accounts (ADR 0012 D3).
  *
  * A platform mints an onboarding link for a seller's account; the SELLER opens
- * it signed in with Oxy and registers the watch-only key their FairCoin will be
- * paid to. These routes are `auth: 'user'` — the seller's own session, never a
- * service token — because the key that decides who receives a seller's money is
- * accepted only from the seller. A platform cannot reach them at all, and the
+ * it signed in with Oxy and confirms that their FairCoin is paid into the
+ * Peable wallet of that account (ADR 0021 D5). These routes are `auth: 'user'`
+ * — the seller's own session, never a service token — because who receives a
+ * seller's money is the seller's consent. A platform cannot reach them at all, and the
  * link token alone is not enough without the session it names.
  */
 export const connectOnboardingSchema = defineObject('connect_onboarding', 'ConnectOnboarding', z
@@ -35,22 +35,11 @@ export const connectOnboardingCompleteSchema = defineComponent('ConnectOnboardin
 })
     .strict());
 /**
- * An extended public key is 111 characters in base58check; the bound is a
- * request-size guard with headroom, not a format check — the non-custody
- * firewall (`assertWatchOnly`) is.
+ * `POST /v1/connect/onboarding/{token}/faircoin` takes nothing: the seller
+ * confirms, in their own Oxy session, that their FairCoin is paid into the
+ * Peable wallet of that account (ADR 0021 D5). No key travels.
  */
-const XPUB_MAX_LENGTH = 200;
-/** `POST /v1/connect/onboarding/{token}/faircoin` — the seller's watch-only ACCOUNT xpub. */
-export const registerFaircoinKeyParams = z
-    .object({
-    xpub: z
-        .string()
-        .trim()
-        .min(1)
-        .max(XPUB_MAX_LENGTH)
-        .describe('A watch-only extended PUBLIC key. A private extended key is refused (`watch_only_violation`) and never stored.'),
-})
-    .strict();
+export const confirmFaircoinOnboardingParams = z.object({}).strict();
 const tokenParam = { token: 'The onboarding link token (the last segment of its `url`).' };
 export const connectOnboardingRoutes = [
     defineRoute({
@@ -65,15 +54,15 @@ export const connectOnboardingRoutes = [
         response: connectOnboardingSchema,
     }),
     defineRoute({
-        operationId: 'registerConnectOnboardingFaircoinKey',
+        operationId: 'confirmConnectOnboardingFaircoin',
         method: 'post',
         path: '/v1/connect/onboarding/{token}/faircoin',
         tag: 'Connect onboarding',
-        summary: "Register the seller's FairCoin key",
-        description: 'The ONLY way a key reaches a connected account: runs the non-custody firewall, consumes the link and tells the platform (`connected_account.updated`), in one transaction. The key is immutable once registered and never appears on any response.',
+        summary: 'Confirm FairCoin payments into the seller’s Peable wallet',
+        description: 'The seller, signed in as the account the link names, confirms that FairCoin paid to them goes to that account’s Peable wallet (ADR 0021 D5) — the only way a FairCoin half becomes payable. No key is sent: addresses derive from the account’s public identity key. 409 `faircoin_wallet_missing` while the account has no Peable wallet yet. Consumes the link and tells the platform (`connected_account.updated`) in one transaction.',
         auth: 'user',
         params: tokenParam,
-        body: registerFaircoinKeyParams,
+        body: confirmFaircoinOnboardingParams,
         response: connectOnboardingCompleteSchema,
     }),
 ];

package/dist/esm/resources/payments/paymentIntents.js

@@ -3,7 +3,7 @@ import { emailParam, shippingParams, shippingSchema } from '../../common/address
 import { listOf, searchResultOf } from '../../common/envelopes.js';
 import { defineComponent, defineObject, expandable } from '../../common/objects.js';
 import { clearable, expandParam, idParam, listQuery, metadataCreateParam, metadataUpdateParam, retrieveQuery, searchQuery, } from '../../common/params.js';
-import { amount, currency, livemode, metadata, network, nullableString, unixSeconds, } from '../../common/primitives.js';
+import { amount, currency, fiatCurrency, livemode, metadata, network, nullableString, unixSeconds, } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
 import { CURRENCY_CODES, isBaseUnitString, NETWORK_TYPES } from '../../vocabulary/money.js';
 import { CARD_RAIL_PAYMENT_METHOD_TYPES, CLIENT_ACTION_KINDS, MERCHANT_CANCELLATION_REASONS, PAYMENT_ERROR_TYPES, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, PAYMENT_METHOD_TYPES, } from '../../vocabulary/payments.js';
@@ -49,6 +49,39 @@ export const paymentIntentNextActionSchema = defineComponent('PaymentIntentNextA
         .strict(),
     z.object({ type: z.literal('use_peable_sdk') }).strict(),
 ]));
+/**
+ * The FairCoin price of a FIAT order (ADR 0021 D4), carried by the FairCoin
+ * payment the payer chose for it. Pricing, never exchange: the payer pays
+ * `amount` FAIR (the intent's) to the payee's own address, and no fiat moves.
+ * `rate` is for display; the FAIR amount is exactly
+ * `ceil(amount ÷ rate)` computed from the sources' own figures.
+ */
+export const faircoinQuoteSchema = defineComponent('FaircoinQuote', z
+    .object({
+    currency: fiatCurrency.describe("The order's currency."),
+    amount: amount.describe("The order's total in base units of `currency` (tax included)."),
+    rate: z.string().describe('`currency` per 1 FAIR, rounded to 10 significant digits.'),
+    price: z
+        .object({
+        source: z.literal('wfair-base'),
+        usd_per_fair: z.string().describe("The FairCoin Explorer's FAIR/USD price."),
+        observed_at: unixSeconds,
+    })
+        .strict(),
+    reference_rates: z
+        .object({
+        source: z.literal('ecb'),
+        usd_per_eur: z.string(),
+        currency_per_eur: z.string().describe('`1` for EUR.'),
+        observed_at: unixSeconds,
+    })
+        .strict()
+        .nullable()
+        .describe("The European Central Bank's reference rates; `null` for a USD order."),
+    quoted_at: unixSeconds,
+    expires_at: unixSeconds.describe('The payment expires with its quote unless already broadcast.'),
+})
+    .strict());
 /**
  * The chain side of a FairCoin payment. `txid` and `confirmations` describe the
  * transaction the payer reported: `null`/`0` while `requires_action`, the
@@ -59,10 +92,13 @@ export const paymentIntentFaircoinSchema = defineComponent('PaymentIntentFaircoi
     network,
     address: z
         .string()
-        .describe("Watch-only receive address derived per intent from the merchant's (or seller's) xpub."),
+        .describe("Receive address in the Peable wallet of the account this payment pays (the merchant's owner, or the seller), derived per payment from that account's public identity key (ADR 0021 D5)."),
     txid: nullableString,
     confirmations: z.number().int().nonnegative(),
     required_confirmations: z.number().int().nonnegative(),
+    quote: faircoinQuoteSchema
+        .nullable()
+        .describe('The fiat order this payment pays, as quoted (ADR 0021); `null` on a FAIR-priced payment.'),
 })
     .strict());
 /** Where a destination charge's funds go (`transfer_data`, ADR 0015 §2). */
@@ -193,6 +229,7 @@ export const paymentIntentSchema = defineObject('payment_intent', 'PaymentIntent
                 txid: null,
                 confirmations: 0,
                 required_confirmations: 6,
+                quote: null,
             },
             merchant_id: 'merch_0193b8f2c1a87d3e9f4a',
             connected_account: null,