Referência de regras

Antes de criar uma regra, você precisa entender como as regras são processadas e quais atributos de pagamento podem ser usados para definir os critérios de avaliação. Os sistemas de machine learning de combate à fraude da Stripe podem bloquear várias fraudes em pagamentos, mas você também pode configurar regras únicas para sua empresa usando os atributos aceitos.

Processamento e ordem de regras

O Radar avalia cada pagamento em relação às regras criadas por você de acordo com o tipo de ação, com a seguinte prioridade:

1. Solicitar 3DS: regras que exigem autenticação do 3D Secure, se aceito, quando usadas com a API Payment Intents ou o Checkout. O Radar avalia essas regras antes de qualquer regra de bloqueio, análise ou permissão.
2. Permitir: regras que permitem o processamento de um pagamento. Os pagamentos aprovados pelas regras de permissão não são avaliados pelas regras de bloqueio ou análise.
3. Bloquear: regras que bloqueiam e recusam um pagamento. Os pagamentos bloqueados não são avaliados por nenhuma regra de análise.
4. Analisar: regras que permitem o processamento de pagamentos, mas os enviam para análise.

Regras do mesmo tipo de ação não são ordenadas.

Se um pagamento cumpre os critérios de uma regra, o Radar executa a ação adequada e interrompe a avaliação. Por exemplo, se um pagamento cumpre uma regra de permissão, é processado normalmente, sem avaliação de nenhuma regra de bloqueio ou análise, mesmo que o pagamento cumpra seus critérios. Um exemplo de conjunto de regras pode ser o seguinte:

• Permitir pagamentos abaixo de $10
• Permitir pagamentos realizados nos EUA com nível de risco normal
• Bloquear pagamentos com nível de risco high
• Bloquear pagamentos greater than $1,000
• Analisar pagamentos realizados com um cartão emitido outside the US

Uso das regras acima:

• Todos os pagamentos inferiores a US$ 10 são processados, independentemente do nível de risco ou local de emissão. Como a primeira regra permite o pagamento, nenhuma outra regra é avaliada.
• Um pagamento de US$ 1.500 feito nos EUA com um nível de risco normal é processado normalmente porque cumpre os critérios da segunda regra. Portanto, não é avaliado em relação à regra de bloqueio de pagamentos acima de US$ 1.000.
• Um pagamento de alto risco acima de US$ 1.000 é bloqueado porque não cumpre os critérios de nenhuma das regras de permissão e aciona ambas as regras de bloqueio, independentemente da ordem de avaliação.

Estrutura das regras

A estrutura da regra tem dois componentes: a ação a ser realizada e a condição a ser avaliada:

{action} if {condition}

Em conjunto, elas são chamadas de predicado. Na prática, esta seria uma regra para bloquear todos os pagamentos acima de 1.000 USD:

Block if :amount_in_usd: > 1000.00

• A ação é Block
• A condição é :amount_in_usd: > 1000.00

Ações

Uma regra executa uma das quatro ações descritas nesta seção quando um pagamento cumpre seus critérios. A ordem dos tipos de ação a seguir representa a prioridade seguida pelo Radar ao avaliar cada regra.

Solicitar 3D Secure

Quando usada com a API Payment Intents, esta regra determina se a Stripe solicitará ao emissor que tente usar a autenticação 3D Secure. Apenas a solicitação do 3DS não bloqueia todos os resultados possíveis do 3D Secure. Independentemente de haver ou não correspondências nessa regra, avaliamos as regras para permissão, bloqueio e análise posterior.

Permitir

Esta regra determina quando permitir um pagamento que cumpre determinados critérios, independentemente de qualquer outra regra correspondente. Quando um pagamento cumpre os critérios de uma regra de permissão, não fica sujeita à avaliação adicional das regras do Radar. A Stripe processa o pagamento normalmente, mas o emissor do cartão ainda pode recusá-lo.

Bloquear

As regras de bloqueio aconselham a Stripe a sempre bloquear um pagamento. Pagamentos que cumprem os critérios de uma regra de bloqueio são recusados pela Stripe e não são mais avaliados por nenhuma regra.

Revisar

