Documentation sur les règles

Avant de créer une règle, vous devez comprendre comment elle est traitée et quels attributs de paiement vous pouvez utiliser pour définir des critères d’évaluation. Les systèmes de prévention de la fraude de Stripe reposant sur le machine learning peuvent bloquer automatiquement de nombreux paiements frauduleux, mais vous pouvez aussi configurer des règles spécifiques à votre entreprise à l’aide des attributs pris en charge.

Traitement et classement des règles

Radar évalue chaque paiement par rapport aux règles que vous créez en fonction de leur type d’action, en utilisant l’ordre de priorité suivant :

1. Request 3DS : règles qui, si elles sont utilisées avec l’API Payment Intents ou Checkout, demandent à l’émetteur de procéder à une authentification 3D Secure si elle est prise en charge. Radar évalue ces règles avant toute règle de blocage, de vérification ou d’autorisation.
2. Autoriser : règles qui autorisent le traitement d’un paiement. Les paiements qui s’inscrivent dans le cadre des règles d’autorisation ne sont pas évaluées par rapport aux règles de blocage ou de vérification.
3. Bloquer : règles qui bloquent un paiement et le refusent. Les paiements bloqués ne sont pas évalués par rapport aux règles de vérification.
4. Vérifier : règles qui autorisent le traitement d’un paiement, mais qui placent ensuite ce dernier en vérification.

Les règles du même type d’action ne sont pas ordonnées.

Si un paiement correspond aux critères d’une règle, Radar effectue l’action appropriée et interrompt l’évaluation. Par exemple, si un paiement correspond à une règle d’autorisation, il est traité normalement, sans évaluation des règles de blocage ou d’examen ultérieurs, même si le paiement répond également aux critères. Voici un exemple d’ensemble de règles :

• Autoriser les paiements de moins de $10
• Autoriser les paiements effectués aux États-Unis avec un niveau de risque normal
• Bloquer les paiements pour lesquels le niveau de risque est high
• Bloquer les paiements greater than $1,000
• Vérifier les paiements effectués avec une carte émise outside the US

En utilisant les règles ci-dessus :

• Tous les paiements inférieurs à 10 USD sont traités, quel que soit leur niveau de risque ou leur lieu d’émission. Étant donné que la première règle autorise le paiement, aucune autre règle n’est évaluée.
• Un paiement de 1 500 USD effectué aux États-Unis avec un niveau de risque normal est traité normalement, car il répond aux critères de la deuxième règle, et n’est donc pas évalué dans le cadre de la règle de blocage des paiements de plus de 1 000 USD.
• Un paiement à haut risque de plus de 1 000 USD est bloqué, car il ne répond pas aux critères de l’une ou l’autre règle d’autorisation et déclenche les deux règles de blocage, quel que soit l’ordre d’évaluation.

Structure des règles

La structure de la règle présente deux composants : l’action à effectuer et la condition à évaluer :

{action} if {condition}

Ces deux composants représentent le prédicat. Dans la pratique, une règle visant à bloquer tous les paiements supérieurs à 1 000 USD se présente comme suit :

Block if :amount_in_usd: > 1000.00

• L’action est Block
• La condition est :amount_in_usd: > 1000.00

Actions

Une règle exécute l’une des quatre actions décrites dans cette section lorsqu’un paiement répond à ses critères. L’ordre des types d’action suivants représente la priorité que Radar suit lors de l’évaluation de chaque règle.

Request 3D Secure

Lorsqu’elle est utilisée avec l’API Payment Intents, cette règle détermine si Stripe demande à l’émetteur de procéder à l’authentification 3D Secure. La demande de 3DS à elle seule ne bloque pas encore tous les résultats possibles de 3D Secure. Quelles que soient les correspondances aux critères de cette règle, les règles d’autorisation, de blocage et de vérification sont évaluées après celle-ci.

Autoriser

Cette règle détermine quand autoriser un paiement qui répond à certains critères, sans tenir compte des autres règles de correspondance. Lorsqu’un paiement répond aux critères d’une règle d’autorisation, il n’est plus soumis à aucune autre évaluation des règles Radar. Stripe traite le paiement normalement, mais l’émetteur de la carte peut le refuser.

