Getting Started with the Hosted Payment SDK

Deprecated

Starting April 30, 2022, new users can no longer install your legacy Hosted Payment SDK (HPSDK) integrations. Your new payments app should be launched by this time to ensure that there's no disruption with new user onboarding. Existing users will have until July 31, 2022 to switch to your payments app.

In early May 2022, Shopify will contact impacted users who haven't migrated to the new platform to help them adopt an alternative payments app and avoid payment processing disruptions. After July 31, 2022, all HPSDK integrations will be deprecated.

To learn more about the HPSDK deprecation, and how to migrate to Payments Platform, refer to Hosted Payment SDK overview.

Learn more about the new payments platform.

The Hosted Payment SDK allows you to integrate your hosted payment page with Shopify's checkout. All Hosted Payment SDK integrations are based on a full page redirect on the final payment step of Shopify's checkout through a standardized interface available to third party payment gateways.

Getting started with the Hosted Payments SDK

To begin integrating your custom payment gateway, you'll need to become a Shopify Partner and create a development store. After you've created a development store, you can start to develop your payment gateway integration.

The checkout process, including what the customer sees and doesn't see, has six stages:

1. The customer places an order with Shopify Checkout. They enter their email, shipping address and delivery method, and then select your gateway as their payment option.

2. On the last step of Shopify Checkout the customer is redirected to your gateway's URL using a POST request along with Request Values. Your gateway verifies the x_signature value and presents its own hosted payments page to the customer (see Signing Mechanism).

3. The customer pays for the order on the hosted payment page that you provide.

4. Customers that complete the payment flow should be redirected back to x_url_complete with all required Response Values as query parameters, including x_signature (see Signing Mechanism). Visitors that exit the payment flow before successfully completing it need to be redirected back to x_url_cancel.

5. It is best practice for your payment gateway to also POST a callback asynchronously to x_url_callback with the same Response Values. This ensures that orders can be completed even in cases where the customer's connection to Shopify is terminated prematurely. Callbacks must be in HTTP POST x-www-form-urlencoded format.

6. The order is complete, and a thank-you page is shown to customer:

   • HTTP 200 indicates successful receipt of a callback by Shopify. Otherwise up to 5 retries with an interval of at least 60 seconds are recommended.
   • Duplicate requests are ignored by Shopify.

Continue to the getting started guide to begin making use of the Hosted Payment SDK.

Contents of the SDK

The Hosted Payment SDK includes the resources you need to integrate your custom payment gateway with Shopify, including:

• Developing your payment gateway integration

• Adding your payment gateway to your Partners account

• Sharing your payment gateway

• API Reference

Frequently asked questions

"422 Unprocessable Entity: Notification acknowledgment failed" when sending the response

This error occurs when an invalid x_signature parameter is being sent in the response. Either the merchant has input the incorrect credentials in the Payment settings of their store, or there is an issue with how the signature is being calculated.

"422 Unprocessable Entity: Unable to find checkout with ID <x>"

You'll need to ensure that the x_reference value that you are providing matches the checkout ID that is generated by Shopify. This value will be the same as the x_reference value that was sent in the parameters of the request.

Is it possible to modify the Order ID on Shopify?

No, order IDs are generated sequentially by Shopify and are not mutable.

Is it possible to create an order with "pending" payment status, and then transition to "paid" at a later time? (i.e. when goods are ready to ship)

Upon sending the initial notification to x_url_callback, you can provide an x_result value of pending. To transition the order in Shopify to the "paid" status, simply send another notification to x_url_callback at a later time with an x_result value of completed.

Why am I receiving empty order management requests?

Payment requests to your integration have their parameters stored in the URL as query string parameters, but order management requests have their parameters stored within the request body instead. When your gateway processes order management requests, make sure that it reads the request body.

Hosted Payments SDK resources

Shopify API Developer Forums

Visit our forums to connect with the community and find out more about the Shopify API and App development.

Sample Hosted Payments project

The Hosted Payment Simulator will allow you to simulate the redirects and callbacks needed to build an integration