Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
c7c825e
feat(browser-pay): add fillCard to type the placeholder into checkout…
gwitwer Nov 7, 2026
f752818
fix(browser-pay): fillCard types only into trusted frames and confirm…
gwitwer Nov 7, 2026
b9ba2ce
fix(browser-pay): check expiry year width against the field and trust…
gwitwer Nov 7, 2026
4014b0c
fix(browser-pay): let validation, not the pattern text, pick the expi…
gwitwer Nov 7, 2026
61c69d0
fix(browser-pay): always try both expiry year widths
gwitwer Nov 7, 2026
18262a6
fix(browser-pay): harden fillCard per review
gwitwer Nov 7, 2026
ca92e6a
fix(browser-pay): keep scrolled-to autofill copies and navigated fram…
gwitwer Nov 7, 2026
cfbba9b
fix(browser-pay): scroll stacked card fields into view inside frames too
gwitwer Nov 7, 2026
c56057c
fix(browser-pay): rank in-view card fields ahead of ones reached by s…
gwitwer Nov 7, 2026
5598628
fix(browser-pay): rank duplicate card fields by on-page visibility, r…
gwitwer Nov 7, 2026
1d6110f
fix(browser-pay): within one frame, rank the in-view field ahead of a…
gwitwer Nov 7, 2026
2fe6634
fix(browser-pay): apply the in-view preference only between equally s…
gwitwer Nov 7, 2026
e24a06c
fix(browser-pay): in a cross-origin card frame, the in-view field win…
gwitwer Nov 7, 2026
b45340a
fix(browser-pay): never take an address or contact field as a bare ca…
gwitwer Nov 7, 2026
aa41e23
fix(browser-pay): a vault frame's visible bare field beats any scroll…
gwitwer Nov 7, 2026
d39fff4
fix(browser-pay): a bare card field's label may use only card words
gwitwer Nov 7, 2026
8aae7ef
Merge remote-tracking branch 'origin/main' into sapiom/browser-pay-fi…
gwitwer Nov 12, 2026
9b8d6a2
fix(browser-pay): fillCard never guesses the card number from an addr…
gwitwer Nov 12, 2026
380a27e
fix(browser-pay): check a srcdoc frame's origin from its parent; matc…
gwitwer Nov 12, 2026
9a33613
test(browser-pay): run the fillCard tests on CI's system Chrome
gwitwer Nov 13, 2026
4c4fd5d
test(browser-pay): give fillCard browser tests 30s on a shared CI runner
gwitwer Nov 13, 2026
d280cad
test(browser-pay): close Chrome's idle preconnect before closing the …
gwitwer Nov 13, 2026
899a2e5
fix(browser-pay): never fill a cardholder address or phone field as t…
gwitwer Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/browser-pay-fill-card.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@sapiom/browser-pay": minor
---