Bloquer

Les règles de blocage indiquent à Stripe de toujours bloquer un paiement. Si un paiement répond aux critères d’une règle de blocage, Stripe le refuse et il n’est pas soumis à une autre évaluation de règles.

Vérifier

Il se peut que vous vouliez autoriser certains types de paiements, tout en ayant la possibilité de les examiner de plus près. Avec les règles de vérification, vous pouvez placer les paiements en vérification. Cela est particulièrement utile pour les paiements qui ne suivent pas un modèle standard, comme ceux au montant plus élevé ou ceux provenant d’un pays vers lequel vous ne réalisez pas souvent des livraisons. Stripe traite ces paiements et débite le client comme d’ordinaire, mais vous avez en plus l’opportunité de vérifier la commande et de la contrôler pour détecter les éventuels signes de fraude.

Lorsqu’une règle particulière est déclenchée, Radar effectue l’action recommandée et interrompt toute autre évaluation de la règle.

Conditions

Si un paiement correspond à la condition d’une règle, l’action correspondante est effectuée. Une condition de base est, elle-même, constituée de trois parties :

[attribute] [operator] [value]

• Attribut : l’attribut d’un paiement (par exemple, le montant ou le type de carte)
• Opérateur : l’arithmétique qui compare l’attribut à la valeur (par exemple, supérieur à ou différent de)
• Valeur : les critères que vous voulez utiliser (par exemple, 100.00 ou debit)

En combinant l’action et la condition, la structure d’une règle est la suivante :

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

Il existe quatre types de condition, selon le type d’attribut :

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

Vous pouvez aussi utiliser des attributs comme valeur correspondante dans une condition. Par exemple, vous pouvez créer une règle pour bloquer les paiements pour lesquels le pays d’émission de la carte ne correspond pas au pays dans lequel le paiement a été effectué :

Block if :card_country: != :ip_country:

Pour obtenir la liste de toutes les conditions possibles, reportez-vous aux attributs pris en charge.

Attributs de chaînes

Ils contiennent toutes les combinaisons de caractères. Les attributs et les valeurs de chaîne représentent la plupart du temps un texte, comme une marque de carte (par exemple, visa, amex) ou le niveau de risque (par exemple, elevated). Vous pouvez les utiliser dans les règles pour autoriser uniquement les paiements provenant d’un pays particulier ou pour bloquer les paiements effectués avec des cartes prépayées.

Attributs de métadonnées

Ces attributs sont dérivés des métadonnées que vous avez jointes à vos paiements. Les attributs de métadonnées peuvent agir comme des chaînes ou des valeurs numériques. Lorsqu’ils sont utilisés en tant que chaînes, les attributs de métadonnées sont sensibles à la casse.

Vous pouvez utiliser ces attributs lors de la création des règles Stripe Radar, ce qui vous permet d’écrire des règles tenant compte de tout attribut professionnel personnalisé que vous avez transmis à Stripe dans le champ des métadonnées joint à vos paiements.

Les attributs de métadonnées sont écrits en suivant cette structure :

::[metadata attribute name]:: [operator] [metadata_value]

Par exemple, supposons que nous ayons des paiements avec les données clé-valeur suivantes sauvegardées dans le champ des métadonnées :

Vous pouvez écrire une règle pour placer les paiements qui répondent aux critères suivants en vérification.

Review if ::Customer Age:: < 30

Vous pouvez également écrire des règles à l’aide d’attributs de métadonnées et d’autres attributs pris en charge mentionnés dans ce document. Par exemple, vous pouvez écrire une règle qui place un paiement en vérification uniquement si le Item ID correspond à 5A381D et que le montant du paiement dépasse 1 000 USD.

Review if ::Item ID:: = '5A381D' and :amount_in_usd: > 1000

Les attributs de métadonnées prennent également en charge l’opérateur IN pour comparer avec plusieurs valeurs. Par exemple, vous pouvez écrire une règle qui place un paiement en vérification si le Category ID se rapporte aux produits alimentaires, aux équipements électroniques ou aux vêtements.

Review if ::Category ID:: IN ('groceries', 'electronics', 'clothing')

