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

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

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.

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.