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
A ação tomada por uma regra determina a ordem em que ela é processada. O Radar avalia cada pagamento em relação às regras criadas na seguinte ordem de prioridade:
- 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.
- 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.
- Bloquear: regras que bloqueiam e recusam um pagamento. Os pagamentos bloqueados não são avaliados por nenhuma regra de análise.
- Analisar: regras que permitem o processamento de pagamentos, mas os enviam para análise.
Se um pagamento cumpre os critérios de uma regra, o Radar executa a ação adequada e encerra a avaliação do pagamento. Se um pagamento cumpre uma regra de permissão, é processado normalmente e nenhuma regra de bloqueio ou análise é avaliada, mesmo que o pagamento cumpra seus critérios. Este é um exemplo de conjunto de regras:
- 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
Usando as regras acima, todos os pagamentos abaixo de 10 USD são processados, independentemente do nível de risco ou do local de emissão do cartão. O motivo é que a primeira regra permite o pagamento, portanto, nenhuma outra regra é avaliada. Da mesma forma, um pagamento de 1.500 USD realizado nos EUA com um nível de risco normal também é permitido, apesar da regra de bloquear pagamentos acima de 1.000 USD. Isso ocorre devido à segunda regra da lista, que permite pagamentos realizados nos EUA com nível de risco normal. Quando uma determinada regra é acionada, nenhuma outra regra é avaliada.
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
Quando um pagamento cumpre os critérios de uma regra, ela pode executar uma das quatro ações abaixo, processadas nesta ordem:
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 da avaliação da Stripe ou de qualquer outra regra cujos critérios também são cumpridos pelo pagamento. Pagamentos que cumprem os critérios de uma regra de permissão são processados normalmente pela Stripe e não são mais avaliados por nenhuma regra. Mesmo que a Stripe prossiga com o pagamento, ele poderá ser recusado pelo emissor do cartão.
Bloquear
As regras de bloqueio especificam que a Stripe deve 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.
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
oudebit
)
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 certos atributos como um valor correspondente em uma condição. Por exemplo, para criar uma regra para bloquear pagamentos quando o país emissor do cartão não corresponde ao país de onde o pagamento foi feito, use este atributo e valor:
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_value]
:: [operator]
Por exemplo, vamos supor que temos pagamentos com os seguintes dados chave-valor armazenados no campo de metadados:
Nome dos metadados | Valor dos metadados |
---|---|
Idade do cliente | 22 |
ID do item | 5A381D |
ID da categoria | mantimentos |
Você pode criar uma regra que envia para análise os pagamentos que cumprem os critérios especificados.
Review if < 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 =
'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 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 INCLUDES
'A381'
Cuidado
Quando usados como strings, os atributos de metadados diferenciam maiúsculas e minúsculas. Verifique se os valores de metadados especificados são idênticos aos especificados nos pagamentos.
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_value]
:: [operator]
Por exemplo, vamos supor que você tem um cliente com estes metadados:
Nome dos metadados | Valor dos metadados |
---|---|
Confiável | verdadeiro |
É possível criar uma regra que permite pagamentos em que o campo Trusted
dos metadados do cliente é true
.
Allow if =
'true'
No caso de um destino com os seguintes metadados:
Nome dos metadados | Valor dos metadados |
---|---|
Categoria | novo |
É possível criar uma regra que envia para análise os pagamentos em que o campo Category
dos metadados é new
.
Review if =
'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, sua regra deve comparar 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:
Valor do atributo | Explicação |
---|---|
pass | Os dados informados estão corretos. |
fail | Os dados informados estão incorretos. |
unavailable | O emissor do cartão do cliente não verifica os dados informados. Nem todos os emissores ou países do cartão aceitam a verificação de endereço. |
unchecked | Os dados foram informados, mas ainda não foram verificados. Esses dados serão verificados mais tarde pelo emissor do cartão do cliente. |
not_provided | Os dados não foram informados à Stripe. |
Alguns exemplos de regras:
Block if :address_line1_check: =
'fail'
Block if :cvc_check: !=
'pass'
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 regras incluem a frase “considerados pagamentos de 2020 em diante”. Isso significa que a regra trataria um cartão cuja última transação foi em 2019 como o mesmo que um cartão que é novo para a sua empresa. Considere cuidadosamente o que isso significa no contexto do seu negócio e regras, pois pode resultar em um comportamento contraintuitivo. Por exemplo, se você criar uma regra para bloquear pagamentos de valor elevado de cartões novos, pode acabar bloqueando um bom cliente que não fazia 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.
Operador | String | Metadados | País | Estado | Numérico | Descrição | Exemplo |
---|---|---|---|---|---|---|---|
= | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | Igual a | :card_country: = |
!= | ✔︎ | ✔︎ | ✔︎ | ✔︎ | ✔︎ | Diferente de | :card_funding: != |
< | ✔︎ | Menor que | :amount_in_gbp: < 10.00 | ||||
> | ✔︎ | Maior que | :amount_in_usd: > 500.00 | ||||
<= | ︎ | ✔︎ | Menor que ou igual a | :amount_in_eur: <= 100.00 | |||
>= | ✔︎ | Maior que ou igual a | :amount_in_cad: >= 10.00 | ||||
IN | ✔ | ✔︎ | ✔ | ✔︎ | ✔︎ | Está no grupo | :card_country: IN ( |
INCLUDES | ✔ | ✔︎ | ✔ | ✔ | Contém a string | :ip_address: INCLUDES | |
LIKE | ✔ | ✔︎ | ✔ | ✔ | Procura correspondências com o padrão informado. Use o caractere de curinga % para corresponder zero ou mais ocorrências de letras, dígitos ou símbolos. | :email: LIKE |
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.
Cuidado
Membros da UE devem estar cientes do Regulamento de Bloqueio Geográfico e suas proibições de bloqueio de pagamentos de clientes localizados em estados-membros da UE. Saiba mais sobre esse regulamento.
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: =
. Se você não coletou o e-mail do cliente, o atributo 'definitelyfraud.com'
:email_domain:
não será encontrado e, portanto, a condição da regra não corresponderá ao pagamento.
Considere a regra Review if :email_domain: !=
. Se o atributo 'definitelysafe.com'
:email_domain:
não for encontrado, a regra também não corresponderá ao pagamento. Isso pode parecer um pouco inesperado, pois um valor não encontrado é diferente de
. Nesse caso, 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.'definitelysafe.com'
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.
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( ))
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: <
(valores do tipo string só podem usar operadores = ou !=)'highest'
:ip_country: =
(valores de país devem ser especificados com o código abreviado de duas letras)'Canada'
:amount_in_usd: >=
(valores numéricos devem ser especificados com números)'one thousand dollars'
:is_anonymous_ip: =
(valores booleanos não são usados com operadores ou valores)'true'
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.
Os atributos são calculados como uma janela contínua, com base em segundos fixos e não em um calendário. Por exemplo, daily
significa que o tempo entre duas cobranças em um atributo de regra deve ser de no máximo 24 horas ou 86400 segundos de intervalo para corresponder.
Os atributos são definidos como:
hourly
é 3600 segundosdaily
é 86400 segundosweekly
é 604800 segundosyearly
é 31536000 segundos
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.