This is a common API that simplifies the onboarding of new payment providers, specifically Offsite Gateways / Hosted Payment Pages, that are looking to be used on Shopify. By supporting a common API for redirect, cancel, complete, and callback phases of a payment flow, we are giving gateway implementers a way to integrate with Shopify at any time, without requiring a large amount of customization or validation work or bottlenecks by the Shopify integration team.
Follow these simple steps to get started.
- Review the rest of this document
- Sign up for a free trial of Shopify at http://www.shopify.com/. You will use this shop to place test orders against your offsite gateway.
- Send the name of this shop to payment-integrations@shopify.com and mention Universal Offsite Dev Kit in the subject
Once we enable developer mode, which normally happens the same day, you'll be ready to proceed with integration testing.
- Sign in to your Shopify store.
- Go to Products and add a dummy product.
- Go to Settings/Checkout, and select the Universal Offsite Dev Kit in the gateway dropdown.
- Complete the 3 fields,
x_account_id- this is an identifier for a test merchant on your systemHMAC key- this is a key your gateway will use to verify requests and sign responsesPOST URL- this is URL on your system that will properly handle Request Values and is then able to provide proper Response Values to various return URLs at Shopify
- Now you're ready to test! From your admin, click the 'view your website' link, and add a product to your cart. On the cart page, click the "Check out" button, enter in some dummy info, and complete the checkout using your gateway.
We are providing this simple implementation of an Offsite Gateway Sim as a way to demonstrate basics of this new API. If you want to see it in action, leave
POST URLon your Universal Offsite Dev Kit empty, or set it tohttps://offsite-gateway-sim.herokuapp.com/, then try placing another order in your test shop.As soon as you are confident that your implementation is complete, we'll need to collect some more information about your gateway,
- Labels for any fields that your gateway will require shops to input when setting it up within Shopify.
- Your gateway name
- Label for the
x_account_idfield, needs to match your existing terminology, e.g.Merchant IDorAccount #- Label for the
HMAC keyfield, needs to match your existing terminology, e.g.KeyorShared Secret- URL of a POST handler for Request Values that presents a payment flow to the customer, likely the same one you used to configure Universal Offsite Dev Kit gateway during integration testing
- Your gateway's home page URL
- Image to display to customers during checkout process that identifies your gateway and/or supported payment options (PNG, height: 20px, max width: 350px)
- Finally, please indicate whether or not your gateway supports
x_testmode
- Customer initiates checkout on the Shopify storefront
- Browser is redirected to gateway's URL using a POST request along with Request Values (mandatory + whatever else may be available)
- Gateway verifies
x_signaturevalue and presents their own payment flow to the customer (see Signing Mechanism)- Customers who exit the payment flow before successfully completing it should be redirected back to
x_url_cancel- Customers who complete the payment flow should be redirected back to
x_url_completewith all required Response Values as query parameters, includingx_signature(see Signing Mechanism)- We strongly recommend that gateway also POSTs a callback asynchronously to
x_url_callbackwith the same Response Values. This ensures that order can be completed even in cases where customer's connection to Shopify is terminated prematurely- 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 notifications for the same
x_referenceare ignored by ShopifyAll requests and responses must be signed/verified using
HMAC-SHA256(HMAC) where,
keyis a value known to both Shopify (HMAC keyfield in gateway settings) and the gateway itselfmessageis a string of all key-value pairs that start withx_prefix, sorted alphabetically, and concatenated without any separators
- Resulting codes must be hex-encoded and passed as value of
x_signature- Make sure to use case-insensitive comparison when verifying provided
x_signaturevaluesFor example,
fields = {x_account_id: 123, x_currency: 'USD'} => {:x_account_id=>123, :x_currency=>"USD"} message = fields.sort.join => "x_account_id123x_currencyUSD" OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), 'secret key', message) => "06ef4be2654e089b4aa346f970a71988fa3a1452acaa6273573f9db0c32ea355" "x_signature=06ef4be2654e089b4aa346f970a71988fa3a1452acaa6273573f9db0c32ea355"
Key Type Mandatory Example Comment x_account_idunicode string ✓ Z9s7Yt0Txsqbbx This is an account identifier assigned to the merchant by the payment processor. x_currencyiso-4217 ✓ USD x_amountdecimal ✓ 89.99 x_amount_shippingdecimal 8.99 x_amount_taxdecimal 11.70 x_referenceascii string ✓ 19783 Unique reference of an order assigned by the merchant. x_shop_countryiso-3166-1 alpha-2 ✓ US x_shop_nameunicode string ✓ Widgets Inc x_transaction_typeascii string sale x_descriptionunicode string Order #123 x_invoiceunicode string #123 x_testtrue/false ✓ true Indicates whether or not this request should be processed in test mode (if supported). x_customer_first_nameunicode string Boris x_customer_last_nameunicode string Slobodin x_customer_emailunicode string boris.slobodin@example.com x_customer_phoneunicode string +1-613-987-6543 x_customer_shipping_cityunicode string Toronto x_customer_shipping_companyunicode string Shopify Toronto x_customer_shipping_address1unicode string 241 Spadina Ave x_customer_shipping_address2unicode string x_customer_shipping_stateunicode string ON x_customer_shipping_zipunicode string M5T 3A8 x_customer_shipping_countryiso-3166-1 alpha-2 CA x_customer_shipping_phoneunicode string +1-416-123-4567 x_url_callbackurl ✓ https://myshopify.io/ping/1 URL to which a callback notification should be sent asynchronously. x_url_cancelurl ✓ https://myshopify.io URL to which customer must be redirected when they wish to quit payment flow and return to the merchant's site. x_url_completeurl ✓ https://myshopify.io/orders/1/done URL to which customer must be redirected upon successfully completing payment flow. x_timestampiso-8601 in UTC ✓ 2014-03-24T12:13:12Z x_signaturehex string, case-insensitive ✓ 3a59e201a9b8692702b8c41dcba476d4a46e5f5c See Signing Mechanism.
Key Type Mandatory Example Comment x_account_idunicode string ✓ Z9s7Yt0Txsqbbx Echo request's x_account_idx_referenceascii string ✓ 19783 Echo request's x_referencex_currencyiso-4217 ✓ USD Echo request's x_currencyx_testtrue/false ✓ true Echo request's x_testx_amountdecimal ✓ 89.99 Echo request's x_amountx_gateway_referenceunicode string ✓ 123 Unique reference for the authorization issued by the payment processor. x_timestampiso-8601 in UTC ✓ 2014-03-24T12:15:41Z x_resultfixed choice ✓ completed One of: completed, failed, pending x_signaturehex string, case-insensitive ✓ 3a59e201a9b8692702b8c41dcba476d4a46e5f5c See Signing Mechanism.