Pular para o conteúdo principal
O TED Lerian pode pedir ao parceiro de antifraude da sua própria instituição que analise uma transferência antes de o dinheiro se mover. O parceiro responde ALLOW, REVIEW ou DENY. Cada verificação vem desligada por padrão. Você liga a verificação para a sua instituição.

As quatro verificações

Cada verificação é um fluxo. Um fluxo tem as suas próprias configurações, rota e credenciais. O TED Lerian lê as configurações quando cria uma transferência. Uma transferência criada com todos os fluxos desligados não é analisada, mesmo que você ligue um fluxo depois. O fraudCheck dela é null.

TEDs enviadas e transferências internas

O TED Lerian espera o parceiro por no máximo o syncBudgetMs da rota, que é 4000 ms ou menos. Uma TED é analisada depois que o TED Lerian reserva o valor e antes de enviar a TED ao STR. Em uma transferência interna com os dois fluxos ligados, o TED Lerian consulta primeiro o lado do pagador e depois o lado do recebedor. Ele para na primeira recusa. A resposta de criação pode retornar REJECTED ou FRAUD_ANALYSIS. Toda consulta de transferência traz fraudCheck. Ele tem decideBy e uma verificação para cada fluxo que estava ligado quando o TED Lerian criou a transferência. Cada verificação tem a decision, a sua origin (PROVIDER ou FALLBACK), a cause, o analysisId, o score, os reasons, a resolution e resolvedAt. O score e os reasons são os do parceiro, como ele os enviou. O texto de um motivo pode citar um terceiro. decideBy é o horário de criação mais a janela de revisão do fluxo, menos 2 minutos. A janela de revisão é a configuração review_window_minutes, de 10 a 30 minutos. Quando os dois fluxos internos estão ligados, vale a menor janela. Em uma TED, o fechamento da janela de funcionamento pode antecipar decideBy: ele passa a ser o fechamento menos 2 minutos. O fechamento da janela de funcionamento não vale para uma transferência interna. Com o fluxo out ligado, o TED Lerian recusa uma TED com 422 TED-0020 quando a janela de funcionamento fecha em 2 minutos e 4 segundos ou menos. O TED Lerian não reserva nada nesse caso. Se o TED Lerian não consegue ler as configurações de antifraude, ele recusa o envio com um 503 antes de reservar qualquer valor. Uma transferência em FRAUD_ANALYSIS termina de uma destas formas:
  1. O parceiro decide. O parceiro chama a operação de resolução. Em DENY, o TED Lerian rejeita a transferência com TED-0050. Em ALLOW, ele envia uma TED ao STR, ou liquida uma transferência interna quando todos os lados aprovam.
  2. Você cancela. POST /v1/transfers/{transferId}/cancel responde 200, e o TED Lerian libera a reserva e o limite de uso. Enquanto uma chamada ao Midaz ou ao Lerian SPB para a transferência está em andamento, a resposta é 409 TED-0061.
  3. decideBy passa. O TED Lerian rejeita a transferência com TED-0052, com a origem WORKER na linha do tempo, e libera a reserva e o limite de uso.
Depois de decideBy, o TED Lerian ainda aceita um DENY para uma transferência em FRAUD_ANALYSIS. Um ALLOW que chega em decideBy ou depois recebe 409 TED-0060. Um ALLOW para uma TED que chega a tempo, com a janela de funcionamento fechada, rejeita a TED com TED-0020 ou TED-0021. Se o TED Lerian não consegue ler a janela, ele responde 503 TED-0022 e não faz nenhuma mudança. TED-0050, TED-0051 e TED-0052 chegam em rejection.code de uma transferência REJECTED. Eles não são respostas de erro.

Quando o parceiro não consegue responder

Um parceiro pode estourar o tempo, recusar uma chamada ou enviar uma resposta inválida. Em out, intra_out e intra_in, a posture da rota decide então:
  • CLOSED rejeita a transferência com TED-0051.
  • OPEN deixa a transferência seguir sem análise. A verificação mostra origin FALLBACK e a cause.
posture.default define a postura. As bands opcionais a definem por valor: a primeira faixa cujo upTo é igual ou maior que o valor decide. O TED Lerian rejeita a transferência com TED-0051, seja qual for a postura, nestes casos:
  • A rota não está definida.
  • O pacote de credenciais está ausente ou não pode ser lido.
  • ANTIFRAUD_SECRETS_BACKEND está vazio.
  • O endereço é um que o TED Lerian não chama, ou o certificado TLS dele não é verificado.
Se o gerenciador de segredos não responde, a postura decide. O fluxo in não tem postura. Em uma TED recebida, uma resposta que não vem do parceiro não credita nem devolve a TED. O TED Lerian a envia para revisão manual.

TEDs recebidas

