FAQ

Refund Rule Criteria

A breakdown of the different rule criteria you can branch on for your automated ruleset

Steven Petteruti
Steven Petteruti
Co-founder & CTO
Published April 12, 2026
5 min read
Updated November 17, 2026

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

CriteriaDescriptionExample Use Case
card.brandThe 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.amountThe 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.countryThe country where the card was issued.Apply stricter rules for cards issued outside your primary market.
card.processorThe 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_scoreA 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_createdNumber of days between the transaction date and the alert date.Ignore alerts for very old transactions (e.g., > 120 days).
transaction.is_3dsIndicates 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.descriptorThe billing descriptor shown on the customer's bank statement.Apply rules to specific products or brands using unique descriptors.
charge.sub_account_idIdentifier 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_cardTotal number of alerts received for the same card.Flag cards with repeated alerts as high-risk or abusive.
alert.typeThe reason code type assigned by the issuing bank (DISPUTE or FRAUD).Apply different handling strategies depending on Dispute vs Fraud.
alert.skips_vfmpIndicates whether the alert bypassed Visa's fraud monitoring program.Alerts that, when resolved, will avoid TC40s.
alert.amountThe 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_3ds to 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