Pode ser necessário permitir alguns tipos de pagamento com a opção de examiná-los mais detalhadamente. Com as regras de análise, você pode enviar pagamentos para análise. Isso é muito útil para pagamentos diferentes dos padrões comuns, como pagamentos de maior valor ou de um país pouco usado para entregas. A Stripe processa esses pagamentos e cobra o cliente, mas é possível analisar o pedido e verificar se há sinais de fraude.

Quando uma regra específica é acionada, o Radar executa a ação prescrita e interrompe a avaliação de qualquer regra.

Condições

Se um pagamento cumpre a condição de uma regra, a ação correspondente é executada. Uma condição básica consiste em três partes:

[attribute] [operator] [value]

• Atributo: o atributo de um pagamento (por exemplo, o valor ou tipo do cartão)
• Operador: a aritmética que compara o atributo e o valor (por exemplo, maior que ou diferente de)
• Valor: o critério que você quer usar (por exemplo, 100.00 ou debit)

A estrutura de uma regra combina a ação e a condição:

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

Há quatro tipos de condição, dependendo do tipo de atributo:

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

Você também pode usar atributos como valor correspondente em uma condição. Por exemplo, é possível criar uma regra para bloquear pagamentos quando o país emissor do cartão não corresponde ao país onde o pagamento ocorreu:

Block if :card_country: != :ip_country:

Para obter uma lista de todas as condições possíveis, consulte os atributos aceitos.

Atributos de string

Estes atributos contêm qualquer combinação de caracteres. Os atributos e valores de string costumam representar um fragmento de texto, como a marca de um cartão (por exemplo, visa, amex) ou um nível de risco (como elevated). Você pode usá-los em regras para permitir somente os pagamentos de um determinado país ou bloquear pagamentos realizados com cartões pré-pagos.

Atributos de metadados

Estes atributos são obtidos dos metadados que você associou aos pagamentos. Os atributos de metadados podem operar como strings ou números. Quando usados como strings, os atributos de metadados diferenciam maiúsculas e minúsculas.

Você pode usar esses atributos durante a criação de regras do Stripe Radar que processam atributos de negócio personalizados passados à Stripe no campo de metadados associado aos pagamentos.

Os atributos de metadados são criados com a seguinte estrutura:

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

Por exemplo, vamos supor que temos pagamentos com os seguintes dados chave-valor armazenados no campo de metadados:

Você pode criar uma regra que envia para análise os pagamentos que cumprem os critérios especificados.

Review if ::Customer Age:: < 30

Também é possível criar regras usando atributos de metadados e outros atributos aceitos mencionados neste documento. Por exemplo, você pode criar uma regra que envia para análise apenas os pagamentos em que Item ID é 5A381D e o valor excede 1.000 USD.

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

Os atributos de metadados também aceitam o operador IN para correspondência com vários valores. Por exemplo, você pode criar uma regra que envia para análise os pagamentos em que Category ID é uma destas opções: mantimentos, produtos eletrônicos ou vestuário.

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

O operador INCLUDES pode ser usado em regras com atributos de metadados ou outros atributos de string para correspondência com substrings. Por exemplo, você pode criar uma regra que envia para análise os pagamentos em que Item ID inclui a string A381. A regra é cumprida para A381, 5A381D, A381D e 5A381, entre outros.

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

Metadados em objetos Customer e Destination

Também é possível acessar metadados nos objetos Customer e Destination (se usados em um determinado pagamento). Esses atributos usam a seguinte estrutura:

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

Por exemplo, vamos supor que você tem um cliente com estes metadados:

É possível criar uma regra que permite pagamentos em que o campo Trusted dos metadados do cliente é true.

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

No caso de um destino com os seguintes metadados:

É possível criar uma regra que envia para análise os pagamentos em que o campo Category dos metadados é new.

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

Atributos de país

Estes atributos usam códigos de país de duas letras para representar um país, como US para Estados Unidos, GB para Grã-Bretanha ou AR para Argentina. Os atributos de país operam da mesma forma que os de string, mas seu valor deve ser um código de país.

Atributos de estado

