API Reference

Configure as regras com uma linguagem simples e flexível.

As expressões são compostas por, no mínimo, uma variável, uma operação e um valor. No exemplo abaixo, a expressão será verdadeira se o ID do estabelecimento ($merchant_id) for igual ao valor "XYZ".

$merchant_id == "XYZ" 

Variáveis

Todas as variáveis devem começar com $:

VariávelConteúdoTipoExemplo
$merchant_idID do estabelecimentoTexto"loja-1234"
$user_idID do usuárioTexto"cliente-1234"
$user_profilesLista de perfis de pagamentos (cartões ou contas) usados pelo usuário. Disponível apenas para a função countColeçãoN/A
$device_ip_addressEndereço IP do dispositivo do usuárioEndereço IP"200.123.10.2"
$card_binPrimeiros 8 (ou 6¹) números do PAN que identificam o emissor do cartão (conhecido também como IIN)Texto"44332211"
$amountValor total do pagamento no formato decimalDecimal100.12
$scoreScore de risco calculado pela plataforma no formato decimal, variando entre 0.00 e 1.00Decimal0.75

¹ O BIN de 6 dígitos é suportado para manter retrocompatibilidade com as especificações antigas da ISO 7812-1, porém recomendamos que 8 dígitos sejam utilizados sempre que possível.

Estamos implementando novas variáveis conforme a necessidade dos nossos clientes. Se desejar priorizar alguma variável, entre em contato.

Operações

Em geral, as seguintes operações são possíveis entre variáveis e valores:

OperaçãoNome
==Igualdade
!=Desigualdade
>Maior que
<Menor que
>=Maior ou igual que
<=Menor ou igual que
inEstá incluído em
not inNão está incluído em

Os operadores in e not in podem ser usados com listas configuradas no painel de administração e conjuntos (arrays).

Operadores lógicos

É possível conectar mais de uma expressão com os operadores lógicos and e or. Para facilitar a organização, você também pode usar parênteses para agrupar múltiplas expressões.

Operador lógicoOperação
andE
orOu

Valores

Valores podem ser declarados explicitamente na expressão ou então podem fazer referência a listas previamente cadastradas.

Valores estáticos

Para declarar um valor estático explicitamente na regra, use aspas duplas para valores do tipo Texto e Endereço IP.

$user_id == "cliente-123" and $device_ip_address == "200.123.10.2"

Para valores numéricos, não use aspas:

$amount > 1000.0

Para declarar conjuntos estáticos (arrays), utilize colchetes em conjunto com operadores de inclusão:

$user_id in ["cliente-123", "cliente-456", "cliente-567"]

Como as expressões possuem tamanho limitado, recomendamos usar listas sempre que possível.

Listas

A principal vantagem das listas sobre o conjunto estático é que não é necessário atualizar a regra para incluir ou remover valores. Além disso, com as listas é possível incluir comentários, atribuir prazo de validade para cada registro e consultar o usuário da plataforma que fez o cadastro. Para mais informações, leia o artigo sobre listas.

Para usar listas dinâmicas na expressão, declare o nome precedido por @:

$user_id in @clientes_bloqueados

Além do operador in, também é possível usar not in para a operação reversa.

Funções

Funções são operações que podem ser realizadas utilizando variáveis. Uma função é composta pelo seu nome, seguida de parâmetros (opções) separados por vírgula entre parênteses:

nome_da_função(parâmetro_1, parâmetro_2, parâmetro_3)

O resultado de uma função pode ser usado para criar uma expressão lógica.

Contador

A função count(variável, intervalo) retorna a quantidade de registros de uma variável do tipo coleção em um intervalo de tempo passado desejado.

Por exemplo, você pode criar uma condição para bloquear usuários que utilizaram mais de 10 cartões diferentes nos últimos 7 dias:

count($user_profiles, 7d) > 10

No momento, apenas a variável $user_profiles é aceita no primeiro parâmetro desta função.

O parâmetro do intervalo pode receber qualquer quantidade de minutos (m), horas (h) ou dias(d) até o limite de 30 dias. Exemplos:

  • 15m: 15 minutos
  • 48h: 48 horas
  • 20d: 20 dias