Payments app request reference

This guide provides a comprehensive reference for the HTTP POST requests that initiate actions taken by your Payments app. The action flows begins with an HTTP POST request sent from Shopify to your payments app extension. Each request is different depending on the action flow you are trying to configure.

Anchor to Offsite paymentOffsite payment

The offsite payment flow begins with an HTTP POST request sent from Shopify to the payment session URL of your offsite payments app extension provided during app extension configuration. This request contains information about the customer and the order.

Shopify must receive an HTTP 2xx response with redirect_url (URL for the Partner page where Shopify redirects the customer) for the payment session creation to be successful. The redirect_url response should be less than 8192 bytes in length.

If the request fails, then it's retried several times. If the request still fails, then the customer needs to retry their payment through Shopify checkout.

If there's an error on the payments app's side, then don't respond with an HTTP 2xx. Use an appropriate error status code instead.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Anchor to Credit card paymentCredit card payment

The credit card payment flow begins with an HTTP POST request sent from Shopify to the payment session URL of your credit card payments app extension provided during app extension configuration. This request contains information about the customer and the order, and, for 3-D Secure, client details.

Shopify must receive an HTTP 2xx response for the payment session creation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the customer needs to retry their payment through Shopify checkout.

If there's an error on the payments app's side, then don't respond with an HTTP 2xx. Use an appropriate error status code instead.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Anchor to RefundRefund

The refund flow begins with an HTTP POST request sent from Shopify to the payments app's refund session URL provided during app extension configuration:

Start session

Request header

Shopify-Shop-Domain: my-test-shop.myshopify.com

Shopify-Request-Id: afd2de66-cda5-4486-879f-6a2b0071293b

Shopify-Api-Version: 2025-07

Request body

{

"id": "PJUG6iB0xU7czy1ZN3xEwn4o",

"gid": "gid://shopify\/RefundSession/PJUG6iB0xU7czy1ZN3xEwn4o",

"payment_id": "u0nwmSrNntjIWozmNslK5Tlq",

"amount": "123.00",

"currency": "CAD",

"test": false,

"merchant_locale": "en",

"proposed_at": "2021-07-13T00:00:00Z"

}

Response body

Shopify must receive an HTTP 201 (Created) response for the refund session creation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the refund in the Shopify admin.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Attribute	Description	Type
`id`required	The unique identifier for the refund attempt. Used as the idempotency key. It can be assumed that requests with a given ID are identical to any previously-received requests with the same ID.	`String`
`gid`required	Identifies the refund when communicating with Shopify (in GraphQL mutations, for example).	`String`
`payment_id`required	The ID of the original payment that is to be refunded. For captured payments, this ID corresponds to the original authorization ID rather than the capture ID.	`String`
`amount`required	The amount to be refunded. The amount is always sent using a decimal point as a separator, regardless of locale.	`String`
`currency`required	Three-letter ISO 4217 currency code.	`String`
`test`required	Indicates whether the refund is in test or live mode. The `test` field is only sent if you select API version `2022-01` or higher in the payments app extension configuration in Shopify CLI. For more information, refer to Test a payments app.	`Boolean`
`merchant_locale`required	The IETF BCP 47 language tag representing the language used by the merchant.	`String`
`proposed_at`required	A timestamp (ISO-8601) representing when the refund request was proposed.	`String`

Anchor to CaptureCapture

The capture flow begins with an HTTP POST request sent from Shopify to the payments app's capture session URL provided during app extension configuration:

Start session

Request header

Shopify-Shop-Domain: my-test-shop.myshopify.com

Shopify-Request-Id: 70a330cc-8411-47ef-bcc3-650bc1acccf2

Shopify-Api-Version: 2025-07

Request body

{

"id": "GZl9N9ghFvUrYhVONQIj59Rj",

"gid": "gid://shopify\/CaptureSession/GZl9N9ghFvUrYhVONQIj59Rj",

"payment_id": "u0nwmSrNntjIWozmNslK5Tlq",

"amount": "123.00",

"currency": "CAD",

"test": false,

"merchant_locale": "en",

"proposed_at": "2021-07-13T00:00:00Z"

}