Estes usam códigos ISO para representar o estado ou subdivisão principal de um país, como CA para representar a Califórnia dos Estados Unidos, ENG para representar a Inglaterra, que é parte da Grã-Bretanha ou L para representar La Pampa, que é parte da Argentina. Nós omitimos o código de país de duas letras do código ISO de estado, por isso, se quiser bloquear transações da Califórnia, compare o atributo estadual com CA.

Block se :ip_state: = 'CA'

Os atributos de estado operam da mesma forma que os atributos de string, com a única diferença de que o valor precisa ser um código ISO.

Atributos numéricos

Como contêm apenas números, estes atributos oferecem mais operadores que os atributos e valores de string. O valor de um pagamento é um exemplo de um atributo numérico. Você pode criar uma regra para executar uma ação se o valor for maior, menor ou igual a um valor especificado.

Para atributos numéricos que são contagens em períodos, a contagem não inclui o pagamento que está sendo processado. Por exemplo, total_charges_per_customer_hourly representa o número de tentativas de cobrança anteriores de um determinado cliente durante a hora anterior. Na primeira tentativa de cobrança de um cliente em uma hora específica, o valor de total_charges_per_customer_hourly é 0. Na segunda tentativa na mesma hora, o valor é 1 e assim por diante.

Atributos de tempo desde a primeira aparição também não consideram o pagamento que você está processando no momento. Por exemplo, um pagamento sem um e-mail tem um valor ausente para seconds_since_email_first_seen. O mesmo ocorre com pagamentos com e-mails jamais visualizados na sua conta (como não incluímos o pagamento que está sendo processado, esse é efetivamente o mesmo comportamento do primeiro exemplo). Confira abaixo para obter mais detalhes sobre valores ausentes. O campo seconds_since_email_first_seen somente é não nulo quando um novo pagamento com um determinado e-mail é processado.

Atributos numéricos limitados

Os atributos numéricos limitados são semelhantes aos atributos numéricos descritos acima. Por exemplo, eles excluem o pagamento que está sendo processado. A diferença é que os valores disponíveis para os atributos numéricos limitados têm um valor máximo específico.

Como exemplo, authorized_charges_per_email_hourly representa o número de cobranças anteriores autorizadas para o e-mail na última hora em sua conta. Vamos supor que o limite seja 5. Na primeira tentativa de cobrança na última hora com o e-mail jenny.rosen@example.com, o valor do contador é 0. As tentativas de cobrança seguintes na mesma hora aumentam o valor do contador. Depois de autorizar a sexta cobrança na mesma hora com o e-mail jenny.rosen@example.com, o contador não é mais incrementado e permanece 5, apesar das 6 tentativas de cobrança na última hora.

Se houver uma tentativa de incrementar o contador acima do limite, os valores mais antigos serão substituídos pelos mais recentes. Por exemplo, um contador com limite 3 já tem 3 cobranças. Podemos visualizar esse contador como uma lista de carimbos de data e hora que representam o horário das cobranças: [10, 20, 30]. Quando uma nova cobrança chega no horário 50, a lista muda para [20, 30, 50].

Atributos booleanos

Um atributo booleano representa se um atributo específico é verdadeiro. Ao contrário dos atributos string e numéricos, os atributos booleanos não têm operadores ou valores. Você pode usar um atributo booleano para bloquear pagamentos realizados com um e-mail descartável ou enviar para revisão os pagamentos realizados em um endereço IP anônimo.

Atributos de pós-autorização

Um atributo de pós-autorização (por exemplo, :cvc_check:, :address_zip_check: ou :address_line1_check:) exige que a Stripe permute dados com os emissores do cartão durante o processo de autorização. O emissor do cartão verifica se esses dados correspondem aos que estão cadastrados para o titular do cartão. As regras que usam atributos de pós-autorização são executadas após as regras que não usam esses atributos. Isso não afeta a decisão de bloquear ou não a cobrança, mas pode alterar a regra que bloqueia a cobrança.

Quando você usa um atributo de pós-autorização em uma regra, o extrato do cliente pode mostrar temporariamente uma autorização, mesmo que a cobrança seja bloqueada depois. Nesse caso, a autorização costuma desaparecer em alguns dias.

Os atributos de endereço (AVS) e de CVC têm cinco possíveis valores:

