> 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](/docs/apps/build/payments/hosted-payment-sdk). > Learn more about the new [payments platform](/docs/apps/build/payments). ![ ](/assets/payment-gateway-sdk/welcome-to-payment-gateway.png) 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](/docs/api/development-stores#create-a-development-store-to-test-your-app). After you've created a development store, you can start to [develop your payment gateway integration](/docs/apps/build/payments/hosted-payment-sdk/payment-gateway-integration). The checkout process, including what the customer sees and doesn't see, has six stages: ![A flowchart of the checkout process](/assets/api/sdks/hosted-payment-sdk/flow-chart.png) 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](/docs/apps/build/payments/hosted-payment-sdk/reference/request-values). Your gateway verifies the `x_signature` value and presents its own hosted payments page to the customer (see [Signing Mechanism](/docs/apps/build/payments/hosted-payment-sdk/payment-gateway-integration#gateway-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](/docs/apps/build/payments/hosted-payment-sdk/reference/response-values) as query parameters, including `x_signature` (see [Signing Mechanism](/docs/apps/build/payments/hosted-payment-sdk/payment-gateway-integration#gateway-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](/docs/apps/build/payments/hosted-payment-sdk/reference/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](/docs/apps/build/payments/hosted-payment-sdk/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](/docs/apps/build/payments/hosted-payment-sdk/payment-gateway-integration) - [Adding your payment gateway to your Partners account](/docs/apps/build/payments/hosted-payment-sdk/add-payment-gateway) - [Sharing your payment gateway](/docs/apps/build/payments/hosted-payment-sdk/publish) - [API Reference](/docs/apps/build/payments/hosted-payment-sdk/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](/docs/apps/build/payments/hosted-payment-sdk/reference) 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](https://community.shopify.com/c/Shopify-APIs-SDKs/bd-p/shopify-apis-and-technology) Visit our forums to connect with the community and find out more about the Shopify API and App development. ### [Sample Hosted Payments project](https://github.com/Shopify/hosted-payment-sim) The Hosted Payment Simulator will allow you to simulate the redirects and callbacks needed to build an integration