Com o fluxo in ligado, o TED Lerian não credita uma TED recebida antes de o parceiro responder. Uma TED em FRAUD_REVIEW termina de uma destas formas:
  1. O parceiro decide. O parceiro chama a operação de resolução. Em ALLOW, o TED Lerian credita a TED. Em DENY, ele devolve a TED com o motivo 9.
  2. Um operador resolve a revisão. O operador usa resolve-review, como em qualquer outra revisão manual.
  3. decideBy passa. decideBy é 15 minutos antes do prazo regulatório de 60 minutos, ou seja, 45 minutos depois da liquidação interbancária. O TED Lerian marca a revisão aberta como EXPIRED. Com antifraud.in.auto_return_enabled ligado, ele devolve a TED com o motivo 9. Com ele desligado, a TED fica com o operador.
A operação de resolução responde 409 TED-0060 nestes casos:
  • A TED não aguarda esta análise.
  • O analysisId é diferente.
  • Há outra decisão registrada.
  • decideBy passou.
  • Um DENY chega depois que o crédito da TED por um operador pode ter chegado ao ledger.
Não repita um 409. Um 503 significa que o TED Lerian não terminou. Repita com o mesmo X-Idempotency. TED-0053 significa que a decisão chegou antes de o TED Lerian registrar a análise, ou que a mesma chave ainda está em andamento. Com TED-1000 ou TED-0080, a decisão continua registrada, e a repetição a conclui.

Ligar uma verificação

Grave as configurações no namespace plugin-br-ted-lerian.policy pela API de administração do systemplane do TED Lerian, no plano /v1/system. O papel editor grava as configurações. Para cada fluxo: A rota tem estes campos:
O TED Lerian chama um endpoint, feedbackEndpoint ou tokenUrl apenas 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 TED Lerian a recusa. Veja as variáveis de ambiente. No BYOC, o TED Lerian lê um pacote de credenciais do gerenciador de segredos que ANTIFRAUD_SECRETS_BACKEND nomeia. O caminho é tenants/{ENVIRONMENT_NAME}/single-tenant/plugin-br-ted-lerian/external/antifraud-<flow>/credentials. <flow> é out, intra-out, intra-in ou in. Com vault, o caminho fica sob o mount KV v2 secret. O pacote aceita estas chaves:
  • secret: o segredo do cliente, ou o segredo HMAC em hmac-v1. É obrigatório em todos os modos de autenticação.
  • certPem e keyPem: um par de certificado de cliente opcional. Envie os dois ou nenhum.
  • header.<Name>: um header opcional que o TED Lerian envia em cada chamada.

O que o parceiro recebe

Com um fluxo ligado, o TED Lerian envia ao parceiro estes dados das duas partes:
  • O nome completo.
  • O CPF ou CNPJ.
  • O ISPB, a agência, a conta e o tipo de conta.
Ele também envia o valor e o código de finalidade.
  • TEDs enviadas e transferências internas: a descrição e o metadata da transferência. O lado do pagador também recebe clientReference.
  • TEDs recebidas: a descrição que a instituição remetente escreveu, o nuop, o número de controle do STR e o horário da liquidação.

O que o parceiro implementa

O TED Lerian envia cada avaliação como um POST de um corpo JSON ao endpoint da rota. Os headers são: Cada corpo tem transferId, flow (EXTERNAL ou INTRA), amount, currency (BRL), payer, payee e createdAt. Ele também tem purposeCode, sem zeros à esquerda, e description quando existem. ted-out.v1 soma clientReference e metadata. ted-in.v1 soma metadata em uma transferência interna, e messageCode, numCtrlStr, settledAt e nuop em uma TED recebida. Cada parte tem name, taxId, ispb, branch, account e accountType. TEDs enviadas e transferências internas também levam personType. O lado com conta na sua instituição leva accountId. O TED 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 TED 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 precisa de um analysisId, a menos que o corpo diga DENY. O TED Lerian repete um 408, 429 ou 5xx com a mesma Idempotency-Key, dentro de syncBudgetMs e maxAttempts. Ele não repete um 403. Nos modos de token, quando maxAttempts é 2 ou mais, repete um 401 uma vez, depois de obter um token novo. Qualquer status diferente de 200 ou 202, um corpo de mais de 64 KiB, ou um REVIEW sem analysisId válido não é uma decisão. O TED Lerian trata isso como uma resposta que não veio do parceiro (veja Quando o parceiro não consegue responder). O parceiro envia a decisão final de um REVIEW com estas operações. As duas exigem o papel editor. Uma aplicação com o papel operator não pode chamá-las. O corpo é analysisId, decision (ALLOW ou DENY) e reasons opcional. X-Idempotency é obrigatório, e o valor dele é <analysisId>:<decision>. Os reasons de uma resolução substituem os motivos da avaliação na verificação. O score continua. Quando a rota do fluxo out, intra_out ou intra_in tem um feedbackEndpoint, o TED Lerian informa o resultado de cada TED enviada e transferência interna analisada. Ele não envia feedback para TEDs recebidas. O corpo tem evaluationKey, analysisId, decisionOrigin (PROVIDER ou FALLBACK), outcome e occurredAt. outcome é SETTLED, REJECTED, CANCELLED, EXPIRED ou RETURNED. A Idempotency-Key é a chave da avaliação, dois-pontos e o resultado. O feedback precisa de OUTBOX_ENABLED com o valor true. Sem ele, a análise funciona e o TED Lerian não envia feedback.