Wiki · Concept · Last reviewed June 25, 2026

Payment Request API

The Payment Request API is the W3C browser API that lets a merchant ask the user agent to mediate a payment request between merchant, user, and payment method.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Payment Request, web payments, payment sheets, browser API, agentic commerce, privacy

Definition

The Payment Request API is a W3C Web Payments specification for browser-mediated checkout. The June 22, 2026 Candidate Recommendation Draft says it standardizes an API that lets merchants use one or more payment methods with minimal integration, while user agents facilitate the payment flow between merchant and user. W3C also identifies the document as a draft that may change before any later Recommendation.

MDN frames the API as a consistent payment user experience rather than a new payment method. It lets a user select a preferred way to pay and makes the resulting payment information available to the merchant. In practice, the API moves part of checkout from merchant-controlled form fields into a browser payment interface.

How It Works

A merchant page constructs a PaymentRequest with supported payment method data, payment details, and optional payment options. The W3C interface exposes show(), abort(), and canMakePayment(), along with fields and events for shipping address changes, shipping option changes, and payment-method changes. The request is typically associated with a user action such as activating a buy, purchase, or checkout button.

Calling show() asks the user agent to display and handle the payment interface. MDN marks show() as limited availability and secure-context only, and says its promise resolves with a PaymentResponse when the user accepts the payment request. canMakePayment() is a preflight-style method for checking whether the request is compatible with at least one payment method the user agent supports, but MDN also marks it limited availability.

Payment method identifiers tell the browser which payment methods the merchant accepts. The W3C Payment Method Identifiers specification allows standardized identifiers and URL-based identifiers. For a URL-based identifier, the validation algorithm requires HTTPS and rejects URLs with usernames or passwords.

Agent Context

For Agentic Commerce, Payment Request is the browser ceremony that sits between recommendation and payment authority. A shopping agent may compare products, assemble a cart, watch a price, or prepare checkout details, but Payment Request is where the browser can still show the payee context, amount, method choice, shipping fields, and approval step.

The API is also the base layer for nearby entries. Secure Payment Confirmation binds stronger authentication to payment context. Web-based Payment Handler API describes web applications that can handle payment requests. Payment Request is the merchant-side initiation path that those later mechanisms rely on or extend.

Risks and Boundaries

The API does not process a payment by itself, prove that a transaction is fair, verify that a product description is true, or make an AI agent trustworthy. It coordinates data exchange and user-agent UI around a payment request. The merchant and payment method still carry their own duties for processing, fulfillment, refunds, disputes, and compliance.

The W3C draft's privacy section says the user agent must not share user information with a developer without user consent. It also warns that canMakePayment() can become a fingerprinting vector if many payment methods are probed, and suggests user-agent protections such as rate limiting. The draft also discusses spam and clickjacking risk if payment UI can be opened without recent user activation.

Cross-origin embedding is another boundary. The 2026 W3C draft uses the Permissions Policy payment keyword for iframes that are allowed to invoke Payment Request. A merchant, marketplace, ad frame, affiliate widget, or agent-hosted checkout should not be treated as equivalent just because a payment sheet appears.

Minimum Evidence Record

A governed deployment should preserve the merchant origin, top-level origin, any embedding origin, payment method identifiers, requested total, displayed line-item classes, shipping and payer fields requested, selected payment handler or method class, user activation source, show() timestamp, response status, completion result, agent task identifier if an agent prepared checkout, and the refund or dispute path. Logs should avoid raw payment credentials and should not retain address or contact fields unless retention is necessary and disclosed.

Defense Pattern

Spiralist Reading

Spiralism reads Payment Request as a small pause in the commercial spell. The merchant asks, the browser mediates, and the person is supposed to see enough context to decide.

Agentic commerce pressures that pause. A model can make desire, comparison, cart, coupon, shipping, and payment feel like one conversational motion. The humane task is to keep the point of authority visible.

Sources

Return to Wiki