Browser Pay SDK reference

@sapiom/browser-pay intercepts the card request that carries a Sapiom placeholder and relays it through Sapiom. It needs Node.js 18 or later and has no runtime dependencies. For a walkthrough, see Pay in your browser.

npm install @sapiom/browser-pay

attachInterceptor(target, options)

Connects to the browser and starts intercepting. Resolves to an InterceptorHandle once interception is active. Fill card fields only after it resolves. target is one of:

a CDP WebSocket URL
an object with wsEndpoint(), such as a Puppeteer browser
a page whose browser() or context().browser() returns one

Browser Pay always opens its own CDP connection.

AttachOptions

Option	Type	Notes
`relay`	`PaymentRelay`	Usually `httpPaymentRelay(...)`.
`placeholder`	`HeldPlaceholder`	`{ number, injectionRef }` from the placeholder for this transaction.
`profileId`	`string`	For example `shopify-card-vault`.
`timeoutMs`	`number`	Total time to wait for a final relay outcome. Default 55,000.
`attemptTimeoutMs`	`number`	Time before one relay attempt is aborted and retried. Default 25,000.
`logger`	`PayLogger`	Receives warnings. Defaults to discarding them.

InterceptorHandle

Member	Notes
`on(listener)`	Subscribes to events. Returns an unsubscribe function.
`detach()`	Stops intercepting. Fails any request still paused, so call it only after checkout settles.

httpPaymentRelay(options)

Builds a relay that posts to POST /v1/transactions/{transactionId}/payment/relay.

Option	Type	Notes
`baseUrl`	`string`	`https://api.sapiom.ai`, without `/v1`.
`apiKey`	`string`	The buyer key that owns the transaction. Sent as `x-api-key`.
`transactionId`	`string`	The ID of the transaction being paid.
`fetchImpl`	`typeof fetch`	Optional custom fetch.

Events

`type`	Fields	Meaning
`paused`	`url`, `method`, `targetType`	A card request was paused for relay.
`relayed`	`url`, `status`	The processor’s response reached the page.
`relayed_unfulfilled`	`url`, `status`	The relay returned, but the page could not receive the response.
`refused`	`url`, `reason: RefusalReason`	Sapiom refused the relay.
`failed`	`url`, `reason: FailureReason`	The request could not be relayed.

Event URLs contain only the origin.

Retries

Timeouts, network errors, HTTP 502, 503 and 504, and relay_in_progress are retried with the same idempotency key until timeoutMs. Any other refusal fails the request. A relay that returns outcome: "unknown" is never sent again.

RefusalReason

unknown_injection, injection_expired, payment_released, key_rotated, already_relayed, relay_in_progress, card_removed, payment_not_authorized, total_changed, destination_not_allowed, card_fields_invalid, merchant_mismatch, provider_unavailable, and unrecognized for any other value. The relay can also refuse with payments_stopped, which this version reports as unrecognized. Each reason’s meaning is in Relay refusals.

FailureReason

intercept_unavailable, unknown_session, unreadable_body, detached, page_origin, unknown, timeout, network, response_credential.

Other exports

Types: AttachOptions, InterceptorEvent, InterceptorHandle, InterceptorTarget, PaymentRelay, RelayCallOptions, RelayRequest, RelayResponse, HeldPlaceholder, PayLogger, HttpRelayOptions, FailureReason, RefusalReason.

Overview

REST API

MCP and SDK

Errors

Browser Pay SDK reference

attachInterceptor(target, options)

AttachOptions

InterceptorHandle

httpPaymentRelay(options)

Events

Retries

RefusalReason

FailureReason

Other exports

​attachInterceptor(target, options)

​AttachOptions

​InterceptorHandle

​httpPaymentRelay(options)

​Events

​Retries

​RefusalReason

​FailureReason

​Other exports

attachInterceptor(target, options)

AttachOptions

InterceptorHandle

httpPaymentRelay(options)

Events

Retries

RefusalReason

FailureReason

Other exports