---
title: >-
  New payment decline codes added to OrderTransactionErrorCode enum - 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-payment-decline-codes-added-to-ordertransactionerrorcode-enum
  md: >-
    https://shopify.dev/changelog/new-payment-decline-codes-added-to-ordertransactionerrorcode-enum.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: true
  createdAt: '2026-01-08T13:01:45-05:00'
  postedAt: '2026-03-16T12:00:00-04:00'
  updatedAt: '2026-03-10T11:32:10-04:00'
  effectiveAt: '2026-01-09T12:00:00-05:00'
---

March 16, 2026

Tags:

* Action Required
* Admin GraphQL API
* 2026-04

# New payment decline codes added to `OrderTransactionErrorCode` enum

We're adding new error codes to the [OrderTransactionErrorCode](https://shopify.dev/docs/api/admin-graphql/latest/enums/OrderTransactionErrorCode) enum to provide more granular detail about the transaction failure. You can use this more detailed response to improve customer interactions.

### What's new

These error codes enable precise identification of transaction issues:

| Error Code | Description |
| - | - |
| `AMOUNT_TOO_LARGE` | The transaction amount exceeds the maximum amount allowed. |
| `AMOUNT_TOO_SMALL` | The transaction amount is below the minimum amount allowed. |
| `AUTHENTICATION_FAILED` | The 3D Secure authentication failed. |
| `AUTHENTICATION_REQUIRED` | The transaction requires 3D Secure authentication but was attempted without authentication. |
| `AUTHORIZATION_EXPIRED` | The authorization has expired. |
| `CANCELLED_PAYMENT` | The transaction was cancelled. |
| `CARD_TESTING` | The transaction was declined due to suspected card testing activity. |
| `DO_NOT_HONOR` | The issuer declined the transaction without providing a specific reason. |
| `FRAUD_SUSPECTED` | The transaction was declined due to suspected fraudulent activity. |
| `INSUFFICIENT_FUNDS` | There are insufficient funds available to complete the transaction. |
| `INSTRUMENT_DECLINED` | The payment instrument was declined by the payment processor. |
| `INVALID_CURRENCY` | The currency isn't supported. |
| `INVALID_PAYMENT_METHOD` | The payment method is invalid or not found. |
| `INVALID_PURCHASE_TYPE` | This payment method doesn't support the requested transaction type. |
| `MERCHANT_ACCOUNT_ERROR` | The transaction couldn't be processed due to an issue with the merchant account. |
| `MERCHANT_RULE` | The transaction was blocked due to the merchant's custom payment risk rule. |
| `PAYMENT_METHOD_UNSUPPORTED` | The payment method isn't supported. |
| `PAYMENT_PROVIDER_ERROR` | The transaction couldn't be processed due to an unexpected error with the payment provider. |
| `RETRY_DECLINED` | The transaction retry attempt was declined. |
| `TRANSACTION_LIMIT_EXCEEDED` | The payment instrument has exceeded the processing frequency limit. |



### What's changed

The `RISKY` error code is deprecated. When a transaction is declined due to suspected fraud, you'll now receive `FRAUD_SUSPECTED`. The `RISKY` value remains in the enum for backward compatibility but won't be returned anymore.

We've also updated descriptions for some existing error codes to improve clarity.

### What you need to do

Update your error handling logic to leverage these specific error codes for more precise customer messaging. You can now provide targeted responses based on the specific decline reason.

For more information, refer to the [OrderTransactionErrorCode enum reference](https://shopify.dev/docs/api/admin-graphql/latest/enums/OrderTransactionErrorCode).