Getting Started with the Hosted Payment 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.

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

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.

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.

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

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.

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.

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