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.
With
intra_out and intra_in both on, the partner screens the same Pix twice. A Pix Agendado that your institution sends and a Pix Automático settlement are not screened. A received return is not screened.
Sent Pix
With the
out or intra_out flow on, Pix Lerian debits the account, then asks the partner, and only then sends the Pix to the rail. The partner has at most the syncBudgetMs of the route, which is 1500 ms or less.
Pix Lerian also reverses the debit and answers
422 with PIX-0337 in these cases:
- The partner gives no valid decision, and the
postureof the route isCLOSED. - The configuration of the flow is broken, under any posture. Examples are a missing route, a missing credential bundle, an empty
ANTIFRAUD_SECRETS_BACKEND, anhmac-v1secret with fewer than 32 characters, and an address that Pix Lerian does not call.
OPEN, Pix Lerian sends the Pix without screening. The check shows origin FALLBACK and the cause.
If Pix Lerian cannot prove that it reversed the debit, the call answers 500 with PIX-0000. Read the transfer before you act. A retry is a new initiation, not a repeat of the same call.
Every read of a screened transfer carries fraudCheck. It holds the decision, its origin (PROVIDER or FALLBACK), the cause, the analysisId, the score and the reasons. The score and the reasons are the partner’s, as it sent them. The text of a reason can name a third party. The events outbound_transfer.completed and outbound_transfer.rejected carry fraudCheck too.
Hold a sent Pix for review
A sent Pix that the partner answersREVIEW waits in FRAUD_ANALYSIS only when all of these hold:
ANTIFRAUD_OUT_REVIEW_ALLOWEDistrueon the SPI. The default isfalse.- The
review_window_minutesof the flow is above0. - The Pix is not a Saque or a Troco.
- The deadline
decideByis still ahead.
201. The debit and the usage limit stay, and Pix Lerian sends nothing. The event outbound_transfer.fraud_analysis announces the hold, and GET /transfers accepts status=fraud_analysis.
decideBy is the shorter of two times, less 3 minutes. The first is the Pix manual time: 30 minutes from 08:00 to 20:00 on a business day, and 60 minutes at any other time, in America/Sao_Paulo. The second is the review window of the flow. fraudCheck.decideBy shows it.
A transfer in FRAUD_ANALYSIS ends in one of these ways:
- The payer cancels it.
POST /spi/v1/transfers/{id}/canceltakesX-Account-IdandX-Idempotency, and has no body. It answers200with the transferREJECTEDand the reversal done.fraudCheck.resolutionisCANCELLED. It answers409withPIX-0339when the Pix is not held, and404withPIX-0340for another account. - The partner decides. The partner calls
POST /spi/v1/transfers/{id}/fraud-decisionwithanalysisIdanddecision(ALLOWorDENY), through an application of your institution that holds the permission below. - Your back office decides. A person of your institution calls the same route, and adds a
justificationof 10 to 500 characters. decideBypasses. Pix Lerian reverses the debit and closes the transferREJECTED, withfraudCheck.resolutionEXPIRED.
PENDING with a resolution.
On ALLOW, the route sends the Pix and answers 200 with the transfer in PROCESSING. On DENY, it reverses the debit and answers 200 with the transfer REJECTED. The record shows who decided: resolutionOrigin is PARTNER or OPERATOR, and resolvedBy is the subject of the token. Pix Lerian never publishes the justification.
The route needs the
transfer-fraud-decision permission with the action post. It is tenant level, and the editor and contributor roles hold it. In BYOC, only the SPI permission declaration grants it: see Permissions that only the SPI declaration grants. The cancel needs the transfers permission with the action post for the account.
The outcome of each sent Pix
When the route of a sent flow has afeedbackEndpoint, Pix Lerian reports how each screened Pix ended. It sends the report for up to 24 hours after the Pix ended. The body has evaluationKey (the transfer id), analysisId, decisionOrigin (PROVIDER or FALLBACK), outcome and occurredAt. outcome is SETTLED, CANCELLED, EXPIRED or REJECTED. The Idempotency-Key is the transfer id, a colon and the outcome. The partner must apply each outcome once.
Received Pix
With the
in or intra_in flow on, Pix Lerian asks the partner before it approves a received Pix. The partner has at most the syncBudgetMs of the route, which is 1000 ms or less.
Pix Lerian checks the destination account first. A Pix that the account check refuses does not reach the partner.
A broken configuration refuses the Pix with
DS04, under any posture. The causes are the same as for a sent Pix.
The partner’s answer is stored as fraudCheck on the transfer, and the events inbound_transfer.completed and inbound_transfer.credit_parked carry it. The event inbound_transfer.denied announces each received Pix that Pix Lerian refused at approval. No transfer exists for it. See Events.
Turn a check on
Write the settings in the SPI runtime configuration, namespace
spi, with the Systemplane admin API. The admin role of the SPI writes them. For each flow:
The route holds these fields:
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, Pix Lerian refuses it. See the environment variables.
In BYOC, Pix Lerian reads a credential bundle from the secret manager that ANTIFRAUD_SECRETS_BACKEND names. The path is tenants/{env}/single-tenant/plugin-br-pix-lerian-spi/external/antifraud-<flow>/credentials. {env} is the value of ENV_NAME, in lower case and with no spaces. <flow> is out, intra-out, intra-in or in. The bundle accepts these keys:
secret: the client secret, or the HMAC secret forhmac-v1. It is required for every auth mode. Anhmac-v1secret has at least 32 characters.certPemandkeyPem: an optional client certificate pair. Send both or neither.header.<Name>: an optional header that Pix Lerian sends on each call.
What the partner receives
With a flow on, Pix Lerian sends the partner these data of both parties: the full name, the CPF or CNPJ, the person type, the ISPB, the branch, the account and the account type. It also sends the amount, the
endToEndId, the description and the payee’s Pix key. A sent Pix also carries the metadata that the caller sent to Process transfer. Pix Lerian passes it on without reading it.
What the partner implements
Pix Lerian sends each evaluation as a
POST of a JSON body to the endpoint of the route. The headers are:
A sent Pix body has
transferId, endToEndId, flow (EXTERNAL or INTRA), initiationType, transactionType, amount, currency (BRL), description, txId, payer, payee, createdAt and metadata. A received Pix body has endToEndId, flow, initiationType, amount, currency, description, txId, payer and payee. Each party has name, taxId, personType, ispb, branch, account, accountType and key. The payer of a sent Pix and the payee of a received Pix carry accountId.
Pix Lerian signs each call with the auth.mode of the route:
hmac-v1:X-Webhook-Timestamphas the Unix time in seconds.X-Webhook-Signatureisv1,sha256=followed by the hex HMAC-SHA256 ofv1:<timestamp>.<raw body>with thesecret.lerian-m2mandoauth2-client-credentials: Pix Lerian gets a token fromauth.tokenUrlwith theclientIdand thesecret. It sends the token as a bearer token.
200 with a JSON body:
A
202 counts as REVIEW, and it needs an analysisId, unless the body says DENY. Any status other than 200 or 202, or a REVIEW with no valid analysisId, is not a decision. Pix Lerian then applies the posture of the route.
