Process a credit card payment

Payment processing begins when Shopify makes an HTTP call to your payments app. Your app responds with a 200 HTTP status. After the payment is finalized, you need to communicate the result to Shopify using the paymentSessionResolve or paymentSessionReject mutation. After the paymentSessionResolve or paymentSessionReject mutation is called, you can't change the payment state.

The following diagram illustrates how a payment flow works between the payments app and Shopify:

1. The customer completes checkout, triggering a request for payment.
2. Shopify sends a backend request to the payments app, specifying the amount and currency to be charged and the encrypted credit card information.
3. The app responds with an HTTP code 200 (OK), indicating that the request is valid and has been received.
4. The payments app processes the payment with the payment information received in the request.
5. The payments app finalizes the payment as resolved or rejected by calling Shopify's GraphQL API, implementing a retry policy as needed.
6. Shopify responds with an HTTP code 200 (OK) to confirm the payment state is updated.
7. The customer continues to checkout.

Similar to how it works without 3-D Secure, payment processing begins when Shopify makes an HTTP call to your payments app. Your app responds with a 200 HTTP status.

If your app supports 3-D Secure and determines that the customer must be redirected for 3-D Secure, you must communicate to Shopify the URL where the customer is to be redirected. Your app communicates this URL using the paymentSessionRedirect mutation. Shopify renders the URL provided by the app in an iFrame in the customer's browser, and then the app processes the 3-D Secure authentication.

Once the app has completed the 3-D secure authentication steps and does not want to not proceed with the payment, it calls the paymentSessionReject mutation.

If the app wants to proceed with the payment, the app calls the paymentSessionConfirm mutation. After Shopify has responded to the paymentSessionConfirm mutation, the app redirects the customer and Shopify makes an HTTP call to the confirm session URL of the credit card payments app extension, indicating whether the app can proceed with the payment. Once the app has finalized the payment, the app communicates the result to Shopify using the paymentSessionResolve or paymentSessionReject mutation.

The following diagram illustrates how a payment flow works between the payments app and Shopify:

1. The customer completes checkout, triggering a request for payment.
2. Shopify sends a backend request to the payments app, specifying the amount and currency to be charged and the encrypted credit card information.
3. The app responds with an HTTP code 200 (OK), indicating that the request is valid and has been received.

4. The payments app determines whether the customer must be redirected for 3-D Secure authentication. If the customer must be redirected, then the app proceeds through the following substeps.

   1. The app calls the paymentSessionRedirect mutation to indicate that a redirect is required, implementing a retry policy as needed. Shopify responds, indicating that the request is valid and has been received.
   2. Shopify redirects the customer in an iFrame where the 3-D Secure authentication can be performed. The customer may be challenged during the 3-D Secure authentication.
   3. Once the payments app has completed the 3-D Secure authentication steps and the authentication has not been rejected, the app calls the paymentSessionConfirm mutation to confirm with Shopify whether the payment request can proceed, implementing a retry policy as needed. Shopify responds, indicating that the request is valid and provides a redirect URL for partners to redirect customers back to Shopify.
   4. According to its business logic, Shopify determines if the payment can proceed and sends a POST request to the confirm session URL of the credit card payments app extension, delivering the confirmation result.
   5. The app responds with an HTTP code 200 (OK) for the request, indicating that the request is valid and has been received.
   6. If Shopify indicates that the payment can proceed, the payments app processes the payment with the payment information sent in step 2.

5. The app finalizes the payment as resolved or rejected by calling Shopify's GraphQL API, implementing a retry policy as needed, and provides the 3-D Secure data.
   Shopify fails the Resolve and Reject mutation calls if Shopify has not yet sent a confirmation result to the confirm session URL of the credit card payments app extension. Once Shopify has sent a confirmation result to the partner Confirm session URL, Shopify will NOT fail the Resolve and Reject mutation calls, even if Shopify has not received a response from the partner.

6. Shopify responds with an HTTP code 200 (OK) for the request in step 5.

7. The customer continues to checkout.

This kind of failure may happen due to the following reasons.

• The customer authentication is rejected. This corresponds to the transStatus value R. The EMVCo specification indicates that the “Issuer is rejecting authentication/verification and request that authorization not be attempted”.

