Transaction Decline Codes

Each transaction that goes through the Marqeta platform is assigned a response code that represents the transaction’s final outcome. The majority of these codes describe the reason for a decline. The memos that accompany these codes provide insight as to why the transaction was declined and can be used to inform cardholder notifications. This page outlines some common transaction response codes and gives a detailed reasoning for each, as well as recommendations for reducing declines.

Compliance

This decline code appears when a cardholder attempts a transaction in a country where transactions are prohibited.

Code	Description	Details
`1864`	Transactions not allowed from this country	Marqeta’s Risk and Compliance team maintains a list of countries with which Marqeta will not transact, as Marqeta is a U.S.-based company and must obey OFAC rules, including additional internal governance. For details, see the list of accepted countries. Contact your Marqeta representative to add further countries to be blocked.

Just-in-Time (JIT) Funding response

This section outlines responses from JIT Funding gateways. These response codes all correspond to a specific action that is completed via the JIT gateway. These transactions are declined by your gateway, and followed with a specific decline_reason code that determines the response code. You should review the JIT gateway codes to determine the reason for the decline. Common response codes include the following (see the full list in Transaction response codes):

1883 — JIT response invalid amount
1884 — JIT response not sufficient funds
1885 — JIT response transaction not permitted
1886 — JIT response suspected fraud
1887 — JIT response amount limit reached
1888 — JIT response usage limit reached
1889 — JIT response duplicate entry
1016 — Not sufficient funds

To successfully trigger a decline response, the HTTP code must read 402 and a decline_reason must be included in the response payload. Marqeta recommends using the memo and tags fields in your response so that you can store internal response messages, which will later be sent to your webhook endpoint. During triage, you should check the webhook to determine what response was returned from the JIT gateway. An example of a typical response, with the webhook shortened for illustration purposes, is included here for gpa_order.funding.gateway_log.response.data. You can find further information about the decline_reason field on the Gateway JIT Funding Messages page.

JSON

{
  "transactions": [
    {
      "gpa_order": {
        "funding": {
          "gateway_log": {
            "response": {
              "code": "402",
              "data": {
                "jit_funding": {
                  "memo": "Insufficient funds",
                  "tags": "insufficient_funds",
                  "decline_reason": "INSUFFICIENT_FUNDS"
                }
              }
            }
          }
        }
      },
      "response": {
        "code": "1884",
        "memo": "JIT Response Not Sufficient Funds"
      }
    }
  ]
}

Cardholder and card state

This section outlines the responses that can be returned based on the cardholder or the card’s current state. Using the API, customers can update the state of a cardholder or card, and Marqeta will maintain checks during transactions to ensure that the cardholder or card is in the correct state before proceeding with the transaction.

Code	Description	Details
`1813`	Cardholder not active	Either the cardholder’s state is not currently in an `ACTIVE` state, or the cardholder is in a `SUSPENDED` state.
`1920`	Cardholder terminated	The cardholder has transitioned to a `TERMINATED` state. Card transactions will be declined, and new token provisioning will also be declined. Any existing digital wallet tokens will continue to allow transactions. The card’s lifecycle is maintained separately.
`1001`	Card expired	The card’s `expiration_time` has been exceeded and can no longer be used. Marqeta terminates expired cards once daily.
`1003`	Card suspended	The card has transitioned to a `SUSPENDED` state. Card transactions will be declined, and new token provisioning will also be declined. Any existing digital wallet tokens will continue to allow transactions. The card’s lifecycle is maintained separately. This is a temporary state change, and cards can be transitioned back to `ACTIVE`.
`1004`	Card stolen - pickup	Card was transitioned using reason_code``23: Card was reported stolen. When this response code is used, any attempt to use the physical card will try to pick up the card from the cardholder.
`1005`	Card lost	The card was transitioned using reason_code``10: Card was reported lost.
`1901`	Card not activated	The card is currently in an `UNACTIVATED` state. This is the default state for a card when it is issued. Physical cards typically stay in this state until they are shipped to the cardholder. Cardholders must go through an activation process that changes the state of the card to `ACTIVE`.
`1919`	Card terminated	The card has transitioned to a `TERMINATED` state. Card transactions will be declined, and new token provisioning will also be declined. Any existing digital wallet tokens will continue to allow transactions and the lifecycle is maintained separately. This is a final state change. Cards cannot be transitioned again after they have been `TERMINATED`.
`1011`	Card not found	The provided PAN does not exist on the Marqeta platform. Typically, this is a keying error and the PAN was incorrectly entered. Cardholders should confirm that the PAN entered is correct.

