Referência de regras

Antes de criar uma regra, você precisa entender como as regras são processadas e quais atributos de transação e conta podem ser usados para definir os critérios de avaliação. Os sistemas de machine learning de combate a fraudes 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 de transação

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. Solicitação de 3DS: regras que, quando usadas com a API Payment Intents ou Checkout, solicitam que o emissor faça autenticação do 3D Secure, se forem aceitas. 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.

Processamento de regras de conta

O Radar for Platforms permite que sua plataforma crie regras para ações em nível de transação e conta. Você pode criar uma conta para análise com ou sem a suspensão de repasses na conta.

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 da transação

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, essa regra determina se a Stripe solicita que o emissor tente a autenticação do 3D Secure. Apenas a solicitação de 3DS não bloqueia todos os possíveis resultados 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.

Ações da conta

O Radar for Platforms inclui regras que executam uma de duas ações quando uma conta cumpre seus critérios:

• Levantamento para análise
• Aumente para análise e suspenda repasses enquanto estiver em análise

Revisar

Sua plataforma pode aumentar avaliações em contas, que aparecem na seção Fila de revisão do Radar da sua lista de contas conectadas. As regras de revisão ajudam a identificar quando a própria conta pode estar causando danos financeiros à sua plataforma.

Suspensão de repasses (e revisão)

Você pode agir rapidamente para evitar perdas ao definir uma regra para suspender automaticamente os repasses enquanto revisa a conta. Essas análises também aparecem na fila de análises do Radar. Recomendamos que você comece levantando contas para análise e, em seguida, use repasses automáticos para suspender somente quando tiver certeza de que a regra impacta as contas conforme o esperado.

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 regras rígidas de pass pode ser excessivamente restritivo. Por exemplo, as carteiras não costumam fornecer um CVC porque armazenam dados tokenizados dos cartões. Portanto, verificações de CVC, como verificações de 3D Secure, não estão disponíveis para formas de pagamento como Apple Pay. A Stripe recomenda usar as regras integradas 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.

Os atributos booleanos são falsos em vez de ausentes quando a transação não tem o atributo. Por exemplo, :is_new_card_on_customer: é falso em vez de ausente para transações ACH e SEPA.

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.