Alguns exemplos de regras:

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

Exigir um pass rigoroso em regras pode ser excessivamente restritivo. Por exemplo, as carteiras não costumam fornecer um CVC porque armazenam informações tokenizadas dos cartões. Por isso as verificações de CVC, como 3D-Secure, não estão disponíveis para formas de pagamento como o Apple Pay. A Stripe recomenda usar as regras incorporadas do Radar, que levam em consideração esses casos extremos.

Atributos aceitos

Consulte a lista de todos os atributos aceitos para ver uma relação completa de atributos que você pode aplicar às suas definições de regra.

Valores convertidos

Quando você usa amount_in_xyz, a Stripe converte automaticamente o valor de todos os pagamentos para verificar se ele cumpre os critérios escolhidos. Por exemplo, se você cria uma regra usando amount_in_usd para bloquear todos os pagamentos acima de US$ 1.000, a Stripe bloqueia os pagamentos com valor nominal inferior em moedas diferentes (como GBP 900) se, após a conversão, o valor estiver acima de 1US$ 1.000.

Na prática, “considerados pagamentos de 2020 em diante”

As descrições de alguns atributos de regra incluem a frase “considera pagamentos a partir de 2020”. Isso significa que a regra trata um cartão feito para a última transação com sua empresa em 2019 da mesma forma que um cartão novo para sua empresa. Considere o que isso significa no contexto da sua empresa e das suas regras, pois pode resultar em comportamentos contra-intencionados. Por exemplo, se você criar uma regra para bloquear pagamentos de alto valor de novos cartões, pode acabar bloqueando um bom cliente que não faz uma compra desde 2019.

“Esse atributo inclui apenas objetos Customer no modo de produção que interagiram com sua conta no(a) último(a) <week, year>. Os dados são atualizados a cada 72 horas.” na prática

As descrições de alguns atributos de regra incluem as frases “Esse atributo inclui apenas objetos Customer no modo de produção que interagiram com sua conta no(a) último(a) <week, year>. Os dados são atualizados a cada 72 horas”. Isso significa que os objetos Customer no modo de produção que foram criados, cobrados ou atualizados na sua conta na última semana ou ano estão incluídos nessas contagens. No entanto, a contagem não é atualizada imediatamente e pode levar até 72 horas para se propagar pelo sistema, embora muitas vezes esses contadores sejam atualizados antes de 72 horas.

Operadores

O operador de uma condição indica a comparação efetuada entre o atributo do pagamento e o valor informado. Há vários operadores disponíveis, dependendo do tipo de atributo usado.

Listas

Você pode fazer referência a um grupo de valores nas regras usando listas. Todos os aliases de listas mencionados nas regras devem começar com @. Para construir uma regra que mencione uma lista, siga esta estrutura:

{action} [attribute] in [list]

Por exemplo, vamos supor que você tem uma lista de países de cartão que deseja bloquear. Você pode criar uma regra usando várias cláusulas OR:

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

Também é possível criar uma regra usando uma lista em linha:

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

Você também pode criar uma lista de países de cartão que você quer bloquear com o nome card_countries_to_block, adicionar os países desejados à lista e usá-la em uma regra:

Block if :card_country: in @card_countries_to_block

Quando você menciona uma lista em uma regra, pode editar um grande número de itens em um único lugar em vez de manter várias regras individuais.

Atributos não encontrados

As condições de regra comuns mencionam atributos definidos em cada pagamento, como :card_country: (que é definido em toda cobrança de cartão) ou um atributo de metadados informado sempre nas solicitações de pagamento. Alguns cenários podem não utilizar certos atributos. Por exemplo:

• Você tem vários fluxos de checkout no site e alguns deles não coletam os e-mails dos clientes

• Você começou a usar o Stripe.js recentemente. Por isso, :ip_country: está disponível para novos pagamentos, mas não para pagamentos históricos (que pesquisamos quando visualizamos regras)

• Por erro da sua integração, uma chave de metadados esperada não é definida em alguns pagamentos

Como as condições de regra avaliam atributos não encontrados

