Rules Reference

Learn more about how the order in which rules are processed, and how they are structured. If you need help after reading this, get in touch or chat live with other developers in #stripe on freenode.

Before creating a rule, it’s important to know the order in which rules are processed, and what payment attributes are available for use when specifying criteria to evaluate. Stripe’s machine-learning fraud systems are able to block many fraudulent payments for you, but if you need to create rules using information that’s unique to your business, there are many supported payment attributes you can make use of.

Rule processing and ordering

When creating a rule, the action it’s going to take determines the order in which it is processed. Each payment is evaluated against the rules you have created and performed in a specific order:

  1. Allow: Rules that allow a payment to be processed. If a payment is allowed, it is not evaluated against any block or review rules.
  2. Block: Rules that block a payment and reject it. If a payment is rejected, it’s not evaluated against any review rules.
  3. Review: Rules that allow a payment to be processed but are then placed in review

If a payment should match a rule’s criteria, the respective action is performed and no further rules are evaluated against the payment. If a payment matches an allow rule, it’s processed normally–no block or review rules are subsequently evaluated, even if the payment would also meet their criteria. For instance, an example set of rules might be as follows:

  • Allow payments less than $10
  • Allow payments made within the US and with a risk level of normal
  • Block payments where the risk level is high
  • Block payments greater than $1,000
  • Review payments made with a card issued outside the U.S.

Using the rules above, all payment less than $10 would be processed, regardless of their risk level or where the card used was issued. This is because the first rule allows the payment, so no further rules are evaluated. Similarly, a $1,500 payment made within the U.S. with a normal risk level would also be allowed, despite the rule to block payments over $1,000. This is because of the second rule in the list, allowing payments made within the US and a normal risk level. Once a particular rule is triggered, no further rules are evaluated.

Rule structure

Rules are constructed using two components: the action it should take and the condition to evaluate:

{action} if {condition}

In practice, a rule to block all payments over $1,000 would appear as:

Block if :amount_in_usd: > 1000.00

  • The action is Block
  • The condition is :amount_in_usd: > 1000.00

Actions

A rule can perform one of three actions with a payment that meets its criteria, which are processed in this specific order.

Allow

This rule action determines when a payment of a certain criteria should always be allowed, regardless of Stripe’s evaluation and any other rules the payment might match. When a payment matches the criteria in an allow rule, it is processed normally by Stripe and has no further rules evaluated against it. Even when Stripe proceeds with a payment it may nonetheless be declined by the issuing bank.

Block

This specifies when a payment should always be blocked by Stripe. If a payment matches the criteria in a block rule, the payment is rejected and no further rules are evaluated.

Review

There might be certain types of payments you want to allow, but still take a closer look at. With review rules, you can place payments in review. This is especially useful to manage payments that aren’t particularly common, such as those with a larger than usual amount or from a country that you don’t often ship to. These payments are still processed, and the customer charged, but you have an additional opportunity to review the order to make sure there are no signs of fraud.

Conditions

If a payment matches a rule’s condition, the corresponding action is taken. A basic condition is, itself, made up of three parts:

[attribute] [operator] [value]

  • Attribute: The attribute of a payment (e.g., the amount or type of card)
  • Operator: The arithmetic that compares the attribute to the value (e.g., greater than or not equal to)
  • Value: The criteria you wish to use (e.g., 100.00 or debit)

Combining both the action and condition together, the structure of a rule is:

{action} if {[attribute] [operator] [value]}

There are four types of conditions that exist, depending on the attribute type:

  • [string_attribute] [operator] [string_value]
  • [country_attribute] [operator] [country_value]
  • [numeric_attribute] [operator] [numeric_value]
  • [boolean_attribute]

Certain attributes can also be used as a corresponding value within a condition. For instance, you can create a rule to block payments where the country the card was issued does not match against the country the payment was made, using the following attribute and value:

Block if :card_country: != :ip_country:

String attributes

