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
postureda 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_BACKENDvazio, um segredohmac-v1com menos de 32 caracteres e um endereço que o Pix Lerian não chama.
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 respondeREVIEW espera em FRAUD_ANALYSIS somente quando todas estas condições valem:
ANTIFRAUD_OUT_REVIEW_ALLOWEDétrueno SPI. O padrão éfalse.- O
review_window_minutesdo fluxo é maior que0. - O Pix não é um Saque nem um Troco.
- O prazo
decideByainda está à frente.
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:
- O pagador a cancela.
POST /spi/v1/transfers/{id}/cancelrecebeX-Account-IdeX-Idempotency, e não tem corpo. Responde200com a transferênciaREJECTEDe o estorno feito.fraudCheck.resolutionéCANCELLED. Responde409comPIX-0339quando o Pix não está retido, e404comPIX-0340para outra conta. - O parceiro decide. O parceiro chama
POST /spi/v1/transfers/{id}/fraud-decisioncomanalysisIdedecision(ALLOWouDENY), por meio de uma aplicação da sua instituição que tem a permissão abaixo. - O back office decide. Uma pessoa da sua instituição chama a mesma rota e acrescenta uma
justificationde 10 a 500 caracteres. decideBypassa. O Pix Lerian estorna o débito e encerra a transferência comoREJECTED, comfraudCheck.resolutionEXPIRED.
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 umfeedbackEndpoint, 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:
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 parahmac-v1. É obrigatório em todo modo de autenticação. Um segredohmac-v1tem pelo menos 32 caracteres.certPemekeyPem: 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-Timestamptem o horário Unix em segundos.X-Webhook-Signatureév1,sha256=seguido do HMAC-SHA256 em hexadecimal dev1:<timestamp>.<raw body>com osecret.lerian-m2meoauth2-client-credentials: o Pix Lerian obtém um token emauth.tokenUrlcom oclientIde osecret. Ele envia o token como bearer token.
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.
