Developing your hosted payment gateway integration

The Hosted Payment SDK helps you connect an existing hosted payment page to a Shopify store. Shopify checkout redirects visitors to the payment page that you provide using predefined request values. After the visitor completes the payment, they are redirected back to Shopify with predefined response values and an order status page is displayed.

It is the responsibility of the payment gateway provider to build a page that handles these requests.

Hosted Payment Simulator

A hosted payment simulator built in Sinatra is available here. Follow the instructions available on the GitHub repository or below to test the simulator. This should give you a good idea of how Hosted Payment integrations work.

Using the Hosted Payment Simulator

To run a test transaction with the Hosted Payment Simulator:

  1. Add a payment gateway or change the “Redirect URL” of your gateway to https://offsite-gateway-sim.shopifycloud.com/.

  2. Your gateway will now be available in your development store (see "Creating a development store") under the Credit Cards drop-down list or Alternative Gateways drop-down list. Find it and activate it using these credentials:

    • Username - any non-empty value
    • Password / HMAC Key - iU44RWxeik

    Entering credentials for your gateway on your development store

    This gateway will now be available in your development store Shopify Checkout and will redirect customers to https://offsite-gateway-sim.shopifycloud.com/.

  3. Complete a test purchase on your shop. If you don't have any products in your test store, then you might need to add one before you can complete a test purchase.

At the end of checkout you should be redirected to the simulator. This will let you get familiar with the various redirects and callback.

Gateway signing mechanism

All requests and responses must be signed/verified using HMAC-SHA256 where:

  • key is a value known to both the Shopify merchant and you. This is typically the "Password" field for the merchant.

  • message is a string of all key-value pairs that start with x_ prefix, sorted alphabetically, and concatenated without separators.

Assuming your HMAC key is "iU44RWxeik", the signing mechanisms would look like this:

fields = {x_account_id: 'Z9s7Yt0Txsqbbx', x_amount: 89.99, x_currency: 'USD', x_gateway_reference: '123', x_reference: "19783", x_result: "completed", x_test: "true",  x_timestamp: '2014-03-24T12:15:41Z'}
=> {:x_account_id=>"Z9s7Yt0Txsqbbx", :x_amount=>89.99, :x_currency=>"USD", :x_gateway_reference=>"123", :x_reference=>"19783", :x_result=>"completed", :x_test=>"true", :x_timestamp=>"2014-03-24T12:15:41Z"}
message = fields.sort.join
=> "x_account_idZ9s7Yt0Txsqbbxx_amount89.99x_currencyUSDx_gateway_reference123x_reference19783x_resultcompletedx_testtruex_timestamp2014-03-24T12:15:41Z"
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), 'iU44RWxeik', message)
=> "49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d2386404b610777"

"x_signature=49d3166063b4d881b50af0b4648c1244bfa9890a53ed6bce6d2386404b610777"

You can use the provided Signature Calculator to confirm that your signature generation function is working appropriately.

A working example of HMAC-SHA256 signing is available in our Hosted Payment Simulator GitHub repository.

If your integration looks like it is working, you can now add your payment gateway to your Shopify Partners account before publishing it.

Sign up for a Partner account to get started.

Sign up