Issuer-Based Alert Rules (Ethoca / CDRN)
This article explains the available rule criteria used for filtering and acting on issuer-based alerts, specifically from Ethoca and CDRN.
⚠️ Important: These rules are only evaluated for issuer-based alerts (Ethoca / CDRN). They do not apply to other alert types or transaction flows.
Overview
Issuer-based alerts are early warnings from card networks and issuing banks indicating that a transaction may lead to a dispute. Rules allow you to define conditions to automatically take action.
Rule Criteria Reference
| Criteria | Description | Example Use Case |
|---|---|---|
card.brand | The card network used for the transaction. Common values include Visa, Mastercard, Amex, Discover, etc. | Only act on Visa transactions if you see higher dispute rates from that network. |
transaction.amount | The total amount of the original transaction. Typically expressed in dollar terms (e.g., $50.00 = 50). | Automatically refund alerts for transactions under $50 to reduce dispute costs. All rules are automatically converted to USD, so use the amount in USD. |
card.country | The country where the card was issued. | Apply stricter rules for cards issued outside your primary market. |
card.processor | The payment processor used to process the transaction (e.g., Stripe, Shopify, NMI). | Apply different refund rules depending on which processor handled the transaction. |
transaction.risk_score | A fraud/risk score assigned to the transaction by the processor's risk system. Higher values indicate higher risk. Only available on Stripe and Shopify. | Auto-refund alerts for transactions with a risk score above a certain threshold. |
transaction.days_since_created | Number of days between the transaction date and the alert date. | Ignore alerts for very old transactions (e.g., > 120 days). |
transaction.is_3ds | Indicates whether the transaction was authenticated using 3D Secure (true/false). Only populated for PSP integrations with 3DS data (e.g. Stripe). | Skip refunds for 3DS-authenticated transactions since liability may be shifted. |
transaction.descriptor | The billing descriptor shown on the customer's bank statement. | Apply rules to specific products or brands using unique descriptors. |
charge.sub_account_id | Identifier for the sub-account (e.g., merchant account in a platform setup) associated with the charge. May be a MID identifier. | Apply different rules per merchant account in a multi-MID setup. |
alert.count_on_card | Total number of alerts received for the same card. | Flag cards with repeated alerts as high-risk or abusive. |
alert.type | The reason code type assigned by the issuing bank (DISPUTE or FRAUD). | Apply different handling strategies depending on Dispute vs Fraud. |
alert.skips_vfmp | Indicates whether the alert bypassed Visa's fraud monitoring program. | Alerts that, when resolved, will avoid TC40s. |
alert.amount | The dollar amount specified on the alert itself. | Use when you want a rule to react to the disputed amount specifically. Caution: This rule looks at the amount reflected in the alert, not the full order total. Make sure your threshold fits your typical order sizes, especially for multi-item or upsell orders |
Notes & Best Practices
- Refund rules only apply to alerts that can be matched with high confidence to a single transaction; low-confidence or undecipherable matches require manual handling.
- Combine multiple criteria to create precise rules (e.g., high amount + high risk score).
- Use
transaction.is_3dsto avoid unnecessary refunds where liability protection exists. - Monitor performance of rules regularly to optimize for dispute reduction vs. revenue loss.
- Be cautious when using
alert.count_on_card— high counts may indicate fraud rings or repeat customers.
Was this article helpful?
Help us improve our documentation
