@peable.to/contracts 3.0.0 → 4.0.0

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/events/webhookDeliveries.js

@@ -23,7 +23,7 @@ export const webhookDeliverySchema = defineObject('webhook_delivery', 'WebhookDe
     delivered: z.boolean(),
     last_status: z
         .enum(WEBHOOK_DELIVERY_STATUSES)
-        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address), was disabled first, or its stored url breaks the registration rules — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
     last_error: z
         .string()
         .optional()

package/dist/esm/resources/events/webhookEndpoints.js

@@ -26,7 +26,7 @@ const endpointShape = {
     disabled_reason: z
         .enum(WEBHOOK_ENDPOINT_DISABLED_REASONS)
         .nullable()
-        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight. `url_refused`: the stored `url` breaks the registration rules, judged before every delivery; re-enable it with a `url` that passes.'),
     api_version: z.string().describe('The wire version events are rendered with for this endpoint.'),
     metadata,
     created: unixSeconds,

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

@@ -4,6 +4,7 @@ import { defineComponent, defineObject, expandable } from '../../common/objects.
 import { expandOnlyQuery, idParam, listQuery, metadataUpdateParam } from '../../common/params.js';
 import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
+import { settlementSchema } from './refunds.js';
 import { DISPUTE_EVIDENCE_TEXT_MAX, DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_STATUSES, DISPUTE_TEXT_EVIDENCE_FIELDS, } from '../../vocabulary/payments.js';
 /**
  * Disputes (`dp_…`) — the card network holding a payment's money while a
@@ -198,4 +199,19 @@ export const disputeRoutes = [
         response: disputeSchema,
         sdk: 'disputes.close',
     }),
+    defineRoute({
+        operationId: 'retrieveDisputeSettlement',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}/settlement',
+        tag: 'Disputes',
+        summary: "Retrieve a dispute's settlement",
+        description: 'What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'disputes.settlement',
+        expandable: 'settlement',
+    }),
 ];

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,

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

@@ -7,7 +7,8 @@ import { defineRoute } from '../../route.js';
 import { isBaseUnitString } from '../../vocabulary/money.js';
 import { REFUND_ORIGINS, REFUND_REASONS, REFUND_STATUSES, SETTLEMENT_STATUSES, } from '../../vocabulary/payments.js';
 /**
- * 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).
  */
@@ -53,23 +54,42 @@ export const refundSchema = defineObject('refund', 'Refund', 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.
  */
 export const settlementSchema = defineObject('settlement', 'Settlement', z
     .object({
     object: z.literal('settlement'),
     livemode,
-    payment_intent: expandable('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: 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: 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: 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: z
         .enum(SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: amount.nullable().describe('Base units of `currency`.'),
-    fee: amount.nullable(),
-    net: signedAmount.nullable(),
-    currency: 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: 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: 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: 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: 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: unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: z
         .number()
@@ -225,6 +245,21 @@ export const refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    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: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     defineRoute({
         operationId: 'searchRefunds',
         method: 'get',

package/dist/esm/vocabulary/checkout.js

@@ -2,6 +2,23 @@
 // Checkout Sessions and Payment Links. Zod-free, so the hosted checkout and
 // the wallet import them without the schemas (`@peable.to/contracts/vocabulary`,
 // re-exported by `@peable.to/shared-types`).
+/**
+ * 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.
+ */
+export const FAIRCOIN_UNAVAILABLE_REASONS = [
+    'faircoin_wallet_missing',
+    'faircoin_network_closed',
+    'price_unavailable',
+    'temporarily_unavailable',
+];
 export const CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
 export const CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
 export const CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];

package/dist/esm/vocabulary/errors.js

@@ -55,6 +55,7 @@ export const 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.',
@@ -65,7 +66,6 @@ export const 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.',
@@ -126,6 +126,9 @@ export const 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.',
@@ -138,8 +141,7 @@ export const 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/esm/vocabulary/events.js

@@ -147,10 +147,15 @@ export const 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.
  */
 export const WEBHOOK_ENDPOINT_DISABLED_REASONS = [
     'disabled_by_merchant',
     'delivery_failures',
+    'url_refused',
 ];
 /** At most this many endpoints per merchant (per mode). */
 export const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

package/dist/esm/vocabulary/paymentMethodConfigurations.js

@@ -1,7 +1,15 @@
-// Payment method breadth on the card rail (`pmc_…`, `pmd_…`). Zod-free.
-import { FIAT_CURRENCY_CODES } from './money.js';
+// Payment method breadth (`pmc_…`, `pmd_…`): the merchant's card-rail methods,
+// and FairCoin, which is always offered (ADR 0021). Zod-free.
+import { CURRENCY_CODES, FIAT_CURRENCY_CODES } from './money.js';
 /**
- * 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
@@ -13,6 +21,7 @@ import { FIAT_CURRENCY_CODES } from './money.js';
  * scheme).
  */
 export const PAYMENT_METHOD_CONFIGURATION_TYPES = [
+    'faircoin',
     'card',
     'apple_pay',
     'google_pay',
@@ -26,18 +35,29 @@ export const 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.
  */
 export const 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).
  */
 export const PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    faircoin: CURRENCY_CODES,
     card: FIAT_CURRENCY_CODES,
     apple_pay: FIAT_CURRENCY_CODES,
     google_pay: FIAT_CURRENCY_CODES,

package/dist/types/resources/billingEngine/index.d.ts

@@ -4822,6 +4822,15 @@ export declare const billingEngineRoutes: readonly [{
             card: "card";
             faircoin: "faircoin";
         }>>;
+        faircoin: import("zod").ZodObject<{
+            available: import("zod").ZodBoolean;
+            unavailable_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
+                faircoin_wallet_missing: "faircoin_wallet_missing";
+                faircoin_network_closed: "faircoin_network_closed";
+                price_unavailable: "price_unavailable";
+                temporarily_unavailable: "temporarily_unavailable";
+            }>>;
+        }, import("zod/v4/core").$strict>;
         invoice_pdf: import("zod").ZodString;
     }, import("zod/v4/core").$strict>;
 }, {
@@ -4830,12 +4839,17 @@ export declare const billingEngineRoutes: readonly [{
     readonly path: "/v1/invoices/public/{token}/pay";
     readonly tag: "Hosted invoices";
     readonly summary: "Pay a hosted invoice";
-    readonly 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.";
+    readonly 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.";
     readonly auth: "public";
     readonly params: {
         readonly token: "The hosted invoice token (from `hosted_invoice_url`).";
     };
-    readonly body: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
+    readonly body: import("zod").ZodObject<{
+        payment_method_type: import("zod").ZodOptional<import("zod").ZodEnum<{
+            card: "card";
+            faircoin: "faircoin";
+        }>>;
+    }, import("zod/v4/core").$strict>;
     readonly response: import("zod").ZodObject<{
         object: import("zod").ZodLiteral<"public_invoice_payment">;
         payment_intent: import("zod").ZodString;

package/dist/types/resources/billingEngine/public.d.ts

@@ -59,6 +59,15 @@ export declare const publicInvoiceSchema: z.ZodObject<{
         card: "card";
         faircoin: "faircoin";
     }>>;
+    faircoin: z.ZodObject<{
+        available: z.ZodBoolean;
+        unavailable_reason: z.ZodNullable<z.ZodEnum<{
+            faircoin_wallet_missing: "faircoin_wallet_missing";
+            faircoin_network_closed: "faircoin_network_closed";
+            price_unavailable: "price_unavailable";
+            temporarily_unavailable: "temporarily_unavailable";
+        }>>;
+    }, z.core.$strict>;
     invoice_pdf: z.ZodString;
 }, z.core.$strict>;
 export type PublicInvoice = Expand<z.output<typeof publicInvoiceSchema>>;
@@ -509,7 +518,13 @@ declare module '../../common/objects' {
         'billing_portal.public_session': PublicPortalSession;
     }
 }
-export declare const payPublicInvoiceParams: z.ZodObject<{}, z.core.$strict>;
+/** How the payer pays the invoice (ADR 0021 D3). */
+export declare const payPublicInvoiceParams: z.ZodObject<{
+    payment_method_type: z.ZodOptional<z.ZodEnum<{
+        card: "card";
+        faircoin: "faircoin";
+    }>>;
+}, z.core.$strict>;
 /** A portal action on one of the customer's subscriptions. */
 export declare const portalSubscriptionParams: z.ZodObject<{
     subscription: z.ZodString;
@@ -611,6 +626,15 @@ export declare const publicBillingRoutes: readonly [{
             card: "card";
             faircoin: "faircoin";
         }>>;
+        faircoin: z.ZodObject<{
+            available: z.ZodBoolean;
+            unavailable_reason: z.ZodNullable<z.ZodEnum<{
+                faircoin_wallet_missing: "faircoin_wallet_missing";
+                faircoin_network_closed: "faircoin_network_closed";
+                price_unavailable: "price_unavailable";
+                temporarily_unavailable: "temporarily_unavailable";
+            }>>;
+        }, z.core.$strict>;
         invoice_pdf: z.ZodString;
     }, z.core.$strict>;
 }, {
@@ -619,12 +643,17 @@ export declare const publicBillingRoutes: readonly [{
     readonly path: "/v1/invoices/public/{token}/pay";
     readonly tag: "Hosted invoices";
     readonly summary: "Pay a hosted invoice";
-    readonly 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.";
+    readonly 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.";
     readonly auth: "public";
     readonly params: {
         readonly token: "The hosted invoice token (from `hosted_invoice_url`).";
     };
-    readonly body: z.ZodObject<{}, z.core.$strict>;
+    readonly body: z.ZodObject<{
+        payment_method_type: z.ZodOptional<z.ZodEnum<{
+            card: "card";
+            faircoin: "faircoin";
+        }>>;
+    }, z.core.$strict>;
     readonly response: z.ZodObject<{
         object: z.ZodLiteral<"public_invoice_payment">;
         payment_intent: z.ZodString;