Pular para o conteúdo principal
O Pix Lerian pode pedir ao parceiro antifraude da sua própria instituição que verifique um Pix antes de o Pix Lerian enviá-lo ao trilho ou creditá-lo. O parceiro responde ALLOW, REVIEW ou DENY. Cada verificação vem desligada. Você a liga para a sua instituição.

As quatro verificações


Cada verificação é um fluxo. Um fluxo tem as próprias configurações, rota e credenciais. Com intra_out e intra_in ligados, o parceiro verifica o mesmo Pix duas vezes. Um Pix Agendado que a sua instituição envia e uma liquidação do Pix Automático não são verificados. Uma devolução recebida não é verificada.

Pix enviado


Com o fluxo out ou intra_out ligado, o Pix Lerian debita a conta, consulta o parceiro e só então envia o Pix ao trilho. O parceiro tem no máximo o syncBudgetMs da rota, que é de 1500 ms ou menos. O Pix Lerian também estorna o débito e responde 422 com PIX-0337 nestes casos:
  • O parceiro não dá uma decisão válida, e a posture da rota é CLOSED.
  • A configuração do fluxo está quebrada, em qualquer posture. Exemplos são uma rota ausente, um pacote de credenciais ausente, um ANTIFRAUD_SECRETS_BACKEND vazio, um segredo hmac-v1 com menos de 32 caracteres e um endereço que o Pix Lerian não chama.
Quando o parceiro não dá uma decisão válida e a posture é OPEN, o Pix Lerian envia o Pix sem verificação. A verificação mostra origin FALLBACK e a cause. Se o Pix Lerian não consegue provar que estornou o débito, a chamada responde 500 com PIX-0000. Leia a transferência antes de agir. Uma nova tentativa é uma nova iniciação, não uma repetição da mesma chamada. Toda leitura de uma transferência verificada traz fraudCheck. Ele guarda a decision, a sua origin (PROVIDER ou FALLBACK), a cause, o analysisId, o score e os reasons. O score e os reasons são do parceiro, como ele os enviou. O texto de um motivo pode citar um terceiro. Os eventos outbound_transfer.completed e outbound_transfer.rejected também carregam fraudCheck.

Reter um Pix enviado para análise

Um Pix enviado a que o parceiro responde REVIEW espera em FRAUD_ANALYSIS somente quando todas estas condições valem:
  • ANTIFRAUD_OUT_REVIEW_ALLOWED é true no SPI. O padrão é false.
  • O review_window_minutes do fluxo é maior que 0.
  • O Pix não é um Saque nem um Troco.
  • O prazo decideBy ainda está à frente.
A chamada responde 201. O débito e o uso do limite permanecem, e o Pix Lerian não envia nada. O evento outbound_transfer.fraud_analysis anuncia a retenção, e GET /transfers aceita status=fraud_analysis. decideBy é o menor de dois tempos, menos 3 minutos. O primeiro é o tempo manual do Pix: 30 minutos das 08:00 às 20:00 em um dia útil, e 60 minutos em qualquer outro horário, no horário de America/Sao_Paulo. O segundo é a janela de análise do fluxo. fraudCheck.decideBy o mostra. Uma transferência em FRAUD_ANALYSIS termina de uma destas formas:
  1. O pagador a cancela. POST /spi/v1/transfers/{id}/cancel recebe X-Account-Id e X-Idempotency, e não tem corpo. Responde 200 com a transferência REJECTED e o estorno feito. fraudCheck.resolution é CANCELLED. Responde 409 com PIX-0339 quando o Pix não está retido, e 404 com PIX-0340 para outra conta.
  2. O parceiro decide. O parceiro chama POST /spi/v1/transfers/{id}/fraud-decision com analysisId e decision (ALLOW ou DENY), por meio de uma aplicação da sua instituição que tem a permissão abaixo.
  3. O back office decide. Uma pessoa da sua instituição chama a mesma rota e acrescenta uma justification de 10 a 500 caracteres.
  4. decideBy passa. O Pix Lerian estorna o débito e encerra a transferência como REJECTED, com fraudCheck.resolution EXPIRED.
Por pouco tempo depois de um cancelamento ou de uma decisão, uma leitura pode mostrar a transferência como PENDING com uma resolution. Em ALLOW, a rota envia o Pix e responde 200 com a transferência em PROCESSING. Em DENY, ela estorna o débito e responde 200 com a transferência REJECTED. O registro mostra quem decidiu: resolutionOrigin é PARTNER ou OPERATOR, e resolvedBy é o subject do token. O Pix Lerian nunca publica a justification. A rota exige a permissão transfer-fraud-decision com a ação post. Ela é de nível de tenant, e os papéis editor e contributor a têm. No BYOC, só a declaração de permissões do SPI a concede: veja Permissões que só a declaração do SPI concede. O cancelamento exige a permissão transfers com a ação post para a conta.