Vous pouvez utiliser l’opérateur INCLUDES avec des règles pour les attributs de métadonnées et d’autres attributs de chaîne pour établir la correspondance avec des sous-chaînes. Par exemple, vous pouvez écrire une règle qui place un paiement en vérification si le Item ID inclut la chaîne A381. Il correspond à A381, 5A381D, A381D, 5A381, etc.

Review if ::Item ID:: INCLUDES 'A381'

Métadonnées dans les objets Client et Destination

Vous pouvez aussi accéder aux métadonnées dans les objets Client et Destination (si ces derniers sont utilisés pour un paiement donné). Ces attributs utilisent la structure suivante :

::[customer|destination]:[metadata attribute name]:: [operator] [metadata_value]

Par exemple, supposez qu’un de vos clients présente les métadonnées suivantes :

Vous pourriez écrire une règle qui autorise les paiements si le champ des métadonnées Trusted du client est true.

Allow if ::customer:Trusted:: = 'true'

Ou bien si vous aviez une destination avec les métadonnées suivantes :

Vous pourriez écrire une règle qui place un paiement en vérification si le champ des métadonnées Category de la destination est new.

Review if ::destination:Category:: = 'new'

Attributs de pays

Ces attributs utilisent des codes de pays à deux lettres pour représenter un pays, comme US pour les États-Unis, GB pour la Grande-Bretagne ou AR pour l’Argentine. Les attributs de pays fonctionnent de la même manière que les attributs de chaîne, à la seule différence que la valeur doit être un code de pays.

Attributs d’État

Ces attributs utilisent des codes ISO pour représenter l’État ou la subdivision principale d’un pays, comme CA pour représenter la Californie des États-Unis, ENG pour représenter l’Angleterre qui fait partie de la Grande-Bretagne, ou L pour représenter La Pampa, province d’Argentine. Nous omettons le code pays à deux lettres du code ISO de l’État. Par conséquent, si vous souhaitez bloquer les transactions provenant de Californie, comparez l’attribut d’État à CA.

Block if :ip_state: = 'CA'

Les attributs d’État fonctionnent de la même manière que les attributs de chaîne, à la seule différence que la valeur doit être un code ISO.

Attributs numériques

Puisqu’ils contiennent uniquement des nombres, ils prennent en charge plus d’opérateurs que les attributs de chaînes et les valeurs. Le montant d’un paiement est un exemple d’attribut numérique. Vous pouvez créer une règle qui exécute une action si le montant est supérieur, inférieur, égal, ou différent du montant que vous indiquez.

Pour les attributs numériques qui correspondent à des décomptes sur une période, le décompte exclut le paiement en cours de traitement. Par exemple, total_charges_per_customer_hourly représente le nombre de précédentes tentatives de paiement d’un client donné au cours de l’heure passée. La première tentative de paiement effectuée au cours d’une heure donnée pour un client, total_charges_per_customer_hourly, comporte donc la valeur 0. Pour la deuxième tentative de paiement effectuée au cours de la même heure, la valeur est de 1, etc.

Les attributs « temps écoulé depuis la première apparition » ne prennent pas non plus en compte le paiement que vous êtes en train de traiter. Par exemple, un paiement dépourvu d’e-mail a une valeur manquante pour seconds_since_email_first_seen. Il en est de même pour les paiements qui sont associés à des e-mails jamais vus auparavant sur votre compte (comme nous ne tenons pas compte du paiement en cours de traitement, le comportement est effectivement le même que dans le premier exemple). Pour plus de détails sur les valeurs manquantes, voyez ci-dessous. Le champ seconds_since_email_first_seen a uniquement une valeur non nulle une fois qu’un nouveau paiement avec un e-mail donné a été traité.

Attributs numériques limités

Les attributs numériques limités sont équivalents aux attributs numériques décrits ci-dessus. Ils excluent par exemple le paiement en cours de traitement. La différence repose dans le fait que les valeurs disponibles pour les attributs numériques limités sont plafonnées (ou limitées) à une certaine valeur.

