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. ## Offsite 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.
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. |
Attribute | Description | Type |
---|---|---|
id Required |
Unique identifier for the payment 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. This ID must be surfaced to the merchant so that they can correlate Shopify orders with payments managed by the Partner app. | String |
gid Required |
Identifies the payment when communicating with Shopify (in GraphQL mutations, for example). | String |
group Required |
The identifier that's shared across payment sessions, representing attempts to complete the same checkout or deferred payment capture. | String |
session_id Required |
The identifier that's shared across payment sessions that belong to the same payment group, buyer session, and share payment details. Only available in API version 2024-10 and later. | String |
amount Required |
The amount to be charged. The value 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 payment is in test or live mode. Refer to Test mode for more information. | Boolean |
merchant_locale Required |
IETF BCP 47 language tag representing the language used by the merchant. | String |
payment_method Required |
Hash giving details on the payment method used. Refer to payment_method hash for more information. | Hash |
proposed_at Required |
Can be used to order payment attempts that are a part of the same group. | String (ISO-8601) |
customer |
If customer is included, then at least one of customer.email or customer.phone_number is present. For more information on the customer field, refer to the customer hash. |
Hash |
kind Required |
Either sale or authorization . If you support payment authorization, then this value is set based on the merchant's configuration. If you don't support separate authorization and capture, then the value is always sale . For sale transactions, you need to capture the funds instantly with this request. For authorization transactions, you must place a hold on the funds and capture them later when Shopify sends a capture request. |
String |
payment_method
hash
Attribute | Description | Type |
---|---|---|
type Required |
The type of payment method. Possible values: ["offsite" ]. |
String |
data Required |
Contains data relevant for the chosen payment method. Refer to payment_method.data hash for more information. | Hash |
payment_method.data
hash
Attribute | Description | Type |
---|---|---|
cancel_url Required |
The URL to redirect the customer when the customer quits the payment flow and returns to the merchant's website. The cancel_url attribute should only be used when a customer is on the provider page and decides to cancel their payment and return to Shopify. |
String |
customer
hash
Attribute | Description | Type |
---|---|---|
email |
The email of the customer. Required if phone_number isn't present. |
String |
phone_number |
The phone number of the customer. Required if email isn't present. |
String |
locale Required |
The language code as an ISO 639-1 string and the country code as an ISO 3166-1 Alpha-2 string, if available. For more information on the locale field, refer to the locale fields changelog. | String |
billing_address Required |
The billing address of the customer. Refer to shipping/billing_address hash for more information. | Hash |
shipping_address Required* |
The shipping address for the order. Refer to shipping/billing_address hash for more information. *A shipping address isn't sent for digital products. |
Hash |
shipping/billing_address
hash
Attribute | Description | Type |
---|---|---|
given_name |
The given name or first name of the customer. | String |
family_name Required |
The surname of the customer. | String |
line1 Required |
First line of the customer's address (for example, the street or PO box). | String |
line2 |
Second line of the customer's address (for example, the apartment or suite). | String |
city Required |
Name of city or town. | String |
postal_code |
Zip or postal code. | String |
province |
Name of the province or state. | String |
country_code Required |
The country code as an ISO 3166-1 Alpha-2 string. | String |
phone_number |
The phone number of the customer. | String |
company |
Name of company. | String |
given_name
, line2
, postal_code
, province
and company
fields are optional, depending on the customer's locality.
## Credit 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.
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. |
Attribute | Description | Type |
---|---|---|
id Required |
Unique identifier for the payment 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. This ID must be surfaced to the merchant so that they can correlate Shopify orders with payments managed by the Partner app. | String |
gid Required |
Identifies the payment when communicating with Shopify (in GraphQL mutations, for example). | String |
group Required |
The identifier that's shared across payment sessions, representing attempts to complete the same checkout or deferred payment capture. | String |
session_id Required |
The identifier that's shared across payment sessions that belong to the same payment group, buyer session, and share payment details. Only available in API version 2024-10 and later. | String |
amount Required |
The amount to be charged. The value 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 payment is in test or live mode. Refer to Test mode for more information. | Boolean |
merchant_locale Required |
IETF BCP 47 language tag representing the language used by the merchant. | String |
payment_method Required |
Hash giving details on the payment method used. Refer to payment_method hash for more information. | Hash |
proposed_at Required |
Can be used to order payment attempts that are a part of the same group. | String (ISO-8601) |
customer |
If customer is included, then at least one of customer.email or customer.phone_number is present. For more information on the customer field, refer to the customer hash. |
Hash |
kind Required |
Either sale or authorization . For sale transactions, you need to capture the funds instantly with this request. For authorization transactions, you must place a hold on the funds and capture them later when Shopify sends a capture request. |
String |
client_details |
Details about the browser of the customer, if your credit card payments app extension supports the 3-D Secure authentication customer feature. For more information on the client_details field, refer to the client_details hash. |
Hash |
payment_method
hash
Attribute | Description | Type |
---|---|---|
type Required |
The type of payment method. Possible values: ["credit_card" ]. |
String |
data Required |
Contains data relevant for the chosen payment method. Refer to payment_method.data hash for more information. | Hash |
payment_method.data
hash
Attribute | Description | Type |
---|---|---|
fingerprint Required |
The fingerprint of the certificate that’s used to encrypt the credit card information of the customer. | String |
encrypted_message Required |
The encrypted credit card information of the customer strictly encoded as Base64. Learn how to decrypt encrypted_message and the structure of decrypted data. | String |
ephemeral_public_key Required |
The ephemeral public key that should be used with the private key to compute the shared secret, and to decrypt encrypted_message . |
String |
tag Required |
HMAC digest of the encrypted_message strictly encoded as Base64. |
String |
moto Required |
Whether the payment is Mail Order/Telephone Order. Only available in API version 2024-07 and later. | Boolean |
encrypted_message
The credit card information of the customer is encrypted using ECIES hybrid encryption scheme. You can follow the following steps to decrypt the credit card information:
1. Decode the Base64 encoded `encrypted_message` and `tag`.
2. Use `fingerprint` to identify the certificate that's used for encryption.
3. Compute shared secret using the private key of the certificate and `ephemeral_public_key`.
4. Compute the hmac of decoded `encrypted_message` and ensure it matches the decoded value of `tag`.
5. Decrypt `encrypted_message`.
> Caution:
> The application or service that decrypts the value of the `encrypted_message` must be in a PCI DSS compliant environment.
Attribute | Description | Type |
---|---|---|
type Required |
The type of card. | String |
data Required |
Contains data relevant to the encrypted message. Refer to encrypted_message_data hash for more information. | Hash |
encrypted_message_data
hash
Returned hash in API version `2024-04`:
Attribute | Description | Type |
---|---|---|
full_name Required |
The full name of the card holder. | String |
pan Required |
The card number used for payment. | String |
month Required |
The card's month of expiry. | Numeric |
year Required |
The card's year of expiry. | Numeric |
verification_value Required |
The card's security code, for example CSC, CVC, CVV. | String |
Attribute | Description | Type |
---|---|---|
full_name Required |
The full name of the card holder. | String |
pan Required |
The card number used for payment. | String |
month Required |
The card's month of expiry. | Numeric |
year Required |
The card's year of expiry. | Numeric |
verification_value Required |
The card's security code, for example CSC, CVC, CVV. | String |
network |
The customer's preferred processing network.
In specific circumstances, customers using co-badged cards (for example Visa + Cartes Bancaires cards in the EU) are able to choose which network should be used to process the transaction. If the customer doesn't make a choice, the network field will be omitted. |
String |
customer
hash
Attribute | Description | Type |
---|---|---|
email |
The email of the customer. Required if phone_number isn't present. |
String |
phone_number |
The phone number of the customer. Required if email isn't present. |
String |
locale Required |
The language code as an ISO 639-1 string and the country code as an ISO 3166-1 Alpha-2 string, if available. For more information on the locale field, refer to the locale fields changelog. | String |
billing_address Required |
The billing address of the customer. Refer to shipping/billing_address hash for more information. | Hash |
shipping_address Required* |
The shipping address for the order. Refer to shipping/billing_address hash for more information. *A shipping address isn't sent for digital products. |
Hash |
shipping/billing_address
hash
Attribute | Description | Type |
---|---|---|
given_name |
The given name or first name of the customer. | String |
family_name Required |
The surname of the customer. | String |
line1 Required |
First line of the customer's address (for example, the street or PO box). | String |
line2 |
Second line of the customer's address (for example, the apartment or suite). | String |
city Required |
Name of city or town. | String |
postal_code |
Zip or postal code. | String |
province |
Name of the province or state. | String |
country_code Required |
The country code as an ISO 3166-1 Alpha-2 string. | String |
phone_number |
The phone number of the customer. | String |
company |
Name of company. | String |
given_name
, line2
, postal_code
, province
and company
fields are optional, depending on the customer's locality.
#### client_details
hash
Attribute | Description | Type |
---|---|---|
ip_address Required |
The IP address from the browser of the customer. | String |
user_agent Required |
The HTTP user-agent header from the browser of the customer. | String |
accept_language Required |
The HTTP accept-language header from the browser of the customer. | String |
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. |
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 |
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. |
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) |
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. |
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 |
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. |
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 |