Skip to main content
Marqeta enables card programs to act on fraud detection automatically. When one of your Real-Time Decisioning (RTD) rules identifies suspicious or confirmed fraud during a card authorization, Marqeta can suspend the affected card or user without any action from your team. Marqeta can also send the cardholder a one-way SMS notice that the action was taken. Without automated suspensions, a definitive fraud signal from RTD still requires a person to notice it and act, sometimes hours later. Automated suspensions reduce that gap to minutes and remove the manual step, which limits further fraudulent activity on a compromised card. Use the SUSPEND_CARD or SUSPEND_USER supplementary action, along with the RETURN_IN_RESPONSE supplementary action, in the RTD platform to configure your existing RTD rules to suspend a card or a user. You also specify whether the suspension reflects suspicious activity or confirmed fraud. Marqeta applies the suspension using the standard Card Transitions and User Transitions APIs, so the result appears in your webhooks and API responses like any other transition.

How it works

Card and user suspensions run on the fraud tags your RTD rules already produce. When a rule fires during a card authorization and includes a suspend supplementary action, Marqeta records the tag on the transaction and then carries out the suspension.
  1. An RTD rule is triggered during a card authorization and returns the SUSPEND_CARD or SUSPEND_USER supplementary action, along with a reason code of 06 (suspicious activity) or 08 (confirmed fraud).
  2. Marqeta records the action on the transaction in the riskcontrol_tags object, alongside the rule that produced it.
  3. Marqeta evaluates the tag against the current state of the card and the user.
  4. Marqeta transitions the card or the user to SUSPENDED, with a channel of FRAUD and the reason code from the rule.
  5. If cardholder notifications are enabled for your program, Marqeta sends a one-way SMS to the cardholder’s phone number on file.
The transition is a standard card or user transition. It is returned by the Card Transitions and User Transitions endpoints and delivered to your cardtransition and usertransition webhook subscriptions. It is also reflected in the state of the card or user, in the same way as a suspension you initiate yourself through the Core API.

Suspensions and the authorization decision

Card and user suspensions never affect the outcome of the transaction that triggered them. The approve or decline decision is determined solely by the primary action of your rule. The suspension runs after the authorization has been decided and cannot decline a transaction, delay a response to the card network, or change an RTD recommendation.
Because the suspension runs after the authorization rather than inside it, it isn’t applied at the same instant as the decision. In normal operation, the card or user is suspended within a few minutes of the triggering authorization. Design your fraud operations processes around minutes, not milliseconds. Suspensions are also fail-open at every step. If any part of the flow can’t complete, such as the suspension service being unavailable or the SMS provider rejecting a message, the transaction and the authorization flow are unaffected. The worst case is that the suspension doesn’t happen and your fraud operations team acts manually, as it does today.

Reason codes

The reason code you set on the suspend action determines the reason code on the resulting transition. Only the following codes are accepted: A suspend action that carries any other value, or no value, is ignored and no suspension occurs. For the full list of transition reason codes and channels, see Card Transitions and User Transitions.

When no action is taken

Marqeta does not suspend a card or user in the following cases. Each case is expected behavior rather than an error.
Configure each rule to return either SUSPEND_CARD or SUSPEND_USER, not both. If a single transaction carries both actions, Marqeta suspends the card and does not suspend the user. The cardholder notification, if sent, describes the card suspension.

Configuring your rules

In the Real-Time Decisioning dashboard, add a supplementary action to the rule that should trigger the suspension.
  1. Select the supplementary action SUSPEND_CARD to suspend the card used in the transaction, or SUSPEND_USER to suspend the user.
  2. In the adjacent Action data field, enter the reason code you want on the transition: 06 for suspicious activity, or 08 for confirmed fraud.
Add the RETURN_IN_RESPONSE supplementary action to any rule that returns a suspend action. This returns the triggered tag on the transaction record, so it remains visible to you for audit and reporting. Rules are not ranked or prioritized for suspensions. Every suspend action returned on a transaction is evaluated, subject to the consolidation rules described in When no action is taken. Suspend actions must come from rules that run on the real-time authorization decision path. A rule scoped only to asynchronous, post-authorization event types does not produce tags that trigger a suspension.
Editing a published rule to a draft state does not stop it from running. The last published version of a rule continues to be evaluated until you explicitly publish the change or remove the rule.

