> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Exception File Management

> Use the Exception File Management API to add, update, retrieve, and remove cards on a card network's exception file.

Card networks use an exception file to block authorizations, and in some cases clearings, for a listed card independent of whether the Marqeta platform is available to make a real-time authorization decision.
Adding a terminated card to the exception file prevents stand-in processing (STIP) from approving transactions on that card while the Marqeta platform is unavailable.
Depending on the action code you use, adding a card to the exception file can also prevent force-posted clearing transactions on that card, giving your program an additional way to reduce fraud from merchants that submit a clearing without a valid authorization.

Adding a primary account number (PAN) to the exception file blocks new digital wallet token provisioning for that PAN, but doesn't change the state of digital wallet tokens that already exist for it.
Manage the state of existing digital wallet tokens separately, such as by setting `sync_state_with_dwts` on [card transitions](/docs/core-api/card-transitions/) or by following the guidance in [Managing the Digital Wallet Token Lifecycle](/docs/developer-guides/managing-the-digital-wallet-token-lifecycle/).

Each entry on the exception file includes an action code that identifies the reason the card is listed and determines whether the card network also protects clearing transactions for the card, in addition to authorizations.
See [Choosing an action code](#_choosing_an_action_code) for guidance on which code to use for a given scenario.
Each entry also includes a purge date that determines how long the card stays on the exception file before the card network removes it.

The Marqeta platform processes add, update, and remove requests asynchronously.
A successful response confirms that the Marqeta platform accepted the request for processing, not that the card network has completed the action.
Subscribe to the `pan.exception_file.added`, `pan.exception_file.updated`, and `pan.exception_file.deleted` webhook events to confirm when the card network completes each action.
See [Exception File Management events](/docs/core-api/event-types/#_exception_file_management_events) for details.

Exception File Management currently supports Visa's Account Screen Authorization File (ASAF) only.
Support for other card networks, such as Mastercard, isn't currently available.
For more information on Visa's exception file rules, see [Card Network Certifications](/docs/developer-guides/card-network-certifications/#_article_2_17_visa_account_screen_clearing_file_ascf_auto_enablement).

<h2 id="_prerequisites">
  Prerequisites
</h2>

Before you add a card to the exception file, complete the following prerequisites.

<h3 id="_enable_exception_file_management">
  Enable exception file management
</h3>

Exception File Management requires additional activation steps.
Contact your Marqeta representative to enable it for your program.
Card network and Marqeta platform fees apply; your Marqeta representative can provide pricing details for your program.

<h3 id="_terminate_the_card">
  Confirm the card is terminated
</h3>

Before you add a card to the exception file, confirm that the card is in a `TERMINATED` state.
To check the state of the card, send a `GET` request to `/cards/{token}` and review the `state` field in the response.
See [Retrieve card](/docs/core-api/cards/#get_cards_token).

If the card isn't in a `TERMINATED` state, send a `POST` request to `/cardtransitions` with `state` set to `TERMINATED` to terminate it.
See [Create card transition](/docs/core-api/card-transitions/#post_cardtransitions).
Terminating a card is permanent, so confirm that you want to terminate the card before you send the request.

The Marqeta platform rejects requests to add a card that isn't terminated, because doing so would create a conflict between the Marqeta platform's authorization decision and the card network's exception file decision.
If more than one card token shares the same PAN, such as after a card reissue, all card tokens for that PAN must be in a `TERMINATED` state before you can add the PAN to the exception file.

<Note>
  Cards in a `SUSPENDED` state can't be added to the exception file.
  Suspended is a temporary state, and the cardholder is expected to resume transacting.
</Note>

<h2 id="_choosing_an_action_code">
  Choosing an action code
</h2>

Every entry on the exception file requires an action code that identifies why the card is listed.
The action code you choose determines whether the card network also blocks clearing transactions for the card, in addition to blocking authorizations.
Blocking clearing transactions for a card prevents force-posted clearings on it, which helps reduce fraud from merchants that submit a clearing without a valid authorization.

| Scenario | Action code | Protection |
| - | - | - |
| Card terminated or closed account | `CLOS` | Authorization and clearing |
| Lost card | `LCPU` | Authorization and clearing |
| Stolen card | `SCPU` | Authorization and clearing |
| Invalid or not-found account | `INVA` | Authorization and clearing |
| Fraud pickup (non-specific) | `PUWF` | Authorization and clearing |
| Pickup (no fraud) | `PUNF` | Authorization and clearing |
| Expired card | `EXPC` | Authorization only |
| General block (do not honor) | `DNTH` | Authorization only |

Use an action code that provides authorization and clearing protection if you want the card network to block both types of transactions for the card.
`EXPC` and `DNTH` both provide authorization-only protection and don't affect clearing transactions for the card.
The difference is the response code that the merchant receives when the authorization is declined: `EXPC` returns response code 54 (expired card), and `DNTH` returns response code 05 (do not honor).
Use `EXPC` for expired cards and `DNTH` for a general block.

<Warning>
  Visa might downgrade a PAN's action code to `DNTH` or `EXPC` if the Marqeta platform approves a transaction on that PAN after it's added to the exception file.
  When this happens, the PAN loses clearing protection.
  To avoid this downgrade, make sure that any card you add to the exception file is also being declined at authorization by the Marqeta platform.
  For more information, see [Card Network Certifications](/docs/developer-guides/card-network-certifications/#_article_2_17_visa_account_screen_clearing_file_ascf_auto_enablement).
</Warning>

## Setting the purge date

The `action_date` field sets the purge date, which is the date the card network removes the card from the exception file.
Specify the date in `YYYY-MM-DD` format.
The date doesn't include a time because the card network's exception file field is date-only.
The Marqeta platform calculates and validates the purge date in UTC.

The purge date must be between 30 days and 24 months from the current date.
If you don't specify a purge date, it defaults to 90 days from the current date.
The `created_at` and `last_modified_at` fields on a retrieved record are Marqeta platform timestamps in UTC, in `yyyy-MM-ddThh:mm:ssZ` format.

## Handling duplicate requests

If you send a `POST` request for a card whose identical record is already on the exception file, the Marqeta platform returns a `409` response with the message 'This update has already been received.'
The request is idempotent, so you can treat this response as a success.

<h2 id="_exception_file_management_endpoints">
  Exception file management endpoints
</h2>

The Exception File Management API lets you add, update, retrieve, and remove cards on the exception file.
Use the following operations to manage cards on the exception file.

### Available operations

| Operation | Method | Endpoint |
| - | - | - |
| [Add card to exception file](/docs/core-api/exception-file-add) | `POST` | `/exception-file/{cardToken}` |
| [Update card on exception file](/docs/core-api/exception-file-update) | `PUT` | `/exception-file/{cardToken}` |
| [Retrieve card from exception file](/docs/core-api/exception-file-retrieve) | `GET` | `/exception-file/{cardToken}` |
| [Remove card from exception file](/docs/core-api/exception-file-remove) | `DELETE` | `/exception-file/{cardToken}` |

## Exception file management events

The Marqeta platform sends the following webhook events when the card network completes an action.
See [Exception File Management events](/docs/core-api/event-types/#_exception_file_management_events) for the full event structure.

| Event | Description |
| - | - |
| `pan.exception_file.added` | The card was successfully added to the exception file. |
| `pan.exception_file.updated` | An existing exception file record was successfully updated. |
| `pan.exception_file.deleted` | The card was removed from the exception file. |


## Related topics

- [Add Card to Exception File](/docs/core-api/exception-file-add.md)
- [Exception File Record Object](/docs/core-api/exception-file-object.md)
- [Retrieve Card from Exception File](/docs/core-api/exception-file-retrieve.md)
- [Remove Card from Exception File](/docs/core-api/exception-file-remove.md)
- [Update Card on Exception File](/docs/core-api/exception-file-update.md)