Strong customer authentication

The following transaction codes represent soft decline codes that are triggered based on the strong customer authentication (SCA) controls determined by your card product’s limits. A soft decline is not an outright rejection of an authorization request. It advises the merchant that the card issuer requires the cardholder to perform 3D-Secure (3DS) authentication (for e-commerce transactions) or PIN (chip) authentication, prior to approving the transaction. To perform identity verification, the cardholder must pass SCA controls, as described in the Managing SCA in Europe guide. Common SCA transaction codes include:

1891 — SCA contactless cumulative amount exceeded
1892 — SCA contactless transaction count limit exceeded
1893 — SCA contactless transaction limit exceeded
1897 — SCA LVP cumulative amount exceeded
1898 — SCA LVP transaction count limit exceeded
1899 — SCA LVP transaction limit exceeded

When Marqeta returns these response codes, the merchant should request SCA using either a PIN or 3DS. SCA should be completed by the merchant, and then a new authorization posted with the correct SCA credentials. Once an SCA transaction is seen at Marqeta, the cardholder limits are reset. SCA will not be required again until these limits are met.

Transaction security checks

This section defines common transaction security checks that Marqeta uses when declining a transaction on your behalf. As a part of Marqeta’s standard controls, Marqeta ensures the correctness and validity of transactions prior to moving them to the funding phase. If a transaction is declined, you may receive one of the following decline codes:

Code	Description	Details
`1825`	Invalid card security code	Card security code CVV1 is incorrect. This value is coded inside the card’s magstripe. This response suggests that there has been a card production error. The use of CVV1 is limited in Europe at this time.
`1915`	Invalid card security code (CVV2)	The card security code CVV2 entered by the cardholder does not match what is stored on the Marqeta platform for this card.
`1874`	Card suspicious — Expiration mismatch	The expiration date entered by the cardholder does not match what is stored on the Marqeta platform for this card.
`1809`	Invalid PIN	An incorrect PIN was entered for an online PIN transaction.
`1872`	PIN try limit exceeded	The limit on PIN attempts has been reached. You should check the `additional_information` field to determine if the cardholder used an online or offline PIN, so that you can inform the cardholder of the PIN reset flow.
`1880`	Network CAVV decline	Card network CAVV validation has failed and Marqeta has declined the transaction.

Spend controls

Spend controls can be implemented at a program, card product, or cardholder level. Marqeta adopts the lowest-first approach to spend controls. The following response codes depend on the spend controls that you have established. For each spend control decline reason, Marqeta provides a field for additional_information. This field provides the name of the spend control that has been triggered, and the conditions for the response received (for example, additional_information : LIFETIME, Cumulative transaction amount is 10.00). You should name your spend controls using concise, meaningful phrases, as the spend control name will appear in this field.

Code	Description	Details
`1817`	Exceeds withdrawal count limit	The `usage_limit` of the velocity control has been reached.
`1834`	Exceeds withdrawal amount limit	The `amount_limit` of the velocity control has been reached.
`1841`	Exceeds max auth amount limit	The `amount_limit` of the velocity control has been reached. The velocity control shows `velocity_window` = `TRANSACTION`.

Permitted transactions

This section describes responses that are based on your card product’s configuration within your program. As a part of your program setup, you can determine which transactions are allowed to be funded and which will be blocked. These rules should align with your internal risk parameters. The following responses are the most common:

