Getting Started with the Hosted Payment SDK
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:
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.
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_signaturevalue and presents its own hosted payments page to the customer (see Signing Mechanism).
The customer pays for the order on the hosted payment page that you provide.
Customers that complete the payment flow should be redirected back to
x_url_completewith 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
It is best practice for your payment gateway to also POST a callback asynchronously to
x_url_callbackwith 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.
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:
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
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
Visit our forums to connect with the community and find out more about the Shopify API and App development.
The Hosted Payment Simulator will allow you to simulate the redirects and callbacks needed to build an integration