We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Adding order management to your gateway

The Hosted Payment SDK has order management features that allow merchants who use your gateway to capture, refund, and void payments for orders in the Shopify admin. To add order management features to your gateway integration, you should already have created a gateway integration with the Hosted Payments SDK.

Capture payments

When a merchant decides to capture a transaction in the Shopify admin, Shopify sends the Request Values to your app, with the x_transaction_type set to capture:

Key Type Example
x_transaction_type fixed choice capture

Your app needs to send back the Response Values with the x_transaction_type set to authorization:

Key Type Example
x_transaction_type fixed choice authorization

How a manual capture works

  1. The merchant clicks the capture button on an order page in the Shopify admin.

  2. Shopify sends a POST JSON request to your capture URL with the Request Values.

  3. Your server posts a callback to x_url_callback with the Response Values.

Set up manual capture for your merchants

To set your capture URL:

  1. Log in to the Partner Dashboard.

  2. Click Payment gateways.

  3. Click the name of your payment gateway.

  4. On your payment gateway's page, click Edit gateway settings.

  5. In the Payment URLs section, enter the url of your gateway's capture endpoint in the Capture URL field.

When a merchant makes a capture in the Shopify admin, Shopify will send the Request Values to your Capture URL.

Refund payments

When a merchant decides to refund a transaction in the Shopify admin, Shopify sends the Request Values to your app, with the x_transaction_type set to refund:

Key Type Example
x_transaction_type fixed choice refund

Your app needs to send the Response Values to Shopify with the x_transaction_type set to refund:

Key Type Example
x_transaction_type fixed choice refund

How a refund works

  1. The merchant clicks the refund button on an order page in the Shopify admin.

  2. Shopify sends a POST JSON request to your refund url with the Request Values.

  3. Your server posts a callback to x_url_callback with the Response Values.

Set up refunds for your merchants

To set your refund URL:

  1. Log in to the Partner Dashboard.

  2. Click Payment gateways.

  3. Click the name of your payment gateway.

  4. On your payment gateway's page, click Edit gateway settings.

  5. In the Payment URLs section, enter the url of your gateway's capture endpoint in the Refund URL field.

When a merchant gives a refund from the Shopify admin, the Request Values will be sent to your Refund URL.

Void payments

When a merchant decides to capture a transaction in the Shopify admin, Shopify sends the Request Values to your app, with the x_transaction_type set to void:

Key Type Example
x_transaction_type fixed choice void

Then, your app needs to send the Response Values to Shopify, with the x_transaction_type set to refund:

Key Type Example
x_transaction_type fixed choice refund

How a void works

  1. The merchant clicks the cancel button on an order page in the Shopify admin.

  2. Shopify sends a POST JSON request to your void url with the Request Values.

  3. Your server posts a callback to x_url_callback with the Response Values.

Set up voids for your merchants

To set up your void URL:

  1. Log in to the Partner Dashboard.

  2. Click Payment gateways.

  3. Click the name of your payment gateway.

  4. On your payment gateway's page, click Edit gateway settings.

  5. In the Payment URLs section, enter the url of your gateway's capture endpoint in the Void URL field.

When a merchant gives a refund from the Shopify admin, the Request Values will be sent to your Void URL.

Sign up for a Partner account to get started.

Sign up