Code	Description	Details
`1832`	Auth restriction found for given MID or MCC	The card program has an authorization control set up that restricts spending at this merchant ID (MID) or merchant category code (MCC). You should check `/authcontrols` for the relevant authorization control for that user, card product, or program.
`1835`	Card product controls prevent transaction	Review `config.poi` to determine what controls are in place. For example, `config.poi.atm` = `false` would decline an ATM transaction.
`1843`	Network load not allowed	The card product setting does not allow original credit transactions (OCT). If you want to allow OCT, set `config.transaction_controls.allow_network_load` to `true` then confirm with your Marqeta representative that your program now allows OCT.
`1846`	ATM transaction not allowed	The card product setting does not allow ATM transactions. If you want to allow ATM transactions, set `config.poi.atm` to `true`.
`1868`	Quasi-cash transaction not allowed	This response implies that a card product control has restricted this transaction type. If you want to allow quasi-cash transactions, set `config.transaction_controls.allow_quasi_cash` to `true`.
`1873`	Chip fallback to magstripe is not allowed	This response indicates that the cardholder has attempted a transaction using the card’s chip, but the terminal failed to read the chip and has instead attempted to validate the transaction using magstripe. NOTE: As magstripe is not a strong authentication method, you can choose to deny this behavior by setting the card product attribute `config.transaction_controls.allow_chip_fallback` to `false`.
`1876`	Account Funding Transactions are unsupported	The card program does not allow Account Funding Transactions (AFT). If you want to allow AFT, contact your Marqeta representative. These transaction types are represented as `account.funding.authorization` event types.
`1877`	Control Plane/FraudStream decline	Real-Time Decisioning (RTD) is enabled, and a rule was triggered to determine whether a threshold that was reached is considered to be high risk by the program. Meeting a high-risk threshold prevents authorization from occurring. You can configure these rules during your discussion with Marqeta about enabling program-specific rules.

Digital wallet token service

Marqeta’s digital wallet token service (DWTS) allows for token creation using the Marqeta platform. DWTS also allows for communication with the card network or token service provider and facilitates tokenized transactions. In the provisioning flow, Marqeta receives a token.activation.request to determine whether creating tokens is allowed. If there is a failure, Marqeta has specific response codes that describe the reason for token rejection according to card network and token service provider mandates.

Code	Description	Details
`1855`	Digital wallet token not found	The token PAN presented to Marqeta does not exist in the Marqeta platform. This can occur when an incorrect configuration caused the card network to provision a token outside of Marqeta.
`1856`	Digital wallet token not active	The digital wallet token used for the transaction is not in an `ACTIVE` state.
`1858`	Digital wallet token suspended	A transaction has been attempted on a token that is in a `SUSPENDED` state. The token can later be returned to an `ACTIVE` state without reissuing the token.
`1862` or `1896`	Token activation request card product config decline	Token type under `digital_wallet_tokenization.provisioning_controls` is marked as `false`. Tokenization is not enabled for this card product.
`1895`	Token Activation Request - STIP decline	Stand-In Processing (STIP) notification for tokenization failures, which can be caused by issues with the merchant, the acquirer, the card network, or Marqeta.
`1921`	Digital wallet token terminated	A transaction has been attempted on a token that is in a `TERMINATED` state. This token cannot be reactivated and must be reissued.

Technical errors

Technical errors imply that a failure has occurred at some point in the transaction leg. This error could lie with the merchant, the acquirer, the card network, or Marqeta.

Code	Description	Details
`1844`	Network decline advice	Marqeta provides the `standin_reason` to determine what triggered the STIP. STIPs for which Marqeta is responsible are prefixed with `issuer` (for example, `issuer_timeout`).
`1812`	Internal error (TXN)	Contact Marqeta for support when an unexpected error of this type occurs.
`1922`	The transaction cannot be completed	Contact Marqeta for support when an unexpected error of this type occurs.

Guides

​Compliance

​Just-in-Time (JIT) Funding response

​Cardholder and card state

​Strong customer authentication

​Transaction security checks

​Spend controls

​Permitted transactions

​Digital wallet token service

​Technical errors