@agent-cards/sdk 0.23.9 → 0.23.11

package/dist/fiserv.d.ts

@@ -17,8 +17,9 @@ export declare function isFiservCaptureHost(url: string): boolean;
 /** The pinned key with this id, in either environment, or null. */
 export declare function fiservKeyPinById(id: unknown): FiservKeyPin | null;
 /**
- * The id of the pin a paused capture's card may be sealed under (its envelope's key,
- * pinned for its endpoint's environment and for the merchant its body names), or null.
+ * The id of the pin a paused capture's card may be sealed under (its envelope's key or,
+ * for a credentials session's key, the key pinned for the merchant its body names; for its
+ * endpoint's environment and that merchant), or null.
  */
 export declare function fiservCapturePinId(url: string, body: string | null): string | null;
 /** The card-capture endpoint a Fiserv preparation names for its environment. */
@@ -59,7 +60,10 @@ export declare function isFiservSubstitution(sub: unknown): boolean;
  * The paused Fiserv capture with the approval's envelope written over the four members
  * its source.encryptionData already carries, and every other byte the frame's own. It
  * throws, writing nothing, for a body that is not the capture Agentcard covers, for any
- * substitution but Fiserv's envelope, and for an envelope under another key than the one
- * the paused capture names. Run this on a Fiserv approval, never substituteEncryptedFields.
+ * substitution but Fiserv's envelope, and for an envelope under another key than the
+ * paused capture's card goes under: the key it names or, when it names a credentials
+ * session's key, the key pinned for its merchant on the endpoint `url` names (the paused
+ * capture's own URL, which a session's key requires), whose id then replaces the session's.
+ * Run this on a Fiserv approval, never substituteEncryptedFields.
  */
-export declare function substituteFiservEnvelope(body: string, sub: Substitutions): string;
+export declare function substituteFiservEnvelope(body: string, sub: Substitutions, url?: string): string;

package/dist/fiserv.generated.d.ts

@@ -15,6 +15,7 @@ declare var FISERV_KEY_PINS: any;
 declare function fiservKeyPin(keyId: any, environment: any): any;
 declare function isFiservPinnedKeyId(keyId: any): any;
 declare function fiservKeyRefusal(keyId: any, environment: any, nowMs: any): "fiserv_key_unpinned" | "fiserv_key_inactive" | "fiserv_key_outside_validity" | null;