• There’s been an error preventing the authentication step from being completed.

In these cases, the payments app can decide whether or not to proceed with the payment based on merchant’s configurations on the partner side. If the payments app does not want to proceed with the payment, then it must invoke the paymentSessionReject mutation with AUTHENTICATION_FAILED.

This may happen when Shopify does not want to proceed with the payment because some business conditions changed during the time elapsed since the authentication process got initiated through the paymentSessionRedirect mutation by the payments app.

In this case, the payments app must invoke the paymentSessionReject mutation using the CONFIRMATION_REJECTED reason code.

Depending on how the payments app integrates with the 3-D Secure back-end, the payments app may have to provide an intermediate landing page to orchestrate the interactions with the 3-D Secure back-end and, after the customer has completed the 3-D Secure authentication, call the paymentSessionConfirm mutation.

The 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.

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 certificate_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.

After the payments app has determined it needs to orchestrate a 3-D Secure authentication, the app uses the paymentSessionRedirect mutation, after the app has returned a response to HTTP POST request sent from Shopify to initiate the payment flow.

The paymentSessionRedirect mutation request must be received by Shopify within a given timeout, as described in the Timeout section. After the timeout, Shopify redirects the customer back to Shopify's checkout and will fail paymentSessionRedirect mutations with the BUYER_ALREADY_REDIRECTED_BY_SHOPIFY error code.

The id argument corresponds to the global identifier (gid) of the payment:

You must use the paymentSessionConfirm mutation to confirm with Shopify whether or not to proceed with the payment request, according to Shopify's business logic (e.g. oversell protection and discount code validation).

The id argument corresponds to the global identifier (gid) of the payment:

The payments app MUST redirect the customer when Shopify returns a PaymentSessionActionsRedirect.redirectUrl.

When Shopify determines that 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:

Shopify must receive an HTTP 2xx response for the payment session confirmation 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.

You can cause Shopify to send a POST request to the confirm session URL of the credit card payments app extension with confirmation_result=false by simulating that a product gets out of stock while the consumer is authenticating:

1. Navigate to [Products > Inventory](https://help.shopify.com/en/manual/products/inventory/managing-inventory-quantities/track_inventory) in the Shopify admin.
2. Make sure there is at least one unit in the inventory for a given product.
3. Proceed to the payment with this product.
4. Set the available inventory to 0 once the 3-D Secure challenge is presented.
5. Complete the challenge.
6. After your payments app calls the paymentSessionConfirm mutation, Shopify sends a POST request to the confirm session URL of the credit card payments app extension with confirmation_result=false.

You must use the paymentSessionResolve mutation after the customer has successfully gone through the payment process. The id argument corresponds to the global identifier (gid) of the payment:

The PaymentSessionThreeDSecureAuthentication argument must be provided if the paymentSessionRedirect mutation has been called for 3-D Secure.

The payments app should reject a payment if the customer can't complete a payment with the provider. The rejected payment tells Shopify that the checkout process will be halted. For example, if you don't want to process a high-risk payment, then you can reject the payment using the paymentSessionReject mutation.

Rejecting a payment is final. You can't call other actions on a payment after it has been rejected.

You can reject a payment using the paymentSessionReject mutation, as shown in the following example:

The rejection requires information on why the payment was rejected. This information is encapsulated in the PaymentSessionRejectionReasonInput.

The PaymentSessionRejectionReasonInput.code is a PaymentSessionStateRejectedReason enum of standardized error codes.

The PaymentSessionRejectionReasonInput.merchantMessage argument is a localized error message presented to the merchant explaining why the payment was rejected.

The PaymentSessionThreeDSecureAuthentication argument must be provided if the paymentSessionRedirect mutation has been called for 3-D Secure.

Credit card payment apps are expected to process payments in a few seconds. To ensure a good customer experience, the customer will be redirected to the order confirmation page when a payment times out. However the order status will be automatically set to Pending in the Shopify admin. You should still finalize the payment by calling the paymentSessionResolve or paymentSessionReject mutations.

If you don't meet the requirements, then Shopify can remove your app from the public list of payment gateways, suspend access to the payments ecosystem, terminate participation in the payments ecosystem, or take any other action deemed necessary.