New rejection reason codes in Payments Apps API

The Payments Apps API now provides more granular decline reason codes for rejected payment sessions. Multiple new rejection codes have been added to the PaymentSessionStateRejectedReason enum alongside a new source field, giving payments apps more standardized, actionable ways to communicate to merchants why a payment was declined.

New rejection reason codes

The following error codes expand the existing set of rejection reasons with more specific rejection information:

Error Code	Description
`AMOUNT_TOO_LARGE`	The amount exceeds the maximum amount allowed.
`AMOUNT_TOO_SMALL`	The amount is below the minimum amount allowed.
`AUTHENTICATION_REQUIRED`	The payment required 3D Secure authentication but was attempted without authentication.
`CALL_ISSUER`	The issuer declined the payment. The buyer should contact their issuer for more details.
`CANCELLED_PAYMENT`	The payment was cancelled.
`CARD_TESTING`	The payment was blocked due to suspected card testing behaviour.
`DO_NOT_HONOR`	The issuer declined the payment without providing a specific reason.
`FRAUD_SUSPECTED`	The payment was declined due to suspected fraudulent activity.
`HIGH_RISK_FRAUD_SUSPECTED`	The payment was declined due to high fraud risk indicators. The payment instrument may have been reported as lost or stolen.
`INSTRUMENT_DECLINED`	The payment instrument was declined.
`INSUFFICIENT_FUNDS`	The payment method has insufficient funds to complete the payment.
`INVALID_AMOUNT`	The payment amount is invalid or incorrectly calculated.
`INVALID_CURRENCY`	The currency isn't supported.
`INVALID_PAYMENT_METHOD`	The payment method or its associated account is invalid or not found.
`INVALID_PURCHASE_TYPE`	This payment method doesn't support the requested payment type.
`INVALID_REQUEST`	The payment request is missing required parameters or contains invalid values.
`MERCHANT_ACCOUNT_ERROR`	The payment couldn't be processed due to an issue with the merchant account.
`MERCHANT_RULE`	The payment was blocked due to merchant's custom payment risk rule.
`PAYMENT_METHOD_UNSUPPORTED`	The payment method isn't supported.
`PICK_UP_CARD`	The card can't be used for this payment. The cardholder may have reported it as lost or stolen.
`RETRY_DECLINED`	The payment retry attempt was declined.
`TRANSACTION_LIMIT_EXCEEDED`	The payment instrument has exceeded the processing frequency limit.

New rejection source

A new source field has been added to both the PaymentSessionRejectionReasonInput input and the PaymentSessionStateRejected type. This field accepts a PaymentSessionStateRejectedSource enum value to indicate which entity declined the transaction:

NETWORK: The payment network or the issuer rejected the payment.
PROVIDER: The provider rejected the payment.

Deprecation

The RISKY rejection reason is now deprecated. If your app currently passes RISKY when calling paymentSessionReject, update your code to use FRAUD_SUSPECTED instead.

Example

Pass the new rejection reason and source in your paymentSessionReject mutation:

mutation PaymentSessionReject($id: ID!, $reason: PaymentSessionRejectionReasonInput!) {
  paymentSessionReject(id: $id, reason: $reason) {
    paymentSession {
      id
      state {
        ... on PaymentSessionStateRejected {
          reason
          source
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

With variables:

{
  "id": "gid://shopify/PaymentSession/1",
  "reason": {
    "code": "INSUFFICIENT_FUNDS",
    "source": "NETWORK"
  }
}

Was this section helpful?