Prenons par exemple le paramètre authorized_charges_per_email_hourly, qui représente le nombre de paiements précédents autorisés sur votre compte pour l’adresse e-mail donnée et au cours de l’heure écoulée. Dans le cadre de cet exemple, attribuons-lui une limite de 5. Le décompte a une valeur de 0 pour la première tentative de paiement effectuée pendant l’heure passée avec l’adresse jenny.rosen@example.com. Les tentatives de paiement suivantes effectuées au cours de la même heure auront donc des valeurs de décompte plus élevées. Après autorisation de la 6ème tentative au cours de l’heure écoulée pour l’adresse e-mail jenny.rosen@example.com, le décompte s’arrête et reste défini sur 5, même s’il y a eu 6 tentatives effectives de modification au cours de l’heure écoulée.

En cas de tentative d’incrémentation du décompte dépassant le plafond défini, nous excluons les valeurs les plus anciennes du décompte et les remplaçons par les valeurs les plus récentes. Par exemple, un décompte avec un plafond de 3 déjà soumis à 3 tentatives de paiement. Pour visualiser le décompte, vous pouvez notamment tenir une liste des horodatages représentant les heures d’arrivée des paiements : [10, 20, 30], par exemple. Lorsqu’un paiement arrive à l’heure 50, le décompte affiche alors [20, 30, 50].

Attributs booléens

Un attribut booléen indique si un attribut spécifique est vrai. Contrairement aux attributs de chaîne et aux attributs numériques, les attributs booléens n’ont ni opérateur ni valeur. Vous pouvez utiliser un attribut booléen pour bloquer les paiements effectués avec une adresse e-mail temporaire ou pour placer en vérification les paiements effectués avec une adresse IP anonyme.

Attributs de post-autorisation

Un attribut post-autorisation (par exemple, :cvc_check:, :address_zip_check:, ou :address_line1_check:) nécessite que Stripe échange des données avec les émetteurs de carte dans le cadre du processus d’autorisation. L’émetteur de carte vérifie ces données en les comparant aux informations dont il dispose sur le titulaire de la carte et voit si elles correspondent. Les règles qui utilisent les attributs post-autorisation sont exécutées après les règles qui ne les utilisent pas. (Cela n’aura aucun effet sur la décision de bloquer le paiement ou non, mais peut avoir un impact sur le choix de la règle qui bloque le paiement).

Si vous utilisez un attribut post-autorisation dans une règle, le relevé de votre client peut indiquer temporairement une autorisation, même si le paiement est, à terme, bloqué (l’autorisation disparaît généralement au bout de quelques jours).

Les attributs d’adresse (AVS) et de CVC présentent cinq valeurs possibles :

Exemples de règles :

• Block if :address_line1_check: = 'fail'
• Block if :cvc_check: = 'fail'
• Block if :address_zip_check: in ('fail', 'not_provided')

Exiger un état pass strict pour les règles peut s’avérer trop restrictif. Par exemple, les portefeuilles ne fournissent généralement pas de CVC parce qu’ils stockent des informations de carte tokenisées. Par conséquent, les vérifications du CVC, comme les vérifications 3D-Secure, ne sont pas disponibles pour les méthodes de paiement telles qu’Apple Pay. Stripe recommande d’utiliser les règles intégrées de Radar, qui tiennent compte de ces cas particuliers.

Attributs pris en charge

Reportez-vous à la liste de tous les attributs pris en charge pour obtenir la liste complète des attributs que vous pouvez appliquer à vos définitions de règles.

Montants convertis

Lorsque vous utilisez amount_in_xyz, Stripe détermine automatiquement le montant converti de chaque paiement au moment de vérifier si le montant répond aux critères que vous avez choisis. Par exemple, si vous créez une règle avec amount_in_usd pour bloquer tous les paiements supérieurs à 1 000 USD, Stripe bloquera tout paiement d’un montant nominal inférieur dans une devise différente (par exemple, 900 GBP) si sa valeur convertie équivalente excède 1 000 USD.

« Prend en compte les paiements à partir de 2020 », dans la pratique

