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 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.

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 uses a minimal configuration containing only the merchant's Shop Pay identifier today.

Anchor to Configuration schemaConfiguration schema

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

Shop Pay instruments extend the base UCP payment instrument with Shop Pay-specific fields and credential types.

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

Anchor to Platform integrationPlatform integration

Platforms orchestrate Shop Pay payments on behalf of merchants. Two integration paths are supported:

• Path A — One-time Payment Request routes through the Shop Pay interface and returns a single-use token per checkout.
• Path B — Identity-Linked Payment Tokens creates a durable link to the buyer's Shop identity and issues a token the platform can reuse across checkouts.

Both paths converge 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 from the checkout response or merchant profile. If present, the merchant accepts Shop Pay payment instruments and the platform can proceed with either integration path below.

Anchor to Token Acquisition Path A: One-time Payment RequestToken Acquisition Path A: One-time Payment Request

In the one-time flow, the platform constructs a payment request and hands it to the buyer through the Shop Pay interface. The buyer authenticates and selects a payment method in Shop Pay, and Shop Pay returns a single-use Shop Pay token the platform submits at checkout.

Before using this flow, platforms must register with Shop Pay to obtain a client_id for delegated payment experiences. The client_id is used in the Shop Pay interface handoff and isn't advertised in the UCP handler configuration.

Build a Shop Pay payment request by:

1. Initializing the delegated payment context:

   • Provide the merchant's shop_id from the handler configuration.
   • Provide the platform's client_id obtained during registration.
   • This establishes that the platform is orchestrating a Shop Pay payment on behalf of the merchant.

2. Constructing the payment request with standardized UCP checkout data:

   • Totals: Subtotal, shipping, tax, and grand total amounts.
   • Fulfillment options: Available shipping methods or pickup locations.
   • Line items: Product details, quantities, and pricing.
   • Currency and locale: For proper formatting and display.

Present this payment request to the buyer through the Shop Pay interface, where they can authenticate and select their preferred payment method. After the buyer confirms, Shop Pay returns a single-use Shop Pay token scoped to this checkout.

Anchor to Token Acquisition Path B: Identity-Linked Payment TokensToken Acquisition Path B: Identity-Linked Payment Tokens

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. When leveraging the access token in a UCP checkout, Shop Pay surfaces the available Shop Wallet address context and the Shop Pay tokens if scopes were approved by the buyer.

Anchor to Complete the checkoutComplete the checkout

Both integration paths converge at checkout submission. The platform wraps the Shop Pay token in a UCP payment instrument conforming to the Shop Pay instrument schema and posts it as payment_data to the merchant's complete endpoint:

Upon successful processing, the merchant returns the completed checkout state with an order_id confirming the purchase.

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. Extract token: Retrieve the token from credential.token.

3. Process payment: Use the Shop Token to complete the payment through Shop Pay's payment processing API.

4. Return response: Respond with the finalized checkout state including order confirmation details.

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.

• Secure transmission: All token exchanges must occur over TLS 1.2+.
• Path A — One-time Payment Request: Shop Tokens are single-use and can't be reused across transactions.
  • Time-limited: Tokens have a limited validity period and should be used promptly after generation.
  • Checkout-scoped: Tokens have context about the checkout and merchant, preventing usage outside of the verified checkout.
• Path B — 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

• Path A — One-time Payment Request: Platforms must register with Shop Pay to obtain a client_id that identifies the platform during the Shop Pay interface handoff.
• Path B — 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 JSON schemas define the structure and validation rules for Shop Pay handler configuration and payment data:

• 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.