Response body

Shopify must receive an HTTP 201 (Created) response for the capture session creation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the capture in the Shopify admin.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Attribute	Description	Type
`id`required	The unique identifier for the capture attempt. Used as the idempotency key. Assume that requests with a given ID are identical to any previously-received requests with the same ID.	`String`
`gid`required	Identifies the capture when communicating with Shopify in GraphQL mutations, for example.	`String`
`payment_id`required	The ID of the authorized payment that is to be captured.	`String`
`amount`required	The amount to be captured. The value is always sent using a decimal point as a separator, regardless of locale.	`String`
`currency`required	The three-letter ISO 4217 currency code.	`String`
`test`required	Indicates whether the capture is in test or live mode. The `test` field is only sent if you select API version `2022-01` or higher in the payments app extension configuration in Shopify CLI. For more information, refer to Test a payments app.	`Boolean`
`merchant_locale`required	The IETF BCP 47 language tag representing the language used by the merchant.	`String`
`proposed_at`required	A timestamp representing when the capture request was proposed.	`String (ISO-8601)`

Anchor to VoidVoid

The void flow begins with an HTTP POST request sent from Shopify to the payments app's void session URL provided during app extension configuration:

Start session

Request header

Shopify-Shop-Domain: my-test-shop.myshopify.com

Shopify-Request-Id: c42e7408-d87c-4048-a493-b941e4f8ae4f

Shopify-Api-Version: 2025-07

Request body

{

"id": "rAQVz9SYrBs9RkEetRPKIqKfU",

"gid": "gid://shopify\/VoidSession/rAQVz9SYrBs9RkEetRPKIqKfU",

"payment_id": "u0nwmSrNntjIWozmNslK5Tlq",

"test": false,

"merchant_locale": "en",

"proposed_at": "2021-07-13T00:00:00Z"

}

Response body

Shopify must receive an HTTP 201 (Created) response for the void session creation to be successful.

If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the void in the Shopify admin.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Attribute	Description	Type
`id`required	The unique identifier for the void attempt. Used as the idempotency key. It can be assumed that requests with a given ID are identical to any previously-received requests with the same ID.	`String`
`gid`required	Identifies the void when communicating with Shopify (in GraphQL mutations, for example).	`String`
`payment_id`required	The ID of the authorized payment that is to be voided.	`String`
`test`required	Indicates whether the void is in test or live mode. The `test` field is only sent if you select API version `2022-01` or higher in the payments app extension configuration in Shopify CLI. For more information, refer to Test a payments app.	`Boolean`
`merchant_locale`required	The IETF BCP 47 language tag representing the language used by the merchant.	`String`
`proposed_at`required	A timestamp (ISO-8601) representing when the void request was proposed.	`String`

Anchor to Confirm a payment (3-D Secure and Inventory confirmation)Confirm a payment (3-D Secure and Inventory confirmation)

When Shopify determines if the payment request can proceed, Shopify sends a POST request to the confirm session URL of the credit card payments app extension, delivering the confirmation result.

Anchor to Request headersRequest headers

Header	Description
`Shopify-Shop-Domain`required	The permanent domain of the shop. Can be used to identify which shop is initiating the request.
`Shopify-Request-Id`required	The unique request ID used to track specific requests for troubleshooting purposes.
`Shopify-Api-Version`required	The API version selected in the payments app configuration. The version selected defines the response expected by the payments app.

Anchor to Request bodyRequest body

Attribute	Description	Type
`id`required	The unique identifier for the payment, as provided in the HTTP POST request sent from Shopify to the payment session URL. Used as the idempotency key. It can be assumed that requests with a given `id` are identical to any previously received requests with the same `id`.
`gid`required	Identifies the payment when communicating with Shopify (in GraphQL mutations, for example).	`String`
`confirmation_result`required	Result of the payment confirmation initiated by the `paymentSessionConfirm` mutation. The payment app can proceed with the payment request if and only if `confirmation_result` is `true`	`Boolean`

Was this page helpful?