La description de certains attributs de règle inclut la phrase « Prend en compte les paiements à partir de 2020 ». Cela signifie que la règle traite une carte dont la dernière transaction avec votre entreprise remonte à 2019 de la même manière qu’une carte tout juste ajoutée à votre entreprise. Veillez à bien réfléchir aux implications de cette phrase en tenant compte du contexte de votre entreprise et de vos règles, pour éviter d’obtenir un comportement contraire à celui escompté. Par exemple, si vous créez une règle visant à bloquer les paiements de montants élevés provenant de nouvelles cartes, vous risquez de bloquer un bon client qui n’a effectué aucun achat depuis 2019.

« Cet attribut prend uniquement en compte les objets Customer en mode production ayant interagi avec votre compte au cours de la période précédente suivante : <week, year>. » En pratique, ces données sont mises à jour toutes les 72 heures maximum.

Les descriptions de certains attributs de règles incluent les phrases suivantes : « Cet attribut prend uniquement en compte les objets Customer en mode production ayant interagi avec votre compte au cours de la période précédente suivante : <week, year>. » Ces données sont mises à jour toutes les 72 heures maximum. Cela signifie que tous les objets Customer créés, chargés ou mis à jour en mode production sur votre compte au cours de la semaine ou année précédente sont comptabilisés. La mise à jour n’est cependant pas immédiate et peut prendre jusqu’à 72 heures pour être totalement effective, bien que ces compteurs soient souvent mis à jour avant 72 heures.

Opérateurs

Un opérateur de condition indique la comparaison entre l’attribut du paiement et la valeur que vous fournissez. D’autres opérateurs sont disponibles, selon le type d’attribut utilisé.

Listes

Vous pouvez référencer un groupe de valeurs dans vos règles via des listes. Tous les alias de listes référencés dans les règles doivent commencer par @. Pour créer une règle en référence à une liste, veuillez suivre la structure :

{action} [attribute] in [list]

Par exemple, imaginons que vous ayez une liste de pays de cartes que vous souhaitez bloquer. Vous pourriez écrire une règle utilisant plusieurs clauses OR :

Block if :card_country: = 'CA' OR :card_country: = 'DE' OR :card_country: = 'AE'

Vous pourriez aussi écrire une règle utilisant une liste intégrée :

Block if :card_country: IN ('CA', 'DE', 'AE')

Vous pourriez également créer une liste de pays de cartes que vous voulez bloquer, appelée card_countries_to_block. Vous pouvez alors ajouter les pays de votre choix à la liste et faire référence à cette liste dans une règle :

Block if :card_country: in @card_countries_to_block

Faire référence à une liste dans une règle vous permet de modifier un grand nombre d’éléments à un seul endroit plutôt que de gérer de nombreuses règles.

Attributs manquants

Les conditions de règles typiques se réfèrent aux attributs définis sur chaque paiement, comme :card_country: (défini sur chaque paiement sur carte) ou à un attribut de métadonnées que vous envoyez toujours avec vos requêtes de paiement. Dans certains scénarios, un attribut peut être manquant, par exemple :

• Vous disposez de différents flux de paiements sur votre site, et certains ne collectent pas l’adresse e-mail du client.

• Vous avez récemment commencé à utiliser Stripe.js, et donc :ip_country: est disponible pour les nouveaux paiements, mais indisponible pour les paiements antérieurs (que nous recherchons en prévisualisant les règles)

• Pour certains de vos paiements, un problème dans votre intégration empêche la définition de la clé de métadonnées attendue

Évaluation des attributs manquants par les conditions de règles

Considérez la règle Block if :email_domain: = 'definitelyfraud.com'. Si vous n’avez pas collecté l’adresse e-mail du client, l’attribut :email_domain: n’existera pas, et la condition de règle ne correspondra pas au paiement.

Imaginez maintenant la règle Review if :email_domain: != 'definitelysafe.com'. Si l’attribut :email_domain: est manquant, cette règle ne correspond pas non plus au paiement. Il peut sembler y avoir correspondance, car une valeur manquante est différente de 'definitelysafe.com'. Cependant, nous interprétons != 'definitelysafe.com' comme « l’attribut a une valeur différente de 'definitelysafe.com' », ce à quoi l’attribut manquant ne répond pas. Les attributs manquants sont également reportés lors de l’utilisation de l’opérateur NOT, de sorte que la règle if NOTemail_domain = 'definitelysafe.com' ne correspondrait pas non plus au paiement si l’attribut email_domain est manquant.

