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 agents. 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 agents can securely generate a Shop Token for a buyer's selected payment instrument in Shop Pay. Merchants can then process these tokens, and agents 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 shipping details.
• Delegated payments: Agents 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 an agent submits a Shop Pay payment:

Anchor to Agent integrationAgent integration

Agents orchestrate Shop Pay payments on behalf of merchants through a delegated flow that collects payment authorization from buyers and returns a token for processing.

Anchor to RequirementsRequirements

Before handling delegated Shop Pay payments, agents must register with Shop Pay to obtain a client_id that supports delegated experiences.

Anchor to Handler configurationHandler configuration

Agents advertise Shop Pay support by including the handler in their payment handlers array. The handler uses a minimal configuration containing only the agent's Shop Pay identifier.

Anchor to Configuration schemaConfiguration schema

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

Anchor to Delegated payment protocolDelegated payment protocol

Agents must follow this flow to process a dev.shopify.shop_pay handler:

Anchor to Step 1: Discover handlerStep 1: Discover handler

Identify dev.shopify.shop_pay in the merchant's payment_handlers map from the checkout response or merchant profile.

Anchor to Step 2: Build payment requestStep 2: Build payment request

Build a Shop Pay payment request by:

1. Initializing the delegated payment context:

   • Provide the merchant's shop_id from the handler configuration.
   • Provide your agent's client_id obtained during registration.
   • This establishes that you're 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.

Anchor to Step 3: Complete checkoutStep 3: Complete checkout

After the buyer confirms, Shop Pay returns a Shop Token. Wrap this token in a UCP payment instrument conforming to the Shop Pay instrument schema and submit the complete checkout request to the merchant:

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

• Single-use tokens: Shop Tokens are designed to be 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.
• Secure transmission: All token exchanges must occur over TLS 1.2+.

Anchor to Agent authorizationAgent authorization

• Agents must register with Shop Pay to obtain a valid client_id before processing delegated payments.
• The client_id identifies the agent to Shop Pay and enables proper authorization tracking.

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.
• Agent config: Defines the required client_id configuration field that agents include when advertising the Shop Pay handler.
• Shop Pay Instrument schema: Specifies the structure of Shop Pay payment instruments that agents submit and merchants process, including credential and billing address requirements.
• Shop Token Credential schema: Details the Shop Token credential format used to authorize payments through the delegated flow.