These contain any combination of characters. String attributes and values most commonly represent a piece of text, such as a card’s brand (e.g., visa, amex) or risk level (e.g., elevated). These can be used in rules to allow payments only from a particular country, or block payments made with prepaid cards.

Country attributes

These makes use of two-letter country codes to represent a country, such as US for United States or CA for Canada. Country attributes operate the same as string attributes, the only difference being that the value must be a country code.

Numeric attributes

As these only contain numbers, they support more operators than string attributes and values. A payment’s amount is one example of a numeric attribute, and a rule can be created to perform an action should the amount be higher, lower, equal, or not equal to the amount you specify.

Boolean attributes

A boolean attribute simply represents whether a particular attribute is true. Unlike string and numeric attributes, there are no operators or values to use. You can use a boolean attribute to block payments that have been made with a disposable email address, or place payments in review that were made with an anonymous IP address.

Supported attributes

The following payment attributes are supported for use in rule definitions:

Attribute Type Description
card_brand String The brand of the card being used to make the payment. The supported values are: amex (American Express), visa (Visa), mc (Mastercard), dscvr (Discover), and diners (Diners Club).
card_funding String The type of card with respect to the underlying financial mechanics. The supported values are: credit, debit, prepaid, unknown.
email_domain String The domain of the email address supplied with the payment (e.g., example.com).
ip_address String The IP address from which the payment originates.
risk_level String The risk level of a given payment, as determined by Stripe. The supported values are: normal, elevated, highest, not_assessed, unknown.
card_country Country The two-letter code corresponding to the country where the card was issued (e.g., US).
ip_country Country The two-letter code corresponding to the country-level geolocation of the IP address from which the payment originates (e.g., GB).
amount_in_xyz Numeric The amount of the payment, converted to the currency specified by xyz (e.g., amount_in_usd). You can specify one of 14 supported currencies and Stripe automatically provides a converted amount to use. For example, if you create a rule to block all payments greater than $1,000, Stripe would block a £900.00 payment as it’s equivalent converted USD value would be $1,200.00. Note that for decimal currencies (such as USD and GBP), rules use the base currency unit rather than sub units (e.g., Dollars, not cents)
auths_per_card_number_daily Numeric The number of times a card number was successfully authorized on your account in the past 24 hours.
auths_per_card_number_hourly Numeric The number of times a card number was successfully authorized on your account in the past hour.
auths_per_customer_daily Numeric The number of times a customer was successfully authorized on your account in the past 24 hours.
auths_per_customer_hourly Numeric The number of times a customer was successfully authorized on your account in the past hour.
auths_per_ip_address_daily Numeric The number of times an IP address was successfully authorized on your account in the past 24 hours.
auths_per_ip_address_hourly Numeric The number of times an IP address was successfully authorized on your account in the past hour.
blocks_per_card_number_daily Numeric The number of times a card number was blocked by Stripe’s machine learning models on your account in the past 24 hours.
blocks_per_card_number_hourly Numeric The number of times a card number was blocked by Stripe’s machine learning models on your account in the past hour.
blocks_per_customer_daily Numeric The number of times a customer was blocked by Stripe’s machine learning models on your account in the past 24 hours.
blocks_per_customer_hourly Numeric The number of times a customer was blocked by Stripe’s machine learning models on your account in the past hour.
blocks_per_ip_address_daily Numeric The number of times an IP address was blocked by Stripe’s machine learning models on your account in the past 24 hours.
blocks_per_ip_address_hourly Numeric The number of times an IP address was blocked by Stripe’s machine learning models on your account in the past hour.
charge_attempts_per_card_number_daily Numeric The number of times a card is charged on your account in the past 24 hours.
charge_attempts_per_card_number_hourly Numeric The number of times a card is charged on your account in the past hour.
charge_attempts_per_customer_daily Numeric The number of times a customer is charged on your account in the past 24 hours.
charge_attempts_per_customer_hourly Numeric The number of times a customer is charged on your account in the past hour.
charge_attempts_per_ip_address_daily Numeric The number of times an IP address is charged on your account in the past 24 hours.
charge_attempts_per_ip_address_hourly Numeric The number of times an IP address is charged on your account in the past hour.
declines_per_card_number_daily Numeric The number of times a card number was declined by the bank networks on your account in the past 24 hours.
declines_per_card_number_hourly Numeric The number of times a card number was declined by the bank networks on your account in the past hour.
declines_per_customer_daily Numeric The number of times a customer was declined by the bank networks on your account in the past 24 hours.
declines_per_customer_hourly Numeric The number of times a customer was declined by the bank networks on your account in the past hour.
declines_per_ip_address_daily Numeric The number of times an IP address was declined by the bank networks on your account in the past 24 hours.
declines_per_ip_address_hourly Numeric The number of times an IP address was declined by the bank networks on your account in the past hour.
is_3d_secure Boolean Identifies if the payment follows a successfully completed 3D Secure verification.
is_anonymous_ip Boolean Identifies if the IP address from which the payment originates is a known proxy or Tor exit node. Stripe uses a third-party database of anonymous IP addresses to provide this attribute.
is_disposable_email Boolean Identifies if the email address supplied with the payment is one used with a known throwaway email address provider. Stripe maintains a list of domains corresponding to throwaway email addresses to provide this attribute.
is_my_login_ip Boolean Identifies if the IP address from which the payment originates has ever been used to log into your Stripe account. This attribute can be used as a proxy for “is my IP address.”

