New Rejection Reason Codes in Payments Apps API

Shopify has expanded the PaymentSessionStateRejectedReason enum in the Payments Apps API with additional decline reason codes. The update adds more granular error codes alongside a new source field, providing payments apps with standardized ways to communicate payment decline reasons to merchants.

What Changed

The Payments Apps API now includes multiple new rejection codes that offer more specific information about why payment sessions fail. These codes supplement the existing rejection reasons in the PaymentSessionStateRejectedReason enum. The addition of a source field allows payments apps to identify where in the payment flow the rejection originated.

Impact for Developers

Developers building payment apps on Shopify can now implement more precise error handling and merchant communication. The expanded rejection codes enable apps to provide merchants with specific reasons for declined transactions rather than generic failure messages. This standardization creates consistency across different payment apps in how they report transaction failures.

Implementation Considerations

Payment app developers should review their current error handling logic to incorporate the new rejection codes. Apps that display decline reasons to merchants will need to map these new codes to user-friendly messages. The source field provides additional context that can help developers troubleshoot payment flow issues and improve their apps’ reliability.

Developers can reference the full list of new error codes in the Shopify Dev Changelog. The update applies to all apps using the Payments Apps GraphQL API for processing transactions.

Read the full announcement →