O resultado de cada Pix enviado

Quando a rota de um fluxo de envio tem um feedbackEndpoint, o Pix Lerian informa como cada Pix verificado terminou. Ele envia o relatório por até 24 horas depois de o Pix terminar. O corpo tem evaluationKey (o id da transferência), analysisId, decisionOrigin (PROVIDER ou FALLBACK), outcome e occurredAt. outcome é SETTLED, CANCELLED, EXPIRED ou REJECTED. O Idempotency-Key é o id da transferência, dois-pontos e o resultado. O parceiro deve aplicar cada resultado uma vez.

Pix recebido


Com o fluxo in ou intra_in ligado, o Pix Lerian consulta o parceiro antes de aprovar um Pix recebido. O parceiro tem no máximo o syncBudgetMs da rota, que é de 1000 ms ou menos. O Pix Lerian confere a conta de destino primeiro. Um Pix que a conferência da conta recusa não chega ao parceiro. Uma configuração quebrada recusa o Pix com DS04, em qualquer posture. As causas são as mesmas de um Pix enviado. A resposta do parceiro é guardada como fraudCheck na transferência, e os eventos inbound_transfer.completed e inbound_transfer.credit_parked a carregam. O evento inbound_transfer.denied anuncia cada Pix recebido que o Pix Lerian recusou na aprovação. Nenhuma transferência existe para ele. Veja Eventos.

Ligar uma verificação


Grave as configurações na configuração de runtime do SPI, namespace spi, com a API de administração do Systemplane. O papel admin do SPI as grava. Para cada fluxo: A rota tem estes campos:
No BYOC, o Pix Lerian chama um endpoint, feedbackEndpoint ou tokenUrl somente quando ele é https em um endereço público, a menos que o host dele esteja em ANTIFRAUD_ALLOWED_PRIVATE_HOSTS. Quando você grava uma rota que não cumpre essa regra, o Pix Lerian a recusa. Veja as variáveis de ambiente. No BYOC, o Pix Lerian lê um pacote de credenciais do gerenciador de segredos que ANTIFRAUD_SECRETS_BACKEND nomeia. O caminho é tenants/{env}/single-tenant/plugin-br-pix-lerian-spi/external/antifraud-<flow>/credentials. {env} é o valor de ENV_NAME, em minúsculas e sem espaços. <flow> é out, intra-out, intra-in ou in. O pacote aceita estas chaves:
  • secret: o segredo do cliente, ou o segredo HMAC para hmac-v1. É obrigatório em todo modo de autenticação. Um segredo hmac-v1 tem pelo menos 32 caracteres.
  • certPem e keyPem: um par opcional de certificado de cliente. Envie os dois ou nenhum.
  • header.<Name>: um header opcional que o Pix Lerian envia em cada chamada.

O que o parceiro recebe


Com um fluxo ligado, o Pix Lerian envia ao parceiro estes dados das duas partes: o nome completo, o CPF ou CNPJ, o tipo de pessoa, o ISPB, a agência, a conta e o tipo de conta. Também envia o valor, o endToEndId, a descrição e a chave Pix do recebedor. Um Pix enviado também carrega o metadata que o chamador enviou a Processar transferência. O Pix Lerian o repassa sem lê-lo.

O que o parceiro implementa


O Pix Lerian envia cada avaliação como um POST de um corpo JSON ao endpoint da rota. Os headers são: O corpo de um Pix enviado tem transferId, endToEndId, flow (EXTERNAL ou INTRA), initiationType, transactionType, amount, currency (BRL), description, txId, payer, payee, createdAt e metadata. O corpo de um Pix recebido tem endToEndId, flow, initiationType, amount, currency, description, txId, payer e payee. Cada parte tem name, taxId, personType, ispb, branch, account, accountType e key. O pagador de um Pix enviado e o recebedor de um Pix recebido carregam accountId. O Pix Lerian assina cada chamada com o auth.mode da rota:
  • hmac-v1: X-Webhook-Timestamp tem o horário Unix em segundos. X-Webhook-Signature é v1,sha256= seguido do HMAC-SHA256 em hexadecimal de v1:<timestamp>.<raw body> com o secret.
  • lerian-m2m e oauth2-client-credentials: o Pix Lerian obtém um token em auth.tokenUrl com o clientId e o secret. Ele envia o token como bearer token.
O parceiro responde 200 com um corpo JSON: Um 202 conta como REVIEW e exige um analysisId, a menos que o corpo diga DENY. Qualquer status diferente de 200 ou 202, ou um REVIEW sem analysisId válido, não é uma decisão. O Pix Lerian então aplica a posture da rota.