Shop Pay payment handler specification

The dev.shopify.shop_pay handler enables merchants to offer Shop Pay as an accelerated checkout option through UCP-compatible platforms. Shop Pay is Shopify's native payment solution that provides a streamlined checkout experience by securely storing buyer payment and shipping information.

This handler enables a delegated payment flow where platforms can securely acquire a Shop Token for a buyer's Shop Wallet. Merchants can then process these tokens, and platforms can leverage the same Shop Pay integration across all participating merchants.

Anchor to Key benefitsKey benefits

• Accelerated checkout: Buyers with Shop Pay accounts can complete purchases faster using their saved payment and fulfillment details.
• Delegated payments: Platforms can orchestrate Shop Pay payments without directly handling sensitive payment credentials.
• Standardized integration: A single Shop Pay integration works across all UCP-compatible merchants.

Anchor to How it worksHow it works

Every Shop Pay integration has two steps. A platform acquires a Shop Token, and then the platform uses it to pay. How you acquire the token and how you use it are independent decisions.

A Shop Token pays a merchant that advertises dev.shopify.shop_pay. Even when a merchant doesn't, a platform can still use the handler to acquire a credential that the merchant can process: Shop Pay materializes an instrument from the buyer's wallet, and the merchant processes it through its own payment processor, as it would any instrument of that type.

A platform acquires a Shop Token in one of the following ways:

• The Shop Pay Element: The platform embeds Shop Pay in its own checkout. The buyer confirms in the wallet, and the element returns a Shop Token as a UCP payment instrument. For more information, see Acquire a token with the Shop Pay Element.
• Identity-linked payment tokens: The platform completes identity linking with Shop Pay one time and holds scoped access to the buyer's Shop Wallet. Shop Pay surfaces the wallet's address context and tokens on the checkout directly. For more information, see Acquire a token with identity linking.

Each path produces the same result: a shop_pay payment instrument that carries a shop_token credential. The token comes either from the element, as the purchase that the buyer confirmed, or from identity linking.

To use the Shop Token, the merchant must advertise dev.shopify.shop_pay. The credential is confirmed for that merchant's checkout. Submit the instrument unchanged to the merchant's complete endpoint, and the merchant redeems it with Shop Pay directly.

Anchor to Merchant integrationMerchant integration

Merchants enable Shop Pay through UCP by advertising the handler in their payment configuration and processing Shop Pay tokens when buyers complete checkout. The merchant receives a Shop Token and redeems it with Shop Pay, which settles against the buyer's wallet.

Anchor to RequirementsRequirements

Requirements depend on whether you're a Shopify merchant or integrating as an external merchant:

If you're a Shopify merchant, Shopify automatically advertises all UCP payment handlers on your behalf, including Shop Pay.

If you're an external merchant, you must register for Shop Pay to obtain your shop_id before advertising Shop Pay through UCP.

Anchor to Handler configurationHandler configuration

Merchants advertise Shop Pay support by including the handler in their payment handlers array. The handler entry carries the merchant's Shop Pay identifier in config and the instrument type that the merchant accepts in available_instruments.

Anchor to Configuration schemaConfiguration schema

Anchor to Available instrumentsAvailable instruments

Shop Pay has one payment instrument type, shop_pay, so available_instruments lists that one entry. The merchant advertises it in its profile and returns it on every checkout response, where it's authoritative for that checkout, as UCP's payment handler guide describes.

The following example shows how merchants declare the Shop Pay handler in their payment configuration:

Anchor to Payment instrument supportPayment instrument support

By advertising the Shop Pay handler, merchants indicate they can accept and process Shop Pay payment instruments. Merchants must be able to handle payment objects conforming to the Shop Pay instrument schema.

Anchor to Instrument schemaInstrument schema

A shop_pay instrument extends UCP's payment instrument with the shop_token credential and a display that Shop Pay renders.

A delegated budget is a shop_pay instrument with its budget fields present; a platform can pay with it without further approval up to remaining_amount.

Merchants receive a payment object structured as follows when a platform submits a Shop Pay payment:

Anchor to Credential schemaCredential schema

The shop_token credential extends UCP's payment credential. The token is request-only: a credential in a response carries type, plus approval_id when one applies, and never token.

Anchor to Funding instrument schemasFunding instrument schemas

A funding instrument is a buyer funding source behind a shop_pay instrument: a card, the buyer's Shop Cash, or Shop Pay Installments. Each has a type and a display that Shop Pay renders. Shop Pay composes every description for display. Render it as-is and don't parse it, because its format may change.

Anchor to CardCard

A card's display is the display of UCP's card payment instrument, plus issuer and nickname.

Anchor to Shop CashShop Cash

Anchor to Shop Pay InstallmentsShop Pay Installments

A purchase that Shop Cash covers in part, with a card for the rest, has two funding instruments:

A purchase paid with Shop Pay Installments has one:

Anchor to Platform integrationPlatform integration

Platforms orchestrate Shop Pay payments on behalf of merchants. Every acquisition path converges when the platform submits the Shop Pay token at checkout. For Personal Agents, you can leverage our published skill to complete identity linking and UCP checkouts.

Anchor to Advertise the handlerAdvertise the handler

Platforms advertise Shop Pay support by including the handler in their payment_handlers map:

Anchor to Discover the handlerDiscover the handler

Identify dev.shopify.shop_pay in the merchant's payment_handlers map on the latest checkout create or update response. If present, the merchant accepts Shop Pay payment instruments and the platform can proceed with an acquisition path below.

The merchant's /.well-known/ucp profile isn't sufficient on its own. Eligibility varies by buyer country, currency, cart contents, merchant configuration, and checkout state, so the authoritative signal is payment_handlers on the latest checkout response. Re-check whenever the checkout materially changes: line items, buyer country, currency, destination, fulfillment selection, or totals. A merchant that stops returning the handler mid-session can no longer accept the token.

