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.- An RTD rule is triggered during a card authorization and returns the
SUSPEND_CARDorSUSPEND_USERsupplementary action, along with a reason code of06(suspicious activity) or08(confirmed fraud). - Marqeta records the action on the transaction in the
riskcontrol_tagsobject, alongside the rule that produced it. - Marqeta evaluates the tag against the current state of the card and the user.
- Marqeta transitions the card or the user to
SUSPENDED, with achannelofFRAUDand the reason code from the rule. - If cardholder notifications are enabled for your program, Marqeta sends a one-way SMS to the cardholder’s phone number on file.
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
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.- Select the supplementary action
SUSPEND_CARDto suspend the card used in the transaction, orSUSPEND_USERto suspend the user. - In the adjacent Action data field, enter the reason code you want on the transition:
06for suspicious activity, or08for confirmed fraud.
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.
Default messages
If you do not provide a template, Marqeta sends one of the following messages, depending on which action was taken. Card suspensionCustomizing 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 replyingSTOP.
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_tagsobject of thefraud.issuer_processorblock 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
channelset toFRAUDand the reason code from your rule. The state of the card and the status of the user both readSUSPENDED. - 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.