Shop Pay Wallet API
This API is only available to select merchants and partners using third-party checkout solutions. For more information, contact our enterprise sales team.
This API is only available to select merchants and partners using third-party checkout solutions. For more information, contact our enterprise sales team.
Anchor to OverviewOverview
The Shop Pay Wallet JS API enables your existing ecommerce site to use Shop Pay for checkout. Customers who select a Pay with Shop button or are recognized by email are shown all relevant cart information and can complete the transaction in an experience consistent with other usages of Shop Pay using a popup on your site.
Anchor to GlossaryGlossary
| Term | Definition |
|---|---|
| Shop Pay login | Logging in to a Shop Pay account. This occurs directly between a customer and Shopify. |
| Payment request | A payment request includes line items, applied discounts, tax calculations and available shipping methods. |
| Authentication modal | When a Shop Pay user's email is recognized, the customer will see an interface to enter a One Time Password (OTP) for authentication. |
| Shop Pay popup | Most of the interactions in Shop Pay Checkout happen within the context of a Shopify-hosted popup window. |
Anchor to Technical requirementsTechnical requirements
- A Shopify account with Shopify Payments enabled
- The public domain(s) for the site you will be integrating Shop Pay Wallet into
- A non-Shopify-hosted ecommerce environment to implement against (frontend + backend)
- The content security policy on the frontend must be configured to allow
cdn.shopifycloud.com,cdn.shopify.com,shop.app,pay.shopify.com,*.shopifysvc.com,*.stripe.com - The backend needs to be able to functionally access all applicable resources required to assess and update the state of the payment request, including cart details, tax calculations, shipping methods / pricing, local pickup locations, discounts, inventory availability, etc.
- An understanding of the work necessary to integrate with the Order Management System and other backend systems to perform post-order actions in Shopify such as captures, refunds, and updating fulfillment information.
Anchor to Core ConceptsCore Concepts
Anchor to Your system is the main source of truthYour system is the main source of truth
This API extends your existing systems, so it treats those systems as canonical for everything that they already handle. This includes:
-
Cart contents
-
Shipping methods
-
Pickup locations
-
Tax calculation
-
Discounts
-
Inventory reservations
Shopify is the source of truth for the payment transaction and for Shop Pay related fields, including vaulted customer addresses and payment methods.
Consequently, while this API receives detailed information about the cart in the form of a payment request, any changes to the payment request related to your system's canonical topics must be validated. Whenever the payment request is returned to Shopify, it's used as a replacement for prior data received.
Anchor to Shopify's order IDShopify's order ID
Upon payment completion, the order ID is returned from Shopify via a webhook for use in post-order actions such as capturing payments, issuing refunds, and adding order tracking information.
Anchor to Source identifierSource identifier
Your system is responsible for providing a source identifier that uniquely identifies the order, and is often either an existing cart or order identifier from your system. This value is persisted onto the Shopify order record.
Anchor to Shop Pay popup interactionsShop Pay popup interactions
Shop Pay customers will authenticate with a Shop Pay login, either through an authentication modal or directly within the Shop Pay popup.
In order for Shopify to receive your system's canonical information during the checkout process, Shopify will dispatch events to your frontend integration when there are relevant customer actions in the Shop Pay popup. Following this, your system will then determine if there are any subsequent updates required to be made to the payment request. Based on its new state, calculate and rebuild an updated payment request to provide in the required response to the event.
Once accepted by a customer through the action of clicking the Pay now button, your backend should submit the final payment request mutation, including the paymentMethod token provided by Shopify, resulting in processing the payment and order creation.
While the Shop Pay popup is open, an overlay will darken the background, however the cart on your shop may remain visible. It's important that a customer does not see a different total in the cart because it hasn't updated based on selected shipping methods or discounts applied in Shop Pay. To handle this, we recommend updating any cart totals while the user interacts with the Shop Pay Checkout so that values match. A potential fallback is displaying the totals in a pending state through microcopy like Calculating... or through skeletons, spinners, or other pending UI elements.
Anchor to Order creationOrder creation
A payment request must first be validated in your system including verifying that the payment request hasn't been modified unexpectedly, confirming inventory reservation, discount and pricing validation before submitting the final Shop Pay payment request, which will then create the order in Shopify.
Although rare, there can be a delay before an order becomes available via the Shopify API. It's important to ensure that synchronous order creation is not required for functionality of your checkout. Instead, webhooks can be relied upon for order creation confirmation.
Anchor to Sequence DiagramSequence Diagram
This diagram reflects a "happy path" checkout. For simplicity, it bypasses the Shop Pay login flow, assuming a customer is already logged into Shop Pay.
