Process a credit card payment

In this guide, you'll learn how to do the following tasks:

• Understand how the payment flow is initiated
• Redirect the customer for 3-D Secure authentication, if applicable
• Confirm whether to proceed with a payment request, if applicable
• Resolve a payment
• Reject a payment
• Set a payment as pending

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

Returned hash in API version 2023-04:

Returned hash in API version 2023-07 or later:

After the payments app has determined it needs to orchestrate a 3-D Secure authentication, and after the app has returned a response to HTTP POST request sent from Shopify to initiate the payment flow, the app uses the paymentSessionRedirect mutation. Shopify renders the URL provided by the app in an iFrame in the customer's browser.

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 to proceed with the payment request, according to Shopify's business logic (for example, 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 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:

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.

When Shopify indicates that the payment request cannot proceed, the payments app must invoke the paymentSessionReject mutation using the CONFIRMATION_REJECTED reason code.

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 authorizationExpiresAt argument must be provided if the payment session request kind is authorization. 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.

To reject a credit card payment, you can use any of the following reason codes:

• INCORRECT_NUMBER
• INCORRECT_CVC
• INCORRECT_ZIP
• INCORRECT_ADDRESS
• INCORRECT_PIN
• INVALID_NUMBER
• INVALID_CVC
• INVALID_EXPIRY_DATE
• EXPIRED_CARD
• CARD_DECLINED
• CONFIRMATION_REJECTED
• PROCESSING_ERROR

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.

You can set a payment as pending if it's awaiting asynchronous action by the customer, the merchant, the payment Partner, or a payment network.

Not all payments can be processed and finalized quickly. Some payments can take several days to complete. Setting a payment as pending indicates to the customer and the merchant that you have started processing the payment, but require more time to complete the payment. Both sale and authorization payments can be marked as pending.

The process to set a payment as pending follows similar steps to a regular credit card payment, except instead of resolving or rejecting a payment, you first call the paymentSessionPending mutation to set the payment as pending, before calling paymentSessionResolve or paymentSessionReject after the payment has been completed.

The following diagram illustrates how a payment flow works between Shopify and a payments app with a credit card payments app extension when setting a payment as pending:

1. The customer completes checkout, triggering a request for payment.
2. Shopify initiates the flow by sending a 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 calls the paymentSessionPending mutation to set the payment as pending.
6. Shopify responds with an HTTP code 200 (OK) to confirm the payment state is updated.
7. The customer continues to checkout.
8. Upon completion, pending payments must be finalized into either a successful or failed state using the paymentSessionResolve or paymentSessionReject mutations.

To set a payment as pending, use the paymentSessionPending mutation:

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.