Considere a regra Block if :email_domain: = 'definitelyfraud.com'. Se você não coletou o e-mail do cliente, o atributo :email_domain: não existe e, portanto, a condição da regra não corresponderá ao pagamento.

Considere a regra Review if :email_domain: != 'definitelysafe.com'. Se o atributo :email_domain: não for encontrado, a regra também não corresponderá ao pagamento. Isso pode parecer uma correspondência, pois um valor não encontrado é diferente de 'definitelysafe.com'. No entanto, interpretamos != 'definitelysafe.com' como “o atributo tem algum valor diferente de 'definitelysafe.com',” uma condição que não é cumprida por um atributo não encontrado. As informações de atributo ausente também são transmitidas ao usar o operador NOT, de forma que a regra Review if NOT (:email_domain: = 'definitelysafe.com') também não corresponderá ao pagamento se o atributo :email_domain: estiver faltando.

De modo mais geral, qualquer comparação (por exemplo, =, !=, >, <) entre um recurso não encontrado e outro valor ou recurso estático (não encontrado ou presente) sempre retorna falso. O uso do operador NOT com qualquer comparação contendo um recurso ausente sempre retorna falso.

Lidar explicitamente com a função is_missing

Se você quer verificar explicitamente a existência de um atributo ou atributo de metadados, use a função is_missing e informe a ela a chave de metadados ou atributo não encontrado.

Por exemplo, você pode criar uma regra para corresponder todos os pagamentos em que você não tem acesso ao e-mail de um cliente:

• Review if is_missing(:email_domain:)

Ou criar uma regra para corresponder todos os pagamentos com um determinado atributo de metadados definido:

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

Também é possível usar a função is_missing com as conjunções OR ou AND:

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

Condições complexas

Você pode criar condições complexas associando condições básicas com os operadores AND, OR e NOT. Também é possível usar seus respectivos equivalentes simbólicos: &&, || e !.

Assim como nas linguagens de programação como C, Python e SQL, a Stripe usa a precedência padrão de operadores (ordem de operações). Por exemplo, a condição complexa:

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

é interpretada como:

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

Use parênteses para especificar agrupamentos subcondicionais com condições complexas. Por exemplo, você pode alterar o exemplo anterior para mudar explicitamente a ordem de avaliação dos subpredicados:

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

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

Com o uso de parênteses em locais distintos, cada uma dessas condições complexas gera resultados diferentes.

Condições válidas

As condições a seguir são exemplos do uso correto de atributos e de um operador válido:

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

Condições inválidas

O Radar informa quando você tenta usar uma condição inválida na criação de uma regra. Use estes exemplos de condições inválidas em que o valor de um atributo ou o operador não é aceito:

• :risk_level: < 'highest' (valores do tipo string só podem usar operadores = ou !=)
• :ip_country: = 'Canada' (valores de país devem ser especificados com o código abreviado de duas letras)
• :amount_in_usd: >= 'one thousand dollars' (valores numéricos devem ser especificados com números)
• :is_anonymous_ip: = 'true' (valores booleanos não são usados com operadores ou valores)

Regras de velocidade

Muitos atributos aceitos incluem invariáveis para diferentes escalas de tempo (por exemplo, o daily em total_charges_per_email_daily). Essas regras são chamadas de regras de velocidade.

A Stripe calcula atributos usando incrementos de bucket. A duração do aumento varia conforme o intervalo do atributo. Isso significa que a velocidade de qualquer atributo pode incluir dados que ocorreram dentro do intervalo mais um bucket. Por exemplo, um intervalo de atributo de hora em hora pode ser de 3.900 segundos (uma hora e cinco minutos) da transação atual porque o intervalo usa buckets de cinco minutos.

Os atributos são definidos como:

• hourly é até 3900 segundos (buckets de 5 minutos)
• daily é até 90000 segundos (buckets de 1 hora)
• weekly é até 608400 segundos (buckets de 1 hora)
• yearly é até 31622400 segundos (buckets de 1 dia)
• all_time inclui 5 anos de dados com velocidade de até 31622400 segundos (buckets de 1 dia)

Um caso de uso comum desses atributos é reduzir os testes de cartões ou cenários de ataque de enumeração, conforme explicado no Guia de introdução ao Radar.