Messages your cardholders receive

When notifications are enabled, Marqeta sends a single, one-way SMS to the cardholder after a suspension takes effect. The message tells the cardholder that a hold has been placed and directs them to your customer support team.

Message format

Every message is assembled from three parts:
  • Program name: Your program’s display name, followed by a colon, which Marqeta prepends automatically.
  • Message body: Either the Marqeta default or the template you provide.
  • Opt-out line: A line that Marqeta appends automatically.
Do not include your program name or an opt-out line in a custom template. Marqeta adds both, and including them again duplicates them in the message the cardholder receives.

Default messages

If you do not provide a template, Marqeta sends one of the following messages, depending on which action was taken. Card suspension
User suspension
In both messages, Marqeta adds the program name prefix and the opt-out line. The user suspension message refers to the cardholder’s “account,” which is the cardholder-facing wording for a user suspension.

Customizing the message

You can supply your own message text to your Marqeta representative during onboarding. Marqeta recommends providing a separate message for each action, so that a card suspension and a user suspension each read correctly. A single message is used verbatim for both actions, so a user suspension notice would tell the cardholder that their card was blocked. Custom templates support one placeholder, {last_four}, which Marqeta replaces with the last four digits of the card used in the transaction. If those digits are unavailable, Marqeta substitutes ****. No other placeholders are supported.

One-way messaging and opt-out

Suspension notifications are one-way. Marqeta does not monitor or process replies to these messages, and the default message text tells the cardholder not to reply. Cardholders can opt out of future messages at any time by replying STOP. Suspension notifications are sent from a dedicated number, separate from the number used by RTD 2-Way SMS Fraud Confirmation if your program also uses that feature. The two features are independent: a program can use either, both, or neither.
Do not configure a rule to trigger both a suspend action and a 2-Way SMS confirmation on the same transaction. Neither feature waits for the other, so the cardholder receives two messages from two different numbers. The suspension is not held pending their reply, so a cardholder who replies Y to confirm that a declined transaction was genuine can’t retry it successfully, because the card is already suspended. If your process depends on the cardholder’s confirmation, use 2-Way SMS Fraud Confirmation on its own and suspend only after you have their response.

Program notification model

The transition webhook that Marqeta sends to your program for the suspension is the compliance notice of the action. The SMS to the cardholder is a courtesy notification. Use the webhook, not the SMS, as the authoritative record that a suspension was taken.

Viewing suspensions

Suspensions are visible through existing Marqeta interfaces. There is no separate reporting endpoint for the feature.
  • On the transaction: The suspend action appears in the riskcontrol_tags object of the fraud.issuer_processor block of the transaction, along with the name of the rule that produced it.
  • On the card or user: The Card Transitions and User Transitions endpoints return the suspension with channel set to FRAUD and the reason code from your rule. The state of the card and the status of the user both read SUSPENDED.
  • In your webhooks: If you subscribe to card and user transition events, the suspension is delivered on those subscriptions with the same reason code and channel.

Receiving transition events with webhooks

Webhooks are the recommended way to find out in real time that Marqeta suspended a card or user on your program. When a suspension takes effect, Marqeta sends an HTTPS notification to an endpoint that you host. You don’t need to poll the Card Transitions or User Transitions endpoints. Suspensions from Real-Time Decisioning (RTD) dashboard are standard transitions, so they are delivered through the same webhook events as any suspension you initiate yourself. You can also use a wildcard, such as cardtransition.* and usertransition.*, to receive every transition for your program. If you already subscribe to transition events, you need no changes, because automated suspensions arrive on your existing subscriptions. To separate automated suspensions from transitions your team makes, check for a channel of FRAUD and the reason code from your rule (06 or 08). Use these fields to route automated suspensions to your fraud operations workflow.
The webhook is sent after the suspension is applied, so it follows the timing described in Suspensions and the authorization decision. Don’t build processes that depend on millisecond delivery.
For setup steps, authentication options, event payloads, and retry behavior, see Webhooks and Event Types.

Reversing a suspension

All reversals of suspensions are managed outside Real-Time Decisioning.