---
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/posts/new-rejection-reason-codes-in-payments-apps-graphql-api
  md: >-
    https://shopify.dev/changelog/posts/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

# New rejection reason codes in Payments Apps API

DateMarch 16, 2026

Version[2026-04](https://shopify.dev/changelog?api_version=2026-04)

FlagsNew

SurfacesAPI

Affected APIs[Payments Apps API](https://shopify.dev/changelog?api_type=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"
  }
}
```