The email_domain and is_disposable_email attributes make use of an email address found in any of the following fields:

  • The receipt_email of the payment
  • The description of the payment
  • The name of the card (if an email address has been provided as the cardholder name)
  • The email of the customer that the payment was created on
  • The description of the customer or payment

Operators

A condition’s operator denotes the comparison between the payment’s attribute and the value you provide. There are different operators available, depending on the type attribute being used.

Operator String Country Numeric Description Example
= ✔︎ ✔︎ ✔︎ Equal to :card_country: = 'us'
!= ✔︎ ✔︎ ✔︎ Not equal to :card_funding: != 'prepaid'
<     ✔︎ Less than :amount_in_gbp: < 10.00
>     ✔︎ Greater than :amount_in_usd: > 500.00
<=     ✔︎ Less than or equal to :amount_in_eur: <= 100.00
>=     ✔︎ Greater than or equal to :amount_in_cad: >= 10.00
IN ✔︎ Is in the group :card_country: IN ('gb', 'ie')

Complex conditions

You can build complex conditions by joining together basic conditions using the operators AND, OR, and NOT. You can also use their symbolic equivalents &&, || and ! respectively.

Similar to programming languages such as C, Python, and SQL, Stripe supports standard operator precedence (order of operations). For instance, the complex condition:

{condition_X} OR NOT {condition_Y} AND {condition_Z}

is interpreted as:

{condition_X} OR ((NOT {condition_Y}) AND {condition_Z})

Sub-conditional grouping within complex conditions is also supported using parentheses. For instance, the prior example can be amended to explicitly change the evaluation order of sub-predicates:

({condition_X} OR (NOT {condition_Y})) AND {condition_Z}

{condition_X} OR NOT ({condition_Y} AND {condition_Z})

By using parentheses in different locations, each of these complex conditions lead to different results.

Valid conditions

The following conditions are examples of correct use of attributes and a supported operator:

  • :card_brand: = 'amex'
  • :card_country: != 'US'
  • :amount_in_usd: >= 1000.00
  • :is_anonymous_ip:

Invalid conditions

When creating a rule, you’re provided with feedback if you attempt to use a condition that is invalid. For reference, the following are examples of invalid conditions, where the value for an attribute or the operator used is not supported:

  • :risk_level: < 'highest' (string values can only make use of = or != operators)
  • :ip_country: = 'Canada' (country values must be expressed in two-letter short code)
  • :amount_in_usd: >= 'one thousand dollars' (numeric values must be expressed in numbers)
  • :is_anonymous_ip: = 'true' (boolean attributes are not used with operators or values)