Exception File Management

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 or by following the guidance in 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 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 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.

​

Prerequisites

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

​

Enable exception file management

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.

​

Confirm the card is terminated

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. 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. 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.

​

Choosing an action code

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. 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.

​

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.

​

Exception file management endpoints

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

​

Exception file management events

The Marqeta platform sends the following webhook events when the card network completes an action. See Exception File Management events for the full event structure.