Plus généralement, toute comparaison (par exemple, =, !=, >, <) d’une caractéristique manquante à une autre valeur ou caractéristique statique (manquante ou présente) renvoie toujours le résultat « false ». L’utilisation de l’opérateur NOT avec une comparaison contenant une caractéristique manquante renvoie toujours le résultat « false ».

Gestion explicite avec la fonction is_missing

Si vous voulez vérifier explicitement l’existence d’un attribut ou d’un attribut de métadonnées, utilisez la fonction is_missing. Fournissez à cette fonction l’attribut ou la clé des métadonnées qui peut être manquant(e).

Par exemple, vous pourriez écrire une règle pour faire correspondre tous les paiements pour lesquels vous n’avez pas accès à l’adresse e-mail d’un client :

• Review if is_missing(:email_domain:)

Ou vous pourriez écrire une règle pour faire correspondre tous les paiements pour lesquels un certain attribut de métadonnées est défini :

• Review if !(is_missing(::foo::))

Vous pouvez aussi utiliser la fonction is_missing dans les conjonctions OR ou AND.

• Review if is_missing(:email_domain:) OR :email_domain: IN ('yopmail.net', 'yandex.ru')

Conditions complexes

Vous pouvez créer des conditions complexes en regroupant les conditions de base avec les opérateurs AND, OR et NOT. Vous pouvez aussi utiliser les symboles équivalents : &&, ||, et !, respectivement.

Tout comme les langages de programmation (C, Python et SQL), Stripe prend en charge la priorité standard des opérateurs (ordre des opérations). Par exemple, la condition complexe :

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

est interprété comme :

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

Le regroupement sous-conditionnel avec des conditions complexes est également pris en charge avec les parenthèses. Par exemple, vous pouvez corriger l’exemple précédent pour modifier explicitement l’ordre d’évaluation des sous-prédicats :

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

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

En plaçant les parenthèses à des emplacements différents, chaque condition complexe donne des résultats différents.

Conditions valides

Les conditions suivantes sont des exemples d’une utilisation correcte des attributs et d’un opérateur pris en charge :

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

Conditions non valides

Lors de la création de règles, Radar fournit un commentaire si vous tentez d’utiliser une condition non valide. Voici des exemples de conditions non valides, où la valeur d’un attribut ou de l’opérateur utilisé n’est pas prise en charge :

• :risk_level: < 'highest' (les valeurs de chaînes peuvent uniquement utiliser les opérateurs = ou !=)
• :ip_country: = 'Canada' (les valeurs relatives aux pays doivent être exprimées en codes courts de deux lettres)
• :amount_in_usd: >= 'one thousand dollars' (les valeurs numériques doivent être exprimées en chiffres)
• :is_anonymous_ip: = 'true' (Boolean attributes are not used with operators or values)

Règles de vélocité

De nombreux attributs de prise en charge incluent des invariants pour différentes échelles de temps (par exemple, daily dans total_charges_per_email_daily ). On les appelle les règles de vélocité.

Stripe calcule les attributs en utilisant des incréments de groupe. La durée de l’incrément varie en fonction de l’intervalle de l’attribut. Cela signifie que la vélocité pour n’importe quel attribut peut inclure des données qui se sont produites dans l’intervalle, plus un groupe. Par exemple, un intervalle d’attribut horaire peut correspondre à 3 900 secondes (une heure et cinq minutes) de la transaction en cours, car l’intervalle utilise des groupes de cinq minutes.

Les attributs sont définis comme suit :

• hourly dure jusqu’à 3 900 secondes (groupes de 5 minutes)
• daily dure jusqu’à 90 000 secondes (groupes d’une heure)
• weekly dure jusqu’à 608 400 secondes (groupes d’une heure)
• yearly dure jusqu’à 31 622 400 secondes (groupes d’un jour)
• all_time comprend 5 ans de données avec une vitesse allant jusqu’à 31 622 400 secondes (groupes d’un jour)

Un cas d’usage courant de ces attributs consiste à réduire les tests de cartes bancaires ou les scénarios d’attaque par énumération, comme expliqué dans le guide Radar 101.