---
title: New rejection reason codes in Payments Apps API - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/new-rejection-reason-codes-in-payments-apps-graphql-api
  md: >-
    https://shopify.dev/changelog/new-rejection-reason-codes-in-payments-apps-graphql-api.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Payments Apps API
      handle: payments-apps-api
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-03-04T17:25:17-05:00'
  postedAt: '2026-03-16T12:00:00-04:00'
  updatedAt: '2026-03-10T11:28:18-04:00'
  effectiveAt: '2026-03-31T12:00:00-04:00'
---

March 16, 2026

Tags:

* Payments Apps API
* 2026-04

# 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`](https://shopify.dev/docs/api/payments-apps/2026-04/enums/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`](https://shopify.dev/docs/api/payments-apps/2026-04/input-objects/PaymentSessionRejectionReasonInput) input and the [`PaymentSessionStateRejected`](https://shopify.dev/docs/api/payments-apps/2026-04/objects/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:

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

With variables:

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