Anchor to Acquire a token with the Shop Pay ElementAcquire a token with the Shop Pay Element

Embed Shop Pay in your own checkout. The buyer confirms in the wallet, and the element returns the Shop Token as a shop_pay payment instrument for each checkout that it showed. If you'd rather have Shop Pay complete the checkouts for you, with no token to handle, then use Shop Pay in Checkout Kit.

Anchor to Acquire a token with identity linkingAcquire a token with identity linking

In the identity-linked flow, the platform completes Identity Linking with Shop Pay to acquire scoped access to the Shop Pay Wallet as well as delegated identity authentication for the business.

If the buyer approved those scopes, then the merchant's checkout response includes the buyer's Shop Wallet address context and the wallet's saved payment instruments in payment.instruments[] when the platform presents the identity-linked access token. display carries description, the funding_instruments, and, when the instrument carries a delegated budget, limit, remaining_amount, renewal_type and renews_at. The following response carries one saved card with a delegated budget:

To pay, the platform submits the chosen instrument by id with selected: true and no credential. The merchant resolves the instrument on the server:

Anchor to Complete the checkoutComplete the checkout

Every acquisition path converges at checkout submission. The platform submits the Shop Pay instrument in payment.instruments[] with selected: true to the merchant's complete endpoint. When the platform acquired the token with the element, the instrument carries the shop_token credential unchanged. Each checkout in the purchase has its own token:

After the buyer approves the purchase through a Shop Pay payment approval, the platform submits the instrument with the approval's approval_id in the credential:

On success, the merchant returns the checkout with status: "completed" and an order object.

Anchor to MaterializationMaterialization

Shop Pay can also materialize an instrument from the buyer's wallet for a merchant to process through its own payment processor. That's how a platform pays a merchant that doesn't advertise dev.shopify.shop_pay. A materialized instrument shouldn't be submitted over UCP directly. For how materialization works, refer to Shop.

Anchor to Authentication challenges: the ,[object Object], ActionAuthentication challenges: the dev.shopify.shop_pay Action

Shop Pay sometimes needs the buyer to authenticate a payment, for example for a 3-D Secure challenge. The merchant then accepts the completion and returns the checkout with status: "complete_in_progress" and one UCP Action under actions["dev.shopify.shop_pay"]:

Anchor to Action schemaAction schema

The Shop Pay Checkout extension, dev.shopify.shop_pay, declares this Action and extends dev.ucp.shopping.checkout. The merchant and the platform both advertise the extension in their profiles, next to the handler, and the merchant returns the Action only when the extension is active for the checkout:

A platform advertises the extension only if it can resolve the Action. Without the extension, the merchant doesn't return the Action, and escalates the checkout instead.

Shop Pay in Checkout Kit resolves the required action for you. Otherwise, escalate the checkout to the Embedded Checkout Protocol.

Anchor to Merchant processingMerchant processing

Upon receiving a shop_pay payment instrument, merchants must:

1. Validate handler: Confirm handler_id matches a configured Shop Pay handler.

2. Ensure idempotency: If the request repeats a prior complete with the same idempotency key, then return the prior result without redeeming the token again.

3. Process payment: Use the Shop Token (and approval_id if present) to complete the payment through Shop Pay's payment processing API.

4. Return response: Respond with the finalized checkout state including order confirmation details, or with the dev.shopify.shop_pay Action when Shop Pay requires the buyer to authenticate.

Anchor to Security considerationsSecurity considerations

The Shop Pay handler implements multiple security measures to protect payment data and ensure proper authorization throughout the delegated payment flow.

Anchor to Token securityToken security

Depending on the integration, tokens have different security mechanisms preventing their abuse.

• Shop Tokens from the element: A Shop Token is confirmed for one checkout and redeemed one time. It can't be used for another checkout.
  • Time-limited: Every credential that Shop Pay issues has a TTL, whether it's a Shop Token or a materialized instrument. Use it promptly.
  • Checkout-scoped: Shop Pay resolves the token to the checkout that's being completed. Before the merchant charges, Shop Pay verifies the checkout against what the buyer confirmed: the ID, currency, destination, total, and instrument. Shop Pay refuses a checkout that the purchase doesn't cover.
• Identity-linked payment tokens: Shop Tokens can be multi-use instruments authorized for the platform to use in autonomous checkouts.
  • Time-limited: Identity access tokens have a limited validity period and must be used alongside the token credential for processing.
  • Identity-scoped: Tokens have context about the buyer identity and platform, preventing usage outside of the authorized platform's scope.

Anchor to Platform authorizationPlatform authorization

• The Shop Pay Element: The Embedded Protocol token identifies only the platform's application. It carries no buyer identity and no UCP permissions.
• Identity-linked payment tokens: The authorization access token returned by identity linking is scoped to the individual buyer's Shop identity; platforms must not reuse it across buyers or share it across sessions.

Anchor to Schema referenceSchema reference

The following documents define the Shop Pay handler for version 2026-08-25, the structure and validation rules for its configuration and payment data:

• Handler specification: This page, published as the versioned specification that the handler's spec URL points to.
• Handler schema: The root schema defining all Shop Pay handler components, from configs to instruments to credentials.
• Merchant config: Defines the required shop_id configuration field that merchants include when advertising the Shop Pay handler.
• Shop Pay Instrument schema: Specifies the structure of Shop Pay payment instruments that platforms submit and merchants process, including credential and wallet display metadata.
• Shop Token Credential schema: Details the Shop Token credential format used to authorize payments through the delegated flow.
• Checkout extension schema: Declares the dev.shopify.shop_pay Action that the merchant returns when Shop Pay needs the buyer to authenticate a payment.