--- title: 2026-08-25 Shop Pay Payment Handler Specification description: Technical specification for integrating Shop Pay as a UCP payment handler for merchant stores and platforms. --- * **Handler name:** `dev.shopify.shop_pay` * **Handler version:** `2026-08-25` * **Schema:** `https://shopify.dev/ucp/shop-pay-handler/2026-08-25/schema.json` * **UCP core:** schemas pinned to `https://ucp.dev/2026-08-25/` The `dev.shopify.shop_pay` handler enables merchants to offer Shop Pay as an accelerated checkout option through UCP-compatible platforms. [Shop Pay](https://www.shopify.com/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. ## Key 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. ## How 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](#materialization) 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](#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](#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. ## Merchant 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. ### Requirements 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. ### Handler 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`. #### Configuration schema | Field | Type | Description | | :---- | :--- | :---------- | | `shop_id` (required) | String | The merchant's unique Shop Pay identifier. | #### Available 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](https://ucp.dev/2026-08-25/specification/payment/guide/#resolving-available_instruments) describes. | Field | Type | Description | | :---- | :--- | :---------- | | `type` (required) | String | Must be `shop_pay`. | The following example shows how merchants declare the Shop Pay handler in their payment configuration: ```json { "ucp": { "payment_handlers": { "dev.shopify.shop_pay": [ { "id": "shop_pay", "version": "2026-08-25", "spec": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/spec.md", "schema": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/schema.json", "available_instruments": [{ "type": "shop_pay" }], "config": { "shop_id": "shopify-559128571" } } ] } } } ``` ### Payment 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. #### Instrument schema A `shop_pay` instrument extends UCP's [payment instrument](https://ucp.dev/2026-08-25/schemas/common/types/payment_instrument.json) with the `shop_token` credential and a `display` that Shop Pay renders. | Field | Type | Description | | :---- | :--- | :---------- | | `id` (required) | String | Unique identifier for this payment instrument. | | `handler_id` (required) | String | Must match the handler's `id` (for example, `shop_pay`). | | `type` (required) | String | Must be `shop_pay`. | | `selected` | Boolean | Whether this instrument is the one the buyer selected. Set `true` on the instrument submitted to `complete`. | | `credential` | Object | The [`shop_token` credential](#credential-schema). Required when the platform acquired the token with the element. Omitted when the platform submits a saved instrument by `id` from an identity-linked checkout. | | `display` | Object | Display information for this instrument, rendered by Shop Pay. Platforms don't send it. | | `display.description` | String | Buyer-facing label for the whole choice, suitable for rendering as-is, for example `Travel card •••• 1314`. Do not parse. | | `display.funding_instruments` | Array | The buyer's [funding instruments](#funding-instrument-schemas) behind this instrument, in Shop Pay's order. | | `display.remaining_amount` | Integer | Delegated budget only. The amount remaining in the current period, in the checkout's currency minor units. | | `display.limit` | Integer | Delegated budget only. The spending limit for the current period, in the checkout's currency minor units. | | `display.renewal_type` | String | Delegated budget only. How the limit renews; `monthly` is the only supported value. | | `display.renews_at` | String | Delegated budget only. ISO 8601 timestamp at which the limit next renews. | 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: ```json { "payment": { "instruments": [ { "id": "instr_shop_pay_1", "handler_id": "shop_pay", "type": "shop_pay", "selected": true, "credential": { "type": "shop_token", "token": "st_…" } } ] } } ``` #### Credential schema The `shop_token` credential extends UCP's [payment credential](https://ucp.dev/2026-08-25/schemas/common/types/payment_credential.json). The token is request-only: a credential in a response carries `type`, plus `approval_id` when one applies, and never `token`. | Field | Type | Description | | :---- | :--- | :---------- | | `type` (required) | String | Must be `shop_token`. | | `token` | String | The Shop Token. From the element, the purchase credential that the buyer confirmed for this checkout. From identity linking, a wallet token that the platform reuses across checkouts. | | `approval_id` | String | The Shop Pay payment approval this submission redeems, when the buyer approved the purchase through a Shop payment approval rather than at the finalizer. | #### Funding 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. ##### Card A card's `display` is the `display` of UCP's [card payment instrument](https://ucp.dev/2026-08-25/schemas/common/types/card_payment_instrument.json#/allOf/1/properties/display), plus `issuer` and `nickname`. | Field | Type | Description | | :---- | :--- | :---------- | | `type` (required) | String | Must be `card`. | | `display.brand` | String | The card brand, for example `visa`. Presentational only. | | `display.last_digits` | String | The last four digits of the card number. | | `display.expiry_month` | Integer | The month of the card's expiration date, 1 to 12. | | `display.expiry_year` | Integer | The year of the card's expiration date. | | `display.description` | String | Buyer-facing label for this card, for example `Travel card •••• 1314`. Do not parse. | | `display.card_art` | String | A URI to an image of the card, such as the issuer's card art. | | `display.issuer` | String | The card's issuing bank as Shop Pay displays it, for example `Chase`. Omitted when unknown. | | `display.nickname` | String | The name the buyer gave this card in Shop. Omitted when unset. | ##### Shop Cash | Field | Type | Description | | :---- | :--- | :---------- | | `type` (required) | String | Must be `shop_cash`. | | `display.description` | String | Buyer-facing label, for example `Shop Cash`. Do not parse. | ##### Shop Pay Installments | Field | Type | Description | | :---- | :--- | :---------- | | `type` (required) | String | Must be `installments`. | | `display.description` | String | Buyer-facing label, for example `Shop Pay Installments`. Do not parse. | A purchase that Shop Cash covers in part, with a card for the rest, has two funding instruments: ```json { "description": "Shop Cash and Travel card", "funding_instruments": [ { "type": "shop_cash", "display": { "description": "Shop Cash" } }, { "type": "card", "display": { "brand": "visa", "last_digits": "1314", "description": "Travel card •••• 1314" } } ] } ``` A purchase paid with Shop Pay Installments has one: ```json { "description": "Shop Pay Installments", "funding_instruments": [ { "type": "installments", "display": { "description": "Shop Pay Installments" } } ] } ``` ## Platform 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](https://clawhub.ai/shopify/shop) to complete identity linking and UCP checkouts. ### Advertise the handler Platforms advertise Shop Pay support by including the handler in their `payment_handlers` map: ```json { "ucp": { "payment_handlers": { "dev.shopify.shop_pay": [ { "id": "shop_pay", "version": "2026-08-25", "spec": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/spec.md", "schema": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/schema.json" } ] } } } ``` ### Discover 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. ### Acquire 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](https://shopify.dev/docs/agents/carts-and-checkout/shop-pay). ### Acquire a token with identity linking In the identity-linked flow, the platform completes [Identity Linking](https://ucp.dev/2026-08-25/specification/common/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: ```json { "payment": { "instruments": [ { "id": "spw_instr_8f3a1c", "handler_id": "shop_pay", "type": "shop_pay", "selected": true, "display": { "description": "Travel card •••• 1314", "funding_instruments": [ { "type": "card", "display": { "brand": "visa", "last_digits": "1314", "expiry_month": 1, "expiry_year": 2027, "issuer": "Chase", "nickname": "Travel card", "description": "Travel card •••• 1314" } } ], "limit": 80272, "remaining_amount": 40136, "renewal_type": "monthly", "renews_at": "2026-05-21T02:50:34Z" }, "credential": { "type": "shop_token" } } ] } } ``` To pay, the platform submits the chosen instrument by `id` with `selected: true` and no `credential`. The merchant resolves the instrument on the server: ```json { "payment": { "instruments": [ { "id": "spw_instr_8f3a1c", "handler_id": "shop_pay", "type": "shop_pay", "selected": true } ] } } ``` ### Complete 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`: ```http POST /checkout-sessions/{checkout_id}/complete Content-Type: application/json UCP-Agent: profile="https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json" { "payment": { "instruments": [ { "id": "instr_shop_pay_1", "handler_id": "shop_pay", "type": "shop_pay", "selected": true, "credential": { "type": "shop_token", "token": "st_…" } } ] } } ``` 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: ```json { "payment": { "instruments": [ { "id": "spw_instr_8f3a1c", "handler_id": "shop_pay", "type": "shop_pay", "selected": true, "credential": { "type": "shop_token", "approval_id": "0198a2ad-7ae0-7d54-af8e-e44247e778fe" } } ] } } ``` On success, the merchant returns the checkout with `status: "completed"` and an `order` object. ### Materialization 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](https://github.com/Shopify/shop). ### Authentication 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](https://ucp.dev/2026-08-25/specification/overview#actions) under `actions["dev.shopify.shop_pay"]`: ```json { "id": "checkout_123", "status": "complete_in_progress", "actions": { "dev.shopify.shop_pay": [ { "id": "shop_pay_auth_1", "config": { "payment_instrument_id": "instr_shop_pay_1", "url": "https://shop.app/checkouts/uc/ahfg14g2uke821092hfh" } } ] } } ``` #### Action schema | Field | Type | Description | | :---- | :--- | :---------- | | `id` (required) | String | Identifies this occurrence. The same `id` on a later Get Checkout is the same outstanding work; a fresh `id` is new work. | | `config.payment_instrument_id` (required) | String | The Shop Pay instrument the challenge belongs to. | | `config.url` (required) | String | A Universal Checkout frame URL for this payment: the `challengeUrl` that the merchant's charge returned. | 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: ```json { "ucp": { "capabilities": { "dev.shopify.shop_pay": [ { "version": "2026-08-25", "extends": "dev.ucp.shopping.checkout", "spec": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/spec.md", "schema": "https://shopify.dev/ucp/shop-pay-handler/2026-08-25/checkout.json" } ] } } } ``` 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](https://shopify.dev/docs/agents/carts-and-checkout/shop-pay) resolves the required action for you. Otherwise, escalate the checkout to the [Embedded Checkout Protocol](https://shopify.dev/docs/agents/carts-and-checkout/ecp). ## Merchant 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. ## Security considerations The Shop Pay handler implements multiple security measures to protect payment data and ensure proper authorization throughout the delegated payment flow. ### Token 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. ### Platform 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. ## Schema 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](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/spec.md): This page, published as the versioned specification that the handler's `spec` URL points to. - [Handler schema](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/schema.json): The root schema defining all Shop Pay handler components, from configs to instruments to credentials. - [Merchant config](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/business_config.json): Defines the required `shop_id` configuration field that merchants include when advertising the Shop Pay handler. - [Shop Pay Instrument schema](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/shop_pay.json): Specifies the structure of Shop Pay payment instruments that platforms submit and merchants process, including credential and wallet display metadata. - [Shop Token Credential schema](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/shop_token.json): Details the Shop Token credential format used to authorize payments through the delegated flow. - [Checkout extension schema](https://shopify.dev/ucp/shop-pay-handler/2026-08-25/checkout.json): Declares the `dev.shopify.shop_pay` Action that the merchant returns when Shop Pay needs the buyer to authenticate a payment.