General transaction requirements

Payments apps must operate in accordance with the following general requirements for transactions, including support for test mode.

mTLS configuration

Payments apps must implement mTLS. Using mTLS ensures that traffic between Shopify and the payments app is trusted and secure.

You must use a Trusted CA Signed SSL Certificate for your server certificate, not Shopify’s self-signed CA. You should use Shopify’s self-signed CA to validate Shopify’s client certificate.

Shopify's Payments Platform Root CA -----BEGIN CERTIFICATE----- MIICQTCCAeigAwIBAgIUe+t5Y8PXvczEIT25w+VFTeKQUn4wCgYIKoZIzj0EAwIw bTELMAkGA1UEBhMCQ0ExEDAOBgNVBAgTB09udGFyaW8xDzANBgNVBAcTBk90dGF3 YTEQMA4GA1UEChMHU2hvcGlmeTEpMCcGA1UEAxMgU2hvcGlmeSBQYXltZW50IFBs YXRmb3JtIFJvb3QgQ0EwHhcNMjEwMjI1MTk0OTQ5WhcNMjkwMjIzMTk1MDE5WjBt MQswCQYDVQQGEwJDQTEQMA4GA1UECBMHT250YXJpbzEPMA0GA1UEBxMGT3R0YXdh MRAwDgYDVQQKEwdTaG9waWZ5MSkwJwYDVQQDEyBTaG9waWZ5IFBheW1lbnQgUGxh dGZvcm0gUm9vdCBDQTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABE2tRNrL28gM eD6cVH1Evn40gTzoy+aH47QnAhs6oHBZ+pgN1iCK9G6u/Va1BdWqsbmmZMZfZkY4 x+kqHRjw29GjZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgED MB0GA1UdDgQWBBRVqavxvOa9K9SKEuHz4ZmXcCyy5DAfBgNVHSMEGDAWgBRVqavx vOa9K9SKEuHz4ZmXcCyy5DAKBggqhkjOPQQDAgNHADBEAiB+pPrzREg+NpenROMY n5IH3OrORXERggd0+YLI5HhL/wIgcAo70tOV/0Vv9oGFjNbI9TpkeFUgb8Rc5Gh6 65LHwoQ= -----END CERTIFICATE-----
Shopify's Payments Platform Secondary CA Production -----BEGIN CERTIFICATE----- MIICUjCCAfigAwIBAgIUXLkjZ6s/S+FzEbQABn9FmC3vCD8wCgYIKoZIzj0EAwIw bTELMAkGA1UEBhMCQ0ExEDAOBgNVBAgTB09udGFyaW8xDzANBgNVBAcTBk90dGF3 YTEQMA4GA1UEChMHU2hvcGlmeTEpMCcGA1UEAxMgU2hvcGlmeSBQYXltZW50IFBs YXRmb3JtIFJvb3QgQ0EwHhcNMjEwMjI1MTk0OTU1WhcNMjQwMjI1MTk1MDI1WjB9 MQswCQYDVQQGEwJDQTEQMA4GA1UECBMHT250YXJpbzEPMA0GA1UEBxMGT3R0YXdh MRAwDgYDVQQKEwdTaG9waWZ5MTkwNwYDVQQDEzBTaG9waWZ5IFBheW1lbnQgUGxh dGZvcm0gU2Vjb25kYXJ5IENBIFByb2R1Y3Rpb24wWTATBgcqhkjOPQIBBggqhkjO PQMBBwNCAASB/PJiqXjVxmdKWsAjg8ljtdB6th71ZuiSjyMIHfUqe1zUGkNlGfhc Wdxb/XSY1RiO0uZZJUTGsr37Aj42mPgDo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD VR0TAQH/BAgwBgEB/wIBATAdBgNVHQ4EFgQU9PLeHDNrctw7CkA6UhSNOZU8uVEw HwYDVR0jBBgwFoAUVamr8bzmvSvUihLh8+GZl3AssuQwCgYIKoZIzj0EAwIDSAAw RQIhAJkeNxYqCCPo115sgd20SN/87olMagNZqlJa8GZbo4oDAiB9S88ga4jsZCvA ciExpaKrSSFdl4TTxpfLiNZX0OFU5w== -----END CERTIFICATE-----

Idempotency

Payments Apps APIs (HTTP requests from Shopify to your app)

You need to support idempotent requests for the Payments Apps APIs. Regardless of how many requests with the same idempotency key are sent, the result must be the same.

Support for idempotency allows Shopify to safely retry requests without accidentally performing the same operation twice. This is critical in cases where there are network errors to prevent, such as multiple charges for the same payment.

The idempotency key attributes are defined on a per-API basis.

GraphQL mutations (requests to Shopify)

Idempotency is implemented, for a given id, at a per operation name level. If multiple mutation requests of the same name are sent, then the operation is performed only once and the same response is returned. For example, this would occur if several PaymentSessionResolve requests were sent with the same id.

If requests with different names are sent with the same id, then only the first request is processed. For example, if both a PaymentSessionResolve and PaymentSessionReject request are sent for the same payment id, then the PaymentSessionResolve request is processed, and the PaymentSessionReject request fails and returns a user_error.

Retry policy

Due to the asynchronous nature of Shopify's Payments Apps APIs, you must send a GraphQL request to notify Shopify of the results of any payment or refund requests. A retry policy helps provide data consistency between merchants, partners, and Shopify.

If you don't receive an acknowledgment of a GraphQL request (HTTP 200 status code), then you must retry the request according to the following incremental strategy, up to a total of 18 retries over 24h.

Parameter Description Value
Number of recommended retries The maximum number of recommended retries. 18
Base delay interval The time interval after which the first retry is attempted. 5 seconds
Exponential backoff factor Partners are expected to retry their requests immediately, and then 5 seconds afterwards, and then at increasing time intervals after that, until the request is acknowledged or 24 hours has passed, whichever comes first. See example

Example:

[0 seconds, 5 seconds, 10 seconds, 30 seconds, 30 seconds, 45 seconds, 1 minute, 2 minutes, 5 minutes, 12 minutes, 38 minutes, 1 hour, 2 hours] + [4 hours] * 5

You must implement a retry policy for the following mutations:

Rate limiting

To protect the stability of the platform, payments apps are rate-limited. For more information, refer to Shopify API rate limits

Test mode

Payments apps must support test mode. When a store is in test mode, requests from Shopify include the test attribute. If this attribute it set to true, then the payment is processed as a test payment and no money is moved. Test mode simplifies the process of building a payments app and allows merchants to test the integration before they begin processing live transactions.

Considerations for development stores

When using a development store, the payment gateway must have test mode enabled to process payments. Otherwise, Shopify blocks payment attempts.

Next steps

Additional information