> NOTE: This document is **only applicable to select merchants and partners** using 3rd party checkout solutions. For more information, contact [our enterprise sales team](https://www.shopify.com/solutions/shop-pay/enterprise#contact-sales).
## Overview
This document aims to provide developers with guidance on how to approach the implementation of Shop Pay. This document is not intended to replace any of our existing public documentation, but to provide a guide for developers who are interested in understanding the development journey and key considerations for implementing Shop Pay.
## Development Journey
1. Review [the Shop Component documentation](https://shopify.dev/docs/api/commerce-components/pay) including the [UX guidelines](https://shopify.dev/docs/api/commerce-components/pay/design-guidelines).
2. Complete the [Shop Configuration guide](https://shopify.dev/docs/api/commerce-components/pay/shop-configuration) to configure your Shopify account, and provide your Shopify Launch team with the required information.
3. Shopify will confirm once the shop has been configured. Domain propagation might take up to 24 hours.
4. [Create Shop Pay test user account(s)](https://shop.app/pay/authentication/login), verify email & phone, then provide the email addresses to your Shopify Launch team to enable test mode for the accounts.
5. Develop the integration using the [developer documentation](https://shopify.dev/docs/api/commerce-components/pay):
1. Add and configure the [JavaScript SDK](https://shopify.dev/docs/api/commerce-components/pay#javascript-sdk-for-buttons-and-email-recognition).
2. [Create a session](https://shopify.dev/docs/api/commerce-components/pay#create-a-session) and populate the [payment request](https://shopify.dev/docs/api/commerce-components/pay#shoppaypaymentrequest) with mock data.
3. [Create event listeners](https://shopify.dev/docs/api/commerce-components/pay#attach-event-listeners) and ensure they respond with complete calls.
4. Establish frontend-backend API communication.
5. Implement the [GraphQL ShopPayPaymentRequestSessionCreate](https://shopify.dev/docs/api/commerce-components/pay#example-shoppaypaymentrequestsessioncreate) and [GraphQL ShopPayPaymentRequestSessionSubmit](https://shopify.dev/docs/api/commerce-components/pay#example-shoppaypaymentrequestsessionsubmit) calls.
_This is sufficient to establish the session, open the popup and complete an order using a test card with Shopify Payments in test mode. The next section provides additional guidance on how to complete the checkout portion of the implementation._
6. Ensure backend access to required services (discounts, shipping, taxes).
7. Build out frontend event listeners and backend functionality for data passing.
8. Forward customers to the thank-you page and pass required data after a successful purchase.
9. Add [error handling](https://shopify.dev/docs/api/commerce-components/pay#shoppayusererror) and logging.
10. Add analytics and the optional `onAnalyticsEvent` parameter.
11. Add locale and multi-currency support if needed.
_This completes the checkout portion of the implementation. The following additional steps are required to complete all post-order actions._
6. [Build a reconciliation job](https://shopify.dev/docs/api/commerce-components/pay#reconciliation-job) to query orders, transactions, and fulfillmentOrders.
7. Build a webhook service to regularly confirm active [webhook subscriptions](https://shopify.dev/docs/api/admin-graphql/2024-01/queries/webhookSubscriptions#top) and [recover when necessary](https://shopify.dev/docs/apps/build/webhooks/best-practices#recover-webhooks).
8. Build a webhook handler to receive and process webhooks.
9. Ensure the system skips the reconciliation job for orders received via webhook.
10. Pass reconciled order data to your Order Management System and mark orders as completed.
11. Build post-order actions ([captures, partial captures](https://shopify.dev/docs/api/commerce-components/pay#payment-capture), [refunds](https://shopify.dev/docs/api/commerce-components/pay#refund-creation), [order cancellations](https://shopify.dev/docs/api/commerce-components/pay#cancelling-and-deleting-orders), [transaction voids and reauthorizations](https://shopify.dev/docs/api/commerce-components/pay#authorizations)).
> Warning: If using the Order Authorization API to generate new authorizations, ensure that your system tracks the age of authorizations to void and reissue them as needed. See [Authorizations](https://shopify.dev/docs/api/commerce-components/pay#authorizations) for more information.
12. [Instrument the checkout for A/B testing](https://shopify.dev/docs/api/commerce-components/pay/merchant-assigned-ab-testing-guide).
13. Align with Shopify on data sharing for the A/B test.
14. Perform an [A/A test](https://shopify.dev/docs/api/commerce-components/pay/merchant-assigned-ab-testing-guide#a-a-test) to ensure data accuracy and even assignment distribution.
15. Align with Shopify on A/A test results and schedule the A/B test.
16. Roll out to 100% after successful A/B test results.
17. Confirm A/B test disablement and ensure email listener and button components are functional in production.
## Key Considerations
While implementing Shop Component, there are many considerations to be made along the way. Specifically, every effort should be taken to reduce friction that a customer may face within the Shop Pay Checkout, such as an error requiring a customer to close the Shop Pay Checkout for any reason before they can complete a purchase.
Below is a list of common considerations your team should explore early in the development journey.
* ### Frontend
* Does anything in the checkout need to be changed in order to support the implementation of Shop Component?
* Moving the email address field to the top of the guest checkout is important to ensure that the email listener is able to recognize the customer early in the checkout process, avoiding the need to enter any additional information such as shipping or payment details
* Adding additional space for the Shop Pay button in the cart or checkout may be required to ensure that there is sufficient space for the Shop Pay button to be displayed according to the [UX guidelines](https://shopify.dev/docs/api/commerce-components/pay/design-guidelines)
* Modifying the guest checkout flow to ensure that both the button and email recognition components are always present in checkout flows, even for recognized or logged-in users
* Front loading any not supported actions in the checkout so that customers can do them before entering the Shop Pay express checkout flow.
* Rewards selection
* Gift card entry
* Gift wrapping, engraving and other customizations
* Cart add-ons / upsells
* Split delivery methods
* Are there any checkout flows where a customer may not review the options in the cart?
* Are all express payment entry points being moved to the first page of the checkout to ensure that customers perform required actions before proceeding with express checkout options such as Shop Pay?
* Do you plan to add the "Buy now" button on the PDP of any high-value products?
* This may encourage a higher conversion rate for high-value products, but may also reduce Average Order Value
* Are you including BOPIS / In-store pickup support?
* This requires additional configuration in the backend to support the pickup location field, and additional logic to ensure that the correct address is being used for the pickup location
* Are you including multi-language support?
* This requires additional configuration in the frontend to support the locale parameter, and additional logic to ensure that the correct language is being used for the payment request
* Are you including multi-currency support?
* This requires additional configuration in the frontend to support the currency parameter, and additional logic to ensure that the correct currency is being used for the payment request
* Are you including installments support?
* This requires additional configuration in the frontend to specify that installments were selected on the thank-you page, and comes with an additional fee
* ### Backend / Integration
* Are there any systemic constraints which might affect implementation?
* Certain addresses or address formats not accepted, requiring additional validation and error handling
* Do you have subscription products which aren't currently supported by Shop Component?
* Is your development environment closed to the public, which might make it difficult for Shopify to test the implementation?
* Is there an inability to host the required logic, such as a reconciliation job or webhook handler, in your existing systems, which may require additional resources to host the logic in a separate service?
* Which additional systems / functions will the backend need to access in order to rebuild the payment request?
* Shipping
* BOPIS / in-store pickup locations
* Discounts
* Automatic or applied rewards
* Taxes
* Inventory (to ensure that products are in stock)
* Gift card handling (to ensure that gift cards applied to the cart are accounted for in the payment request)
* Gift wrapping, engraving, or any other add-on options selected by the customer on the PDP or during the checkout flow (to ensure that these are accounted for in the payment request)
* Will your team be leveraging the Order Authorization API to replace expired or voided authorizations, and/or capture beyond the normal 7-30 days?
* Are you going to use finalCapture on every partial capture, and refresh the authorization as needed, in order to ensure that you can release customer funds quickly for partial refunds?
* Are you going to leave the extended authorization period (up to 30d on most cards) enabled or have it disabled to reduce time to expiration (down to 7d)?
* Will you be using webhook subscriptions to smooth out traffic, or using reconciliation jobs only to retrieve information from Shopify, post-order-creation? This affects the complexity of the post-order actions portion of the implementation, specifically steps 6, 7, 8, and 9 in the development journey above.
* ### Post Purchase
* How much of the Shopify APIs will be adopted for launch vs how much will Customer Service or other teams need to do in the Shopify Admin?
* If development time is a consideration, almost everything post-order-creation can be done manually in the Shopify admin, except for voiding and reissuing authorizations
* Are there training considerations for your team to ensure that they're comfortable with the new process and familiar with Shopify's admin?
* Are there headcount or volume considerations for your team to ensure that they're able to handle any increased workload?
* What's the forward-looking plan to adopt more APIs and consolidate work in your existing systems (OMS, ERP, etc.)?
* How will your returns system work with Shop Pay orders for processing returns and refunds?
* Will you connect your return system/interface, or give your Customer Service teams access to the Shopify admin?
* ### Other considerations
* Shopify administration
* Which members of your team should be the Account Owners on your development and production environments, to ensure that someone is always available to configure restricted settings in Shopify?
* Who will be responsible for using their details for the configuration of Shopify Payments in each of your shops?
* What permissions within Shopify do your staff require to perform their duties? This will help inform how to configure the various roles and their permissions in the [Organization settings](https://help.shopify.com/en/manual/organization-settings) of the Shopify admin.
* A/B testing
* Is your current A/B testing framework going to allow you to measure the effects of Shop Component?
* Are you able to add [Shopify's eventing](https://shopify.dev/docs/api/commerce-components/pay/merchant-assigned-ab-testing-guide) to your existing A/B testing framework?
* Otherwise, do you have a way to share your A/B test data with Shopify to ensure our data teams are aligned?
## Additional Resources