+declare function fiservCheckoutHost(pinId: any, origin: any): string | null;
 declare function parseFiservPublishedKey(text2: any): {
     keyId: any;
     encryptionType: any;
@@ -38,7 +39,6 @@ declare function fiservErrorIdentifiers(text2: any): {
 declare function fiservCardCaptureRefusal(request: any): "fiserv_request_invalid" | "fiserv_endpoint_invalid" | "fiserv_body_invalid" | "fiserv_body_member_not_allowed" | "fiserv_source_not_encrypted_card" | "fiserv_envelope_invalid" | "fiserv_merchant_invalid" | "fiserv_transaction_details_invalid" | "fiserv_billing_address_invalid" | "fiserv_method_invalid" | "fiserv_headers_invalid" | "fiserv_header_not_allowed" | "fiserv_content_type_invalid" | "fiserv_auth_token_type_invalid" | "fiserv_merchant_header_mismatch" | "fiserv_terminal_header_mismatch" | "fiserv_header_value_invalid" | null;
 declare function isFiservCardCaptureRequest(request: any): boolean;
 declare function isFiservPausableBody(body: any): boolean;
-declare function fiservTemplateKeyId(body: any): any;
 declare function fiservCaptureMerchant(body: any): {
     merchantId: any;
     terminalId: any;
@@ -69,5 +69,5 @@ declare function fiservSubstitutions(envelope: any): {
         [k: string]: any;
     };
 };
-declare function substituteFiservEnvelope(body: any, sub: any): string;
-export { FISERV_CARD_CAPTURE_ENDPOINTS, FISERV_ENVELOPE_CONSTANTS, FISERV_KEY_PINS, FISERV_SIMULATOR_PANS, FISERV_SUBSTITUTION, encryptFiservCard, fiservApprovedEnvelopeRefusal, fiservCaptureCardMismatch, fiservCaptureKeyRefusal, fiservCaptureMerchant, fiservCapturePin, fiservCardCaptureRefusal, fiservEnvironment, fiservErrorIdentifiers, fiservKeyPin, fiservKeyRefusal, fiservPreparationUrl, fiservPublishedKeyRefusal, fiservSubstitutionFieldsRefusal, fiservSubstitutions, fiservTemplateKeyId, fiservTimestampMs, isFiservCardCaptureRequest, isFiservCardCaptureUrl, isFiservPausableBody, isFiservPinnedKeyId, isPreparedFiservRequest, parseFiservPublishedKey, sanitizeFiservCaptureResponse, substituteFiservEnvelope };
+declare function substituteFiservEnvelope(body: any, sub: any, url?: null): string;
+export { FISERV_CARD_CAPTURE_ENDPOINTS, FISERV_ENVELOPE_CONSTANTS, FISERV_KEY_PINS, FISERV_SIMULATOR_PANS, FISERV_SUBSTITUTION, encryptFiservCard, fiservApprovedEnvelopeRefusal, fiservCaptureCardMismatch, fiservCaptureKeyRefusal, fiservCaptureMerchant, fiservCapturePin, fiservCardCaptureRefusal, fiservCheckoutHost, fiservEnvironment, fiservErrorIdentifiers, fiservKeyPin, fiservKeyRefusal, fiservPreparationUrl, fiservPublishedKeyRefusal, fiservSubstitutionFieldsRefusal, fiservSubstitutions, fiservTimestampMs, isFiservCardCaptureRequest, isFiservCardCaptureUrl, isFiservPausableBody, isFiservPinnedKeyId, isPreparedFiservRequest, parseFiservPublishedKey, sanitizeFiservCaptureResponse, substituteFiservEnvelope };

package/dist/fiserv.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: abb8663c9be443f4f09ced0b06df7e3997cfbc7cae7bea1a1c341af1cea93524
+// artifact-sha256: 0e3d991aa970b75f82e71cdec7a1c8dd9211626cd1821485492de7dfc37aad96
 // src/fiserv-environment.js
 var FISERV_CARD_CAPTURE_ENDPOINTS = /* @__PURE__ */ Object.freeze({
     production: "https://connect.fiservapis.com/ch/payments-vas/v1/card-capture",
@@ -320,12 +320,16 @@ var FISERV_KEY_PINS = /* @__PURE__ */ deepFreeze([
         id: "homedepot_orangepay",
         merchant: "Home Depot",
         environment: "production",
-        // Empty until a card-free dry run records the merchantId Home Depot's
-        // capture carries, so this key encrypts no card yet. env.js names
-        // merchantId TZOPBKED, but that is what OrangePay sends its own authenticate
-        // call and may not be the Commerce Hub id in the capture body, and the
-        // payment step has never been observed.
-        merchantIds: [],
+        // The Commerce Hub merchant OrangePay's capture names on Blinds.com, Home
+        // Depot's blinds store, and on homedepot.com: merchantDetails.merchantId
+        // TZOPBKED with terminal 12, which OrangePay's frame hands the Secure Data
+        // Capture submit, read card-free from Blinds.com's payment step on 2026-09-30,
+        // 2026-10-06 and 2026-10-11, and the id env.js names for both stores.
+        merchantIds: ["TZOPBKED"],
+        // Blinds.com's checkout, where those three captures were read. homedepot.com
+        // runs the same OrangePay page and its env.js names the same merchant, but no
+        // capture was read there, so it is not listed and its approval names no host.
+        checkoutOrigins: ["https://www.blinds.com"],
         keyId: "d51d5faeb0261f664c99aac27cd131db",
         spki: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArobUom7fqw1aWE03z0OFQhnwzXPmh/rw0GxxEEdDsV07ysH/xtEAggNO46sWeWh8UEBat/mleL6wart8XEDkP1z67mSBhvu9Y3MqrbTMilxkb7NxdsMW26ukYx7Q9QGq+llTuapwBhLeU3uVsu0keUcs1kqc32fisCMv6hd7Nvh9niVp6dxPpqWnlmrB3PqQI/Y9wIOKlLtQ8n/1b5V3UJUjEXgJlDBzBn13ATj3vrl2aJxey6A99DL75md8RBF/rd2x/OxPKHkqWQWbRIgd++dtjxLVUYe5vRnq8OtqvrWdY0SCRoG61PgHqIPvoaokovJNi8utp95WuCww5jX8MQIDAQAB",
         spkiSha256: "49c3ac40078bfb4d5a08ebf1f6009d0b4b25b9cac58a4046fe64f1fa917a0e84",
@@ -341,6 +345,8 @@ var FISERV_KEY_PINS = /* @__PURE__ */ deepFreeze([
         // The sandbox merchant the key was generated under, which every Wave 0
         // capture named.
         merchantIds: ["100008000003683"],
+        // No merchant's checkout: the sandbox proof pays on Agentcard's own fixture page.
+        checkoutOrigins: [],
         keyId: "77eba5e58f007456ce2c35527bec2877",
         spki: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqbsaa0wpsHUuNIAr5LVYAbID77PB4d0qYnaIsTFGa0JZMIj/egbfdkl4DCaEhV3dzRDMivr+EB5643Xut00lT+SoPonc0Hps+Z5ejcVIZrtIvx/kSxJEqYK70HZHxJewh6P5qFUb+2ZPLSWQQpMqNMpDQhlISt3XtnO1JWmTvCUrjs4PKyVbexIq7+Di36HzwAnatSRP+mfgBnRsXnFmF/oOZKijsCYswqfomIom8eb9kpU1mVuSCPXmxivPOXPdFARFGd23PhdHpLhx0E7OIXpm2xEDmizeit56KVrP4PUHT08tZ4x26cSj7Po1oFpJ4XtsjSrXxmJCdE/LQFIZUwIDAQAB",
         spkiSha256: "7a62942573e251eeffa856ce6f307d8684aad39eec43e9eb48badb450619296a",
@@ -371,6 +377,15 @@ function fiservKeyRefusal(keyId, environment, nowMs) {
 function fiservPinServesMerchant(entry, merchantId) {
     return !!entry && Array.isArray(entry.merchantIds) && typeof merchantId === "string" && entry.merchantIds.includes(merchantId);
 }
+function fiservMerchantPins(merchantId, environment) {
+    return FISERV_KEY_PINS.filter((entry) => (environment === null || entry.environment === environment) && fiservPinServesMerchant(entry, merchantId));
+}
+function fiservCheckoutHost(pinId, origin) {
+    const entry = typeof pinId === "string" ? FISERV_KEY_PINS.find((pin2) => pin2.id === pinId) : null;
+    if (!entry || typeof origin !== "string" || !entry.checkoutOrigins.includes(origin))
+        return null;
+    return new URL(origin).host;
+}
 function pinnedSpki(entry) {
     const der = entry && typeof entry.spki === "string" ? decodeBase64(entry.spki) : null;
     return der && sha256Hex(der) === entry.spkiSha256 ? der : null;
@@ -512,6 +527,7 @@ var decodedLength = (value, min, max) => {
 };
 var IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 var KEY_ID = /^[A-Za-z0-9][A-Za-z0-9-]{7,63}$/;
+var SESSION_KEY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 var BODY_LIMIT = 65536;
 var TOP_LEVEL = ["source", "merchantDetails", "transactionDetails", "billingAddress"];
 var ENVELOPE = ["keyId", "encryptedKey", "encryptionBlock", "aesIv", "aesTagLength", "encryptionType", "encryptionTarget"];
@@ -696,10 +712,6 @@ function isNonCardCapture(body) {
 function isFiservPausableBody(body) {
     return !isNonCardCapture(body);
 }
-function fiservTemplateKeyId(body) {
-    const parsed = readCaptureBody(body);
-    return parsed && captureBodyRefusal(parsed) === null ? parsed.source.encryptionData.keyId : null;
-}
 function fiservCaptureMerchant(body) {
     const parsed = readCaptureBody(body);
     if (!parsed || captureBodyRefusal(parsed) !== null)
@@ -719,12 +731,24 @@ function capturePin(capture) {
     const refusal = captureBodyRefusal(body);
     if (refusal)
         return { refusal };
-    const pin2 = fiservKeyPin(body.source.encryptionData.keyId, environment);
-    if (!pin2)
+    const { keyId } = body.source.encryptionData;
+    const { merchantId } = body.merchantDetails;
+    const pinned = fiservKeyPin(keyId, environment);
+    if (pinned)
+        return fiservPinServesMerchant(pinned, merchantId) ? { pin: pinned, environment } : { refusal: "fiserv_key_merchant_unlisted" };
+    if (!SESSION_KEY_ID.test(keyId))
         return { refusal: "fiserv_key_unpinned" };
-    if (!fiservPinServesMerchant(pin2, body.merchantDetails.merchantId))
-        return { refusal: "fiserv_key_merchant_unlisted" };
-    return { pin: pin2, environment };
+    const pins = fiservMerchantPins(merchantId, environment);
+    return pins.length === 1 ? { pin: pins[0], environment } : { refusal: "fiserv_key_merchant_unlisted" };
+}
+function sealingKeyId(body, environment) {
+    const { keyId } = body.source.encryptionData;
+    if (isFiservPinnedKeyId(keyId) || !SESSION_KEY_ID.test(keyId))
+        return keyId;
+    if (!environment)
+        return null;
+    const pins = fiservMerchantPins(body.merchantDetails.merchantId, environment);
+    return pins.length === 1 ? pins[0].keyId : null;
 }
 function fiservCapturePin(capture) {
     return capturePin(capture).pin ?? null;
@@ -808,7 +832,7 @@ function fiservSubstitutions(envelope) {
     return { encoding: "json", at: FISERV_SUBSTITUTION.at, fields };
 }
 var SUBSTITUTION_MEMBERS = ["encoding", "at", "fields", "remove"];
-function substituteFiservEnvelope(body, sub) {
+function substituteFiservEnvelope(body, sub, url = null) {
     if (!isPlainObject(sub) || !onlyKeys(sub, SUBSTITUTION_MEMBERS) || sub.encoding !== "json" || sub.at !== FISERV_SUBSTITUTION.at || own3(sub, "remove") && !(Array.isArray(sub.remove) && sub.remove.length === 0)) {
         throw new Error("Refusing to substitute: not a Fiserv envelope substitution.");
     }
@@ -820,11 +844,17 @@ function substituteFiservEnvelope(body, sub) {
     const bodyRefusal = parsed ? captureBodyRefusal(parsed) : "fiserv_body_invalid";
     if (bodyRefusal)
         throw new Error(`Refusing to substitute: ${bodyRefusal}.`);
-    const envelope = parsed.source.encryptionData;
-    if (envelope.keyId !== fields.keyId)
+    const environment = url === null ? null : fiservEnvironment(url) ?? null;
+    if (url !== null && !environment)
+        throw new Error("Refusing to substitute: the paused capture is not on a Fiserv card-capture endpoint.");
+    if (!environment && SESSION_KEY_ID.test(parsed.source.encryptionData.keyId)) {
+        throw new Error("Refusing to substitute: a credentials session's key is written over only with the capture's own URL.");
+    }
+    if (sealingKeyId(parsed, environment) !== fields.keyId)
         throw new Error("Refusing to substitute: the envelope names another key than the paused capture.");
+    const envelope = parsed.source.encryptionData;
     for (const name of FISERV_SUBSTITUTION.fields)
         envelope[name] = fields[name];
     return JSON.stringify(parsed);
 }
-export { FISERV_CARD_CAPTURE_ENDPOINTS, FISERV_ENVELOPE_CONSTANTS, FISERV_KEY_PINS, FISERV_SIMULATOR_PANS, FISERV_SUBSTITUTION, encryptFiservCard, fiservApprovedEnvelopeRefusal, fiservCaptureCardMismatch, fiservCaptureKeyRefusal, fiservCaptureMerchant, fiservCapturePin, fiservCardCaptureRefusal, fiservEnvironment, fiservErrorIdentifiers, fiservKeyPin, fiservKeyRefusal, fiservPreparationUrl, fiservPublishedKeyRefusal, fiservSubstitutionFieldsRefusal, fiservSubstitutions, fiservTemplateKeyId, fiservTimestampMs, isFiservCardCaptureRequest, isFiservCardCaptureUrl, isFiservPausableBody, isFiservPinnedKeyId, isPreparedFiservRequest, parseFiservPublishedKey, sanitizeFiservCaptureResponse, substituteFiservEnvelope };
+export { FISERV_CARD_CAPTURE_ENDPOINTS, FISERV_ENVELOPE_CONSTANTS, FISERV_KEY_PINS, FISERV_SIMULATOR_PANS, FISERV_SUBSTITUTION, encryptFiservCard, fiservApprovedEnvelopeRefusal, fiservCaptureCardMismatch, fiservCaptureKeyRefusal, fiservCaptureMerchant, fiservCapturePin, fiservCardCaptureRefusal, fiservCheckoutHost, fiservEnvironment, fiservErrorIdentifiers, fiservKeyPin, fiservKeyRefusal, fiservPreparationUrl, fiservPublishedKeyRefusal, fiservSubstitutionFieldsRefusal, fiservSubstitutions, fiservTimestampMs, isFiservCardCaptureRequest, isFiservCardCaptureUrl, isFiservPausableBody, isFiservPinnedKeyId, isPreparedFiservRequest, parseFiservPublishedKey, sanitizeFiservCaptureResponse, substituteFiservEnvelope };

package/dist/fiserv.js

@@ -36,8 +36,9 @@ export function fiservKeyPinById(id) {
     return typeof id === 'string' ? core.FISERV_KEY_PINS.find((pin) => pin.id === id) ?? null : null;
 }
 /**
- * The id of the pin a paused capture's card may be sealed under (its envelope's key,
- * pinned for its endpoint's environment and for the merchant its body names), or null.
+ * The id of the pin a paused capture's card may be sealed under (its envelope's key or,
+ * for a credentials session's key, the key pinned for the merchant its body names; for its
+ * endpoint's environment and that merchant), or null.
  */
 export function fiservCapturePinId(url, body) {
     return core.fiservCapturePin({ url, body })?.id ?? null;
@@ -96,9 +97,12 @@ export function isFiservSubstitution(sub) {
  * The paused Fiserv capture with the approval's envelope written over the four members
  * its source.encryptionData already carries, and every other byte the frame's own. It
  * throws, writing nothing, for a body that is not the capture Agentcard covers, for any
- * substitution but Fiserv's envelope, and for an envelope under another key than the one
- * the paused capture names. Run this on a Fiserv approval, never substituteEncryptedFields.
+ * substitution but Fiserv's envelope, and for an envelope under another key than the
+ * paused capture's card goes under: the key it names or, when it names a credentials
+ * session's key, the key pinned for its merchant on the endpoint `url` names (the paused
+ * capture's own URL, which a session's key requires), whose id then replaces the session's.
+ * Run this on a Fiserv approval, never substituteEncryptedFields.
  */
-export function substituteFiservEnvelope(body, sub) {
-    return core.substituteFiservEnvelope(body, sub);
+export function substituteFiservEnvelope(body, sub, url) {
+    return core.substituteFiservEnvelope(body, sub, url ?? null);
 }

package/dist/lifecycle.d.ts

@@ -106,7 +106,14 @@ export interface CheckoutController {
     resume(result: ResumeResult): Promise<void>;
     /** Await device consent before the caller starts the first native Pay action. One use per attachment. */
     prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
-    /** Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment. */
+    /**
+     * Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment.
+     * A checkout that already ended keeps its state and reason (`completed`, `declined`, `failed`,
+     * `timed_out`, `unsupported`, `cancelled`, `outcome_unknown`) once no card request is in flight, or
+     * once the request in flight has its own outcome recorded (a cancel from onStateChange or the `failed` event).
+     * Any other reads `outcome_unknown` once a card request is in flight or an authorization exists,
+     * and `cancelled` before, with reason `local_cancel`.
+     */
     cancel(): void;
     /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
     reconcile(): Promise<Readonly<CheckoutState>>;
@@ -131,6 +138,7 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private state;
     private held;
     private active;
+    private settled;
     private cancelled;
     private merchantAborted;
     private unboundStripeToken;

package/dist/lifecycle.js

@@ -2,6 +2,20 @@ import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutEr
 import { CardEndpointRefusedError } from './card-endpoint.js';
 import { parseOwnedShopReceipt, OWNED_SHOP_SKU, OWNED_SHOP_AMOUNT_CENTS, OWNED_SHOP_CURRENCY } from './owned-shop.generated.js';
 import { isWspayChallenge } from './wspay.js';
+/**
+ * The statuses that end an attempt: its outcome is known (`completed`, `declined`, `failed`,
+ * `timed_out`, `unsupported`, `cancelled`), or the SDK already reported it unknown with its own
+ * reason (`outcome_unknown`). cancel() stops and holds the attachment but leaves these as they are,
+ * so an application that cancels at cleanup still reads the outcome, once no card request is in
+ * flight or the request in flight has its own outcome recorded. A checkout not started (`idle`) or
+ * still under way (`awaiting_approval`, `ready_to_submit`, `awaiting_merchant`, `requires_user_action`,
+ * or any status while a request whose outcome is not recorded is in flight) has none:
+ * cancelling it reads `outcome_unknown` once a request is in flight or an authorization exists,
+ * since a card or a token may still move, and `cancelled` before.
+ */
+const FINAL_STATUSES = new Set([
+    'completed', 'declined', 'failed', 'timed_out', 'unsupported', 'cancelled', 'outcome_unknown',
+]);
 /** How many times one approval's card-free Stripe confirmation may be checked before it is simply held. */
 export const MAX_STRIPE_CONTINUATION_CHECKS = 3;
 /**
@@ -29,6 +43,10 @@ export class CheckoutLifecycle {
     state = { status: 'idle', authorizationId: null };
     held = false;
     active = false;
+    // The card request in flight has its own outcome recorded (failed(), handedOff(), merchantNeverRetried()), and
+    // the adapter has yet to call end(): it still answers the page and tidies up. An application that cancels
+    // from onStateChange or the `failed` event runs in that window, and the request waits on nothing there.
+    settled = false;
     cancelled = false;
     merchantAborted = false;
     unboundStripeToken = false;
@@ -113,6 +131,7 @@ export class CheckoutLifecycle {
     }
     begin() {
         this.active = true;
+        this.settled = false;
         this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
     }
     end() { this.active = false; }
@@ -137,9 +156,20 @@ export class CheckoutLifecycle {
         catch { /* observer only */ }
     }
     cancel() {
+        // A checkout that already ended keeps its outcome: a refusal the processor gave, a payment the
+        // merchant confirmed, an unknown the SDK already named. Stopping the attachment afterwards
+        // changes nothing that happened, so only an attempt still under way reads as stopped here.
+        // A card request still in flight is under way whatever the state says: its authorization can
+        // still be approved on the cardholder's device, so cancelling it reads outcome_unknown as before.
+        // One whose own outcome is recorded (settled) is not: the adapter only has to finish answering
+        // the page, so a cancel from onStateChange or the `failed` event keeps that outcome.
+        // Read before the abort, so the state the application saw decides.
+        const ended = FINAL_STATUSES.has(this.state.status) && (!this.active || this.settled);
         this.cancelled = true;
         this.held = true;
         this.abort.abort();
+        if (ended)
+            return;
         this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
     }
     /** The exact browser request is gone; a late approval cannot reopen it. */
@@ -180,6 +210,7 @@ export class CheckoutLifecycle {
     merchantNeverRetried(authorizationId) {
         if (this.cancelled)
             return;
+        this.settled = true;
         this.set({ ...this.state, authorizationId, status: 'declined', reason: 'merchant_never_retried' });
     }
     /**
@@ -324,6 +355,7 @@ export class CheckoutLifecycle {
     handedOff(replay) {
         if (this.merchantAborted)
             return;
+        this.settled = true;
         if (this.ownedShopOrderId) {
             this.held = true;
             this.set({ status: 'completed', authorizationId: replay.authorizationId, mode: 'token', orderId: this.ownedShopOrderId });
@@ -359,6 +391,8 @@ export class CheckoutLifecycle {
     failed(error, handoffStarted = false) {
         if (this.cancelled)
             return;
+        // Before any state is set, so an observer that cancels from onStateChange sees the outcome as recorded.
+        this.settled = true;
         if (this.merchantAborted) {
             this.merchantRequestAborted();
             return;

package/dist/payrails.d.ts

@@ -3,24 +3,30 @@ export { PAYRAILS_CAPABILITY, PAYRAILS_PSP };
 /**
  * How the pre-claim gate reads a POST to a Payrails host: `card` for a card save on a save URL
  * (data.encryptedData present, payment-core's pause predicate), `card_payment` for a payment that
- * carries an encrypted card inside paymentComposition, and null for anything else, which continues.
+ * carries an encrypted card inside paymentComposition, the card form's included, and null for
+ * anything else, which continues.
  */
 export declare function payrailsRequestKind(url: string, method: string, body: string): 'card' | 'card_payment' | null;
+/** Whether `url` is exactly a payment-acceptance execution's authorize link on a Payrails API host, where a card-form payment may pause. */
+export declare function isPayrailsPaymentUrl(url: string): boolean;
 /**
  * Why a Payrails request was aborted, reported as the `reason` of the `unsupported_checkout` event:
  *   unsupported_payrails_card_payment  a payment that sends an encrypted card inside
- *                                      paymentComposition; the attachment holds
+ *                                      paymentComposition in a shape this build does not take
+ *                                      over; the attachment holds
  *   payrails_request_malformed, payrails_not_card_save, payrails_jwe_malformed,
  *   payrails_future_usage_refused, payrails_card_on_file_consent_required
- *                                      a card save payment-core's guard refuses; the attachment holds
- *   payrails_session_unavailable       no captured session matches the save; that request only
+ *                                      a card save or card-form payment payment-core's guard
+ *                                      refuses; the attachment holds
+ *   payrails_session_unavailable       no captured session matches the save or payment; that
+ *                                      request only
  *   payrails_key_invalid, payrails_key_mismatch
  *                                      the captured key cannot be the frame's; that request only
  */
 export type PayrailsUnsupportedReason = 'unsupported_payrails_card_payment' | 'payrails_request_malformed' | 'payrails_not_card_save' | 'payrails_jwe_malformed' | 'payrails_future_usage_refused' | 'payrails_card_on_file_consent_required' | 'payrails_session_unavailable' | 'payrails_key_invalid' | 'payrails_key_mismatch';
-/** Refusals of the save's own shape: the page's next save would be the same, so the attachment holds. */
+/** Refusals of the request's own shape: the page's next one would be the same, so the attachment holds. */
 export declare const PAYRAILS_HOLDING_REASONS: readonly PayrailsUnsupportedReason[];
-/** What the agent reads when a save's session cannot be bound. Not shown to the cardholder. */
+/** What the agent reads when a card request's session cannot be bound. Not shown to the cardholder. */
 export declare const PAYRAILS_SESSION_MESSAGE = "Payrails session expired, reload the checkout";
 /** Captured sessions kept per attachment; the oldest is dropped first. */
 export declare const PAYRAILS_CAPTURE_LIMIT = 8;
@@ -34,29 +40,50 @@ export declare const PAYRAILS_INIT_BODY_LIMIT: number;
 export declare const PAYRAILS_PENDING_READ_MS = 1000;
 /** Fetch interception patterns for every Payrails host, armed only for an org the API served Payrails to. */
 export declare const PAYRAILS_GUARD_PATTERNS: readonly string[];
-/** One captured Payrails session: the init payload's binding fields and its key. Never logged. */
+/**
+ * One captured Payrails session: the init payload's binding fields and its key. Never logged.
+ * `executionId` is the payment-acceptance execution the payload carries (data.execution.id), or null
+ * when it carries none, and then no card-form payment binds to the session.
+ */
 export interface PayrailsSession {
     readonly token: string;
     readonly holderReference: string;
     readonly providerConfigId: string;
     readonly saveInstrumentHref: string;
+    readonly executionId: string | null;
     readonly encryptionPublicKey: string;
     readonly seenAt: number;
 }
 type SessionFields = Omit<PayrailsSession, 'seenAt'>;
-/** What the create carries beside a Payrails save: the session key its page encrypted under. */
+/**
+ * What the create carries beside a Payrails card request: the session key its page encrypted under,
+ * and for a card-form payment the session's holderReference, which the payment's JWE carries.
+ */
 export interface PayrailsSidecar {
     readonly encryption_public_key: string;
+    readonly holder_reference?: string;
 }
+/** How deep inside an answer an init payload is looked for, and how many of its objects at most. */
+export declare const PAYRAILS_INIT_SEARCH_DEPTH = 8;
+export declare const PAYRAILS_INIT_SEARCH_NODES = 4096;
 /**
- * Every Payrails init payload one JSON answer body carries: the body itself, or its members one
- * level down (an object's values or an array's items). An init payload is `{version, data}` whose
- * `data` decodes to JSON with a token, a holderReference and a vaultConfiguration naming its
- * providerConfigId, its encryptionPublicKey and a saveInstrument href on a Payrails save URL.
+ * Every Payrails init payload one JSON answer body carries: the body itself, or any object or array
+ * item inside it at most PAYRAILS_INIT_SEARCH_DEPTH levels down, read breadth first over at most
+ * PAYRAILS_INIT_SEARCH_NODES of them. Blacklane's session answer is the payload itself; FlixBus's
+ * /payment/configuration/list carries it six levels down
+ * (options.initialState.selection.paymentMethods[i].paymentToken). An init payload is
+ * `{version, data}` whose `data` decodes to JSON with a token, a holderReference and a
+ * vaultConfiguration naming its providerConfigId, its encryptionPublicKey and a saveInstrument href
+ * on a Payrails save URL; nothing inside one is read further.
  */
 export declare function payrailsInitSessions(body: unknown): SessionFields[];
 /** Whether an answer may carry an init payload worth reading: a 2xx XHR or fetch with a JSON type. */
 export declare function payrailsInitCandidate(resourceType: unknown, status: unknown, contentType: unknown): boolean;
+/** The key and holderReference a paused Payrails card request binds to. */
+export interface PayrailsBinding {
+    readonly key: string;
+    readonly holderReference: string;
+}
 /**
  * The Payrails sessions one attachment has seen, in memory only: at most PAYRAILS_CAPTURE_LIMIT,
  * each dropped PAYRAILS_CAPTURE_TTL_MS after it was first seen. Nothing here is ever logged or
@@ -83,13 +110,27 @@ export declare class PayrailsSessionCapture {
      * The session key for a paused card save: the key of the captured session whose token is the
      * save's bearer token, whose saveInstrument href is the save's URL, and whose holderReference and
      * providerConfigId are the body's, first seen at most PAYRAILS_SESSION_MAX_AGE_MS before `now`.
-     * Null when none matches, or when matching sessions disagree on the key.
+     * Null when none matches, or when matching sessions disagree on the key. bind() reads a card-form
+     * payment too.
      */
     keyFor(request: {
         url: string;
         headers?: Record<string, string>;
         body: string | null;
     }, now?: number): string | null;
+    /**
+     * The session a paused card request binds to: its key and holderReference. A save binds as keyFor
+     * says. A card-form payment binds to the captured session whose token is the payment's bearer
+     * token, whose execution is the one the authorize link names, whose saveInstrument href is on the
+     * link's host, and whose providerConfigId is the payment's vaultProviderConfigId, first seen at most
+     * PAYRAILS_SESSION_MAX_AGE_MS before `now`. Null when none matches, or when matching sessions
+     * disagree on the key or the holderReference.
+     */
+    bind(request: {
+        url: string;
+        headers?: Record<string, string>;
+        body: string | null;
+    }, now?: number): PayrailsBinding | null;
     /** How many sessions are held; for tests. */
     get size(): number;
     private prune;
@@ -116,18 +157,37 @@ export declare function isPayrailsStaticHost(rawUrl: string): boolean;
  * to, else the refusal code. A guard that throws refuses.
  */
 export declare function payrailsSaveRefusal(body: string): PayrailsUnsupportedReason | null;
+/**
+ * payment-core's judgement of a card-form payment's own shape, before any session is looked up:
+ * null when it is the SDK's own payment that pays once, else the reason. A payment that stores the
+ * card at the merchant reads as payrails_card_on_file_consent_required, one that sets up a
+ * subscription as payrails_future_usage_refused, and a ciphertext of another shape as
+ * payrails_jwe_malformed; every other shape (a stored card's CVC, a split or installment payment, a
+ * preferred scheme) is one this build does not take over, unsupported_payrails_card_payment. A guard
+ * that throws refuses.
+ */
+export declare function payrailsPaymentRefusal(body: string): PayrailsUnsupportedReason | null;
 /**
  * The key check for a bound session: null when the captured key is an RSA-2048, 3072 or 4096 key as
- * long as the key the page's frame wrapped for this save, else the refusal code.
+ * long as the key the page's frame wrapped for this save or payment, else the refusal code.
  */
 export declare function payrailsKeyRefusal(key: string, body: string): PayrailsUnsupportedReason | null;
 /**
- * The only answer the page may receive for an approved Payrails save: Payrails' 201 for a card
- * instrument, rebuilt from payment-core's allow-list (the BIN cut to six digits), under a JSON
- * content type. Null for anything else.
+ * The only answer the page may receive for an approved Payrails card request, by the paused `url`: for
+ * a save, Payrails' 201 for a card instrument, rebuilt from payment-core's allow-list (the BIN cut to
+ * six digits); for a card-form payment, Payrails' 2xx for the authorize action it accepted, rebuilt to
+ * its name, id, time and execution link, which the page's SDK polls for the issuer's answer. That link
+ * must be the paused payment's own execution on its own host, or the page would poll another payment's
+ * result. Under a JSON content type; null for anything else.
  */
+export declare function payrailsAnswer(status: number, body: string, url: string): {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+} | null;
+/** payrailsAnswer for a save. */
 export declare function payrailsSaveAnswer(status: number, body: string): {
-    status: 201;
+    status: number;
     headers: Record<string, string>;
     body: string;
 } | null;

package/dist/payrails.generated.d.ts

@@ -3,6 +3,8 @@ declare var PAYRAILS_CAPABILITY: string;
 declare var PAYRAILS_OPERATION: string;
 declare var PAYRAILS_SAVE_PATH: string;
 declare var PAYRAILS_SAVE_HOSTS: readonly string[];
+declare var PAYRAILS_MERCHANT_API_HOST: RegExp;
+declare var PAYRAILS_AUTHORIZE_WORKFLOW: string;
 declare var PAYRAILS_JWE_HEADER: string;
 declare var PAYRAILS_JWE_HEADER_B64: string;
 declare var PAYRAILS_KEY_BITS: readonly number[];
@@ -25,9 +27,14 @@ declare var PAYRAILS_REFUSALS: Readonly<{
 declare function payrailsRefusalMessage(code: any): any;
 declare function base64UrlEncode(bytes: any): string;
 declare function base64UrlDecode(text: any, max: any): Uint8Array<ArrayBuffer> | null;
+declare function isPayrailsApiHost(hostname: any): boolean;
 declare function isPayrailsSaveUrl(url: any, { exact: exact2 }?: {
     exact?: boolean | undefined;
 }): boolean;
+declare function isPayrailsAuthorizeUrl(url: any, { exact: exact2 }?: {
+    exact?: boolean | undefined;
+}): boolean;
+declare function payrailsExecutionId(url: any): string | null;
 declare function payrailsJweParts(jwe: any): {
     wrappedKey: Uint8Array<ArrayBuffer>;
     iv: Uint8Array<ArrayBuffer>;
@@ -38,6 +45,8 @@ declare function payrailsTemplateRefusal(body: any): any;
 declare function parsePayrailsSave(body: any): any;
 declare function payrailsKeepsCardFor(save: any): any;
 declare function payrailsCardOnFileRefusal(body: any): any;
+declare function payrailsAuthorizeRefusal(body: any): any;
+declare function parsePayrailsAuthorize(body: any): any;
 declare function classifyPayrailsRequest(url: any, method: any, body: any): "card" | "continue" | null;
 declare function payrailsAuthorizeCarriesCard(url: any, method: any, body: any): boolean;
 declare function payrailsSessionKeyBytes(spki: any): any;
@@ -54,7 +63,8 @@ declare function payrailsFacts(text: any): {
     refusalCode: any;
 };
 declare function sanitizePayrailsResponse(text: any): string;
-declare function payrailsResponseOutcome(status: any, text: any, { card }?: {}): {
+declare function sanitizePayrailsAuthorizeResponse(text: any, url: any): string;
+declare function payrailsResponseOutcome(status: any, text: any, { card, url }?: {}): {
     outcome: string;
     reason: string;
     code?: undefined;
@@ -70,4 +80,4 @@ declare function payrailsResponseOutcome(status: any, text: any, { card }?: {}):
     reason?: undefined;
     code?: undefined;
 };
-export { PAYRAILS_CAPABILITY, PAYRAILS_CARD_ON_FILE_CONSENTED, PAYRAILS_FUTURE_USAGES, PAYRAILS_JWE_HEADER, PAYRAILS_JWE_HEADER_B64, PAYRAILS_KEY_BITS, PAYRAILS_OPERATION, PAYRAILS_PSP, PAYRAILS_REFUSALS, PAYRAILS_SAVE_HOSTS, PAYRAILS_SAVE_PATH, PAYRAILS_SERVED_CARD_FACTS, PAYRAILS_SESSION_MIN_SECONDS, PAYRAILS_UNUSABLE_STATUSES, PAYRAILS_USABLE_STATUSES, base64UrlDecode, base64UrlEncode, classifyPayrailsRequest, isPayrailsSaveUrl, parsePayrailsSave, payrailsAuthorizeCarriesCard, payrailsCardOnFileRefusal, payrailsFacts, payrailsJweParts, payrailsKeepsCardFor, payrailsRefusalMessage, payrailsResponseOutcome, payrailsSessionKeyBytes, payrailsSessionKeyRefusal, payrailsTemplateRefusal, payrailsTokenClaims, payrailsWorkspacePinRefusal, sanitizePayrailsResponse };
+export { PAYRAILS_AUTHORIZE_WORKFLOW, PAYRAILS_CAPABILITY, PAYRAILS_CARD_ON_FILE_CONSENTED, PAYRAILS_FUTURE_USAGES, PAYRAILS_JWE_HEADER, PAYRAILS_JWE_HEADER_B64, PAYRAILS_KEY_BITS, PAYRAILS_MERCHANT_API_HOST, PAYRAILS_OPERATION, PAYRAILS_PSP, PAYRAILS_REFUSALS, PAYRAILS_SAVE_HOSTS, PAYRAILS_SAVE_PATH, PAYRAILS_SERVED_CARD_FACTS, PAYRAILS_SESSION_MIN_SECONDS, PAYRAILS_UNUSABLE_STATUSES, PAYRAILS_USABLE_STATUSES, base64UrlDecode, base64UrlEncode, classifyPayrailsRequest, isPayrailsApiHost, isPayrailsAuthorizeUrl, isPayrailsSaveUrl, parsePayrailsAuthorize, parsePayrailsSave, payrailsAuthorizeCarriesCard, payrailsAuthorizeRefusal, payrailsCardOnFileRefusal, payrailsExecutionId, payrailsFacts, payrailsJweParts, payrailsKeepsCardFor, payrailsRefusalMessage, payrailsResponseOutcome, payrailsSessionKeyBytes, payrailsSessionKeyRefusal, payrailsTemplateRefusal, payrailsTokenClaims, payrailsWorkspacePinRefusal, sanitizePayrailsAuthorizeResponse, sanitizePayrailsResponse };