Add `fillCard`, which types the purchase's placeholder card into a checkout's card form over a Playwright page without an LLM. It finds the fields in every frame by `autocomplete`, name, label and provider attributes (Shopify's card vault, Stripe Elements, Braintree hosted fields, Adyen secured fields, plain inputs and expiry selects), ignores the off-screen autofill copies card vaults put in each field's iframe, never types into a field whose name or id names an address or contact part unless its `autocomplete` says it is a card field (a billing- or shipping-prefixed field counts when its name or id names a card field), counts a bare `number`/`name` field only inside a card iframe on another origin (so on the page itself an unrecognised number field is reported missing, not guessed at), handles a combined MM/YY field or split month and year, types only into frames on the page origin, a built-in card-vault host or caller-listed origins, and reads each field back. It never logs or returns a card value and never presses Pay. Reword three README passages that used internal names.
38 changes: 37 additions & 1 deletion packages/browser-pay/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,42 @@ Browser Pay for Sapiom Pay. The agent types a governance placeholder into checko

An agent that gives up before paying cancels the purchase, which revokes the placeholder: a UCP checkout with `POST /v1/transactions/{transactionId}/ucp/checkout/cancel`, a browser-checkout purchase with `POST /v1/transactions/{transactionId}/cancel`. The browser-checkout cancel answers 409 `card_relayed` once the card was relayed; the payment is spent, and the agent completes the transaction instead.

## Filling the card form

`fillCard(page, card)` types the placeholder into the checkout's card form, so the agent does not have to find and type into card fields itself. `page` is a Playwright page connected to the same browser with `chromium.connectOverCDP(cdpUrl)`; `card` is the placeholder's `number`, `expMonth`, `expYear` and `cvc`, plus an optional cardholder `name`.

```typescript
import {
attachInterceptor,
fillCard,
httpPaymentRelay,
} from "@sapiom/browser-pay";

const handle = await attachInterceptor(cdpUrl, {
relay,
placeholder: { number, injectionRef },
});
// … the agent reaches the payment step …
const filled = await fillCard(page, { number, expMonth, expYear, cvc });
if (filled.ok) {
await page
.getByRole("button", { name: /pay now|place order|complete order/i })
.click();
} else {
// `filled.missing` names the fields it could not fill. Read the purchase before retrying or cancelling.
}
```

It looks in every frame, including one cross-origin iframe per field (Shopify's card vault, Braintree hosted fields, Adyen secured fields) and one iframe for all fields (Stripe Elements), and classifies inputs and selects by `autocomplete` (`cc-number`, `cc-exp`, `cc-exp-month`, `cc-exp-year`, `cc-csc`, `cc-name`), name, id, placeholder, label and provider attributes. Without `autocomplete`, a field whose name or id names an address or contact part (`street`, `cardholder_phone`) is never a card field; one that names only a form section (`billing_number`) is a card field only when its name or id also names a card field (`billing_card_number`); and a field named only `number` or `name` counts only inside a card iframe on another origin; on the page itself such a field is reported missing rather than guessed at. A card vault puts a copy of every card input in each field's iframe for autofill; `fillCard` types only into the copy a person could click (its centre is in the frame's viewport and nothing covers it). For a combined expiry it tries `MM/YY` and `MM/YYYY` (four digits first when the placeholder spells YYYY), then `MMYY`, and keeps the first one the field reads back without marking itself invalid (constraint validation, including the field's `pattern`, or `aria-invalid` after blur). It fills split month and year inputs or selects (numbers or month names) only when both exist, and reads a select back after its change handlers run. It waits up to `timeoutMs` (default 15 seconds) for card iframes that load after the page, types with a short delay so input masks keep up, and reads each field back.

It types only into frames on the page's own origin (including a `srcdoc` or `about:blank` frame the browser lets read its parent's document), on a built-in card-vault host over https (Shopify, Stripe, Braintree, Adyen, PayPal, Square, Checkout.com, Recurly, Chargebee, Spreedly, Authorize.net), or on an origin listed in `frameOrigins`. A frame on any other origin that holds card fields is not typed into and is named in `untrusted`, so an unrelated embedded iframe advertising card fields never receives the placeholder.

The result is `{ ok, filled, missing, unconfirmed, origins, untrusted }`. `ok` is true when the number, the security code and the expiry were each typed and read back. `missing` lists `number`, `expiry` or `cvc` when one was not found or did not read back; `unconfirmed` lists fields found whose read-back differed; `origins` names the frame origin each field was filled in. The result never contains a card value, and `fillCard` never logs one.

`fillCard` does not press Pay; the caller keeps that step. A checkout's own field scripts can still send card data while it types, so `ok: false` does not prove nothing was sent: read the purchase (`payment_submitted` means the card may have reached the merchant) before retrying the fill or cancelling the purchase.

It throws a `TypeError`, whose message carries no card values, before touching any field when the number, security code or expiry is not usable. Before typing into a frame it checks the frame is still on the origin it was found on, and after the last field it reads every field back once more, so a field a later handler reset is reported in `unconfirmed`. A field whose click is blocked (covered or detached) passes to the next matching field.

## Relay contract

`POST /v1/transactions/{transactionId}/payment/relay` with `x-api-key`. `transactionId` is only in the path. The JSON body is:
Expand Down Expand Up @@ -140,7 +176,7 @@ Call `handle.on` after `attachInterceptor` resolves. Events emitted while attach

An optional `logger` receives `browser step failed` when arming `Fetch.enable` fails, and when a nested auto-attach, resume, `Target.getTargets`, existing-frame attach, or close fails.

A request is relayed when the held placeholder number appears in the URL or body. An exact match counts, and so do digits split by spaces or dashes, including the URL-encoded and JSON-escaped forms of those separators. `placeholder` is `{ number, injectionRef }`. `injectionRef` is a UUID. The backend's `checkPlaceholderUse` decides whether the number is valid. A paused request that does not hold the placeholder is continued.
A request is relayed when the held placeholder number appears in the URL or body. An exact match counts, and so do digits split by spaces or dashes, including the URL-encoded and JSON-escaped forms of those separators. `placeholder` is `{ number, injectionRef }`. `injectionRef` is a UUID. Sapiom decides whether the number is valid when the relay receives it. A paused request that does not hold the placeholder is continued.

A relayed response fails the paused request only when that response contains the held placeholder number.

Expand Down
33 changes: 33 additions & 0 deletions packages/browser-pay/examples/fill-card.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/**
* Type the purchase's placeholder into the checkout's card form, then decide yourself
* whether to press Pay. Attach the interceptor first (see attach.ts) on the same CDP URL.
*
* CDP_URL=… PLACEHOLDER_NUMBER=… PLACEHOLDER_EXP_MONTH=… PLACEHOLDER_EXP_YEAR=… \
* PLACEHOLDER_CVC=… npx tsx examples/fill-card.ts
*/
import { chromium } from "playwright";
import { fillCard, type PageLike } from "../src/index.js";

async function main(): Promise<void> {
const cdpUrl = process.env.CDP_URL;
if (!cdpUrl) throw new Error("CDP_URL is required");
const browser = await chromium.connectOverCDP(cdpUrl);
const page = browser.contexts()[0]?.pages()[0];
if (!page) throw new Error("no open page on that browser");

const result = await fillCard(page as unknown as PageLike, {
number: process.env.PLACEHOLDER_NUMBER ?? "",
expMonth: Number(process.env.PLACEHOLDER_EXP_MONTH),
expYear: Number(process.env.PLACEHOLDER_EXP_YEAR),
cvc: process.env.PLACEHOLDER_CVC ?? "",
});
// Only field kinds and frame origins: safe to log.
process.stdout.write(`${JSON.stringify(result)}\n`);
if (!result.ok) {
// Never press Pay half-filled. Read the purchase before retrying the fill or cancelling.
process.exitCode = 1;
}
await browser.close();
}

void main();
Loading
Loading