Skip to main content
TED Lerian can ask your institution’s own antifraud partner to screen a transfer before money moves. The partner answers ALLOW, REVIEW or DENY. Each check is off by default. You turn it on for your institution.

The four checks

Each check is a flow. A flow has its own settings, route and credentials. TED Lerian reads the settings when it creates a transfer. A transfer created with every flow off is not screened, even if you turn a flow on later. Its fraudCheck is null.

Sent TEDs and internal transfers

TED Lerian asks the partner for at most the syncBudgetMs of the route, which is 4000 ms or less. A TED is screened after TED Lerian holds the amount and before it sends the TED to the STR. For an internal transfer with both flows on, TED Lerian asks about the payer side first, then about the payee side. It stops at the first refusal. The create response can return REJECTED or FRAUD_ANALYSIS. Every transfer read carries fraudCheck. It holds decideBy and one check for each flow that was on when TED Lerian created the transfer. Each check holds the decision, its origin (PROVIDER or FALLBACK), the cause, the analysisId, the score, the reasons, the resolution and resolvedAt. The score and the reasons are the partner’s, as it sent them. The text of a reason can name a third party. decideBy is the creation time plus the review window of the flow, less 2 minutes. The review window is the review_window_minutes setting, 10 to 30 minutes. When both internal flows are on, the shorter window applies. For a TED, the close of the operating window can set decideBy earlier: it is then the close less 2 minutes. The close of the operating window does not apply to an internal transfer. With the out flow on, TED Lerian refuses a TED with 422 TED-0020 when the operating window closes in 2 minutes and 4 seconds or less. TED Lerian holds nothing then. If TED Lerian cannot read the antifraud settings, it refuses the send with a 503 before it holds anything. A transfer in FRAUD_ANALYSIS ends in one of these ways:
  1. The partner decides. The partner calls the resolve operation. On DENY, TED Lerian rejects the transfer with TED-0050. On ALLOW, it sends a TED to the STR, or settles an internal transfer once every side allows.
  2. You cancel it. POST /v1/transfers/{transferId}/cancel answers 200, and TED Lerian releases the hold and the usage limit. While a call to Midaz or Lerian SPB for the transfer is in progress, the answer is 409 TED-0061.
  3. decideBy passes. TED Lerian rejects the transfer with TED-0052, with the timeline origin WORKER, and releases the hold and the usage limit.
After decideBy, TED Lerian still accepts a DENY for a transfer in FRAUD_ANALYSIS. An ALLOW that arrives at or after decideBy gets 409 TED-0060. An ALLOW for a TED that arrives in time, with the operating window closed, rejects the TED with TED-0020 or TED-0021. If TED Lerian cannot read the window, it answers 503 TED-0022 and makes no change. TED-0050, TED-0051 and TED-0052 arrive in rejection.code of a REJECTED transfer. They are not error responses.

When the partner cannot answer

A partner can time out, refuse a call or send an invalid answer. For out, intra_out and intra_in, the posture of the route then decides:
  • CLOSED rejects the transfer with TED-0051.
  • OPEN lets the transfer go on without screening. The check shows origin FALLBACK and the cause.
posture.default sets the posture. Optional bands set it by amount: the first band whose upTo is at or above the amount decides. TED Lerian rejects the transfer with TED-0051, whatever the posture, in these cases:
  • The route is not set.
  • The credential bundle is missing or cannot be read.
  • ANTIFRAUD_SECRETS_BACKEND is empty.
  • The address is one that TED Lerian does not call, or its TLS certificate does not verify.
If the secret manager does not answer, the posture decides. The in flow takes no posture. For a received TED, an answer that does not come from the partner does not credit or return the TED. TED Lerian sends it to manual review.

Received TEDs

With the in flow on, TED Lerian does not credit a received TED before the partner answers. A TED in FRAUD_REVIEW ends in one of these ways:
  1. The partner decides. The partner calls the resolve operation. On ALLOW, TED Lerian credits the TED. On DENY, it returns the TED with reason 9.
  2. An operator resolves the review. The operator uses resolve-review, as for any other manual review.
  3. decideBy passes. decideBy is 15 minutes before the 60 minute regulatory deadline, that is 45 minutes after interbank settlement. TED Lerian marks the open review EXPIRED. With antifraud.in.auto_return_enabled on, it returns the TED with reason 9. With it off, the TED stays with the operator.
The resolve operation answers 409 TED-0060 in these cases:
  • The TED does not wait for this analysis.
  • The analysisId differs.
  • Another decision is on record.
  • decideBy has passed.
  • A DENY arrives after an operator’s credit of the TED may have reached the ledger.
Do not repeat a 409. A 503 means TED Lerian did not finish. Repeat it with the same X-Idempotency. TED-0053 means the decision arrived before TED Lerian recorded the analysis, or the same key is still in progress. With TED-1000 or TED-0080, the decision stays on record, and the repeat finishes it.

Turn a check on

Write the settings in the plugin-br-ted-lerian.policy namespace through the systemplane admin API of TED Lerian, on the /v1/system plane. The editor role writes them. For each flow: The route holds these fields:
TED Lerian calls an endpoint, feedbackEndpoint or tokenUrl only when it is https on a public address, unless its host is in ANTIFRAUD_ALLOWED_PRIVATE_HOSTS. When you write a route that does not meet this rule, TED Lerian refuses it. See the environment variables. In BYOC, TED Lerian reads a credential bundle from the secret manager that ANTIFRAUD_SECRETS_BACKEND names. The path is tenants/{ENVIRONMENT_NAME}/single-tenant/plugin-br-ted-lerian/external/antifraud-<flow>/credentials. <flow> is out, intra-out, intra-in or in. With vault, the path sits under the KV v2 mount secret. The bundle accepts these keys:
  • secret: the client secret, or the HMAC secret for hmac-v1. It is required for every auth mode.
  • certPem and keyPem: an optional client certificate pair. Send both or neither.
  • header.<Name>: an optional header that TED Lerian sends on each call.

What the partner receives

With a flow on, TED Lerian sends the partner these data of both parties:
  • The full name.
  • The CPF or CNPJ.
  • The ISPB, the branch, the account and the account type.
It also sends the amount and the purpose code.
  • Sent TEDs and internal transfers: the description and the metadata of the transfer. The payer side also gets clientReference.
  • Received TEDs: the description that the sending institution wrote, the nuop, the STR control number and the settlement time.

What the partner implements

TED Lerian sends each evaluation as a POST of a JSON body to the endpoint of the route. The headers are: Each body has transferId, flow (EXTERNAL or INTRA), amount, currency (BRL), payer, payee and createdAt. It also has purposeCode, without leading zeros, and description when they exist. ted-out.v1 adds clientReference and metadata. ted-in.v1 adds metadata on an internal transfer, and messageCode, numCtrlStr, settledAt and nuop on a received TED. Each party has name, taxId, ispb, branch, account and accountType. Sent TEDs and internal transfers also carry personType. The side with an account at your institution carries accountId. TED Lerian signs each call with the auth.mode of the route:
  • hmac-v1: X-Webhook-Timestamp has the Unix time in seconds. X-Webhook-Signature is v1,sha256= followed by the hex HMAC-SHA256 of v1:<timestamp>.<raw body> with the secret.
  • lerian-m2m and oauth2-client-credentials: TED Lerian gets a token from auth.tokenUrl with the clientId and the secret. It sends the token as a bearer token.
The partner answers 200 with a JSON body: A 202 counts as REVIEW, and it needs an analysisId, unless the body says DENY. TED Lerian repeats a 408, 429 or 5xx with the same Idempotency-Key, within syncBudgetMs and maxAttempts. It does not repeat a 403. In the token modes, when maxAttempts is 2 or more, it repeats a 401 once, after it gets a new token. Any status other than 200 or 202, a body of more than 64 KiB, or a REVIEW with no valid analysisId is not a decision. TED Lerian handles it as an answer that did not come from the partner (see When the partner cannot answer). The partner sends the final decision of a REVIEW with these operations. Both need the editor role. An application with the operator role cannot call them. The body is analysisId, decision (ALLOW or DENY) and optional reasons. X-Idempotency is required, and its value is <analysisId>:<decision>. The reasons of a resolution replace the reasons of the evaluation on the check. The score stays. When the route of the out, intra_out or intra_in flow has a feedbackEndpoint, TED Lerian reports the outcome of each screened sent TED and internal transfer. It sends no feedback for received TEDs. The body has evaluationKey, analysisId, decisionOrigin (PROVIDER or FALLBACK), outcome and occurredAt. outcome is SETTLED, REJECTED, CANCELLED, EXPIRED or RETURNED. The Idempotency-Key is the evaluation key, a colon and the outcome. The feedback needs OUTBOX_ENABLED set to true. Without it, the screening works and TED Lerian sends no feedback.