> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Pix Lerian antifraud partner check

> How Pix Lerian asks your institution's antifraud partner to screen sent and received Pix, how you turn each check on, and what the partner must implement.

Pix Lerian can ask your institution's own antifraud partner to screen a Pix before Pix Lerian sends it to the rail or credits it. 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.

| Flow | What the partner screens |
| - | - |
| `out` | A Pix that your institution sends to a payee at another institution. |
| `intra_out` | A Pix that your institution sends to a payee at the same ISPB. |
| `in` | A Pix that your institution receives from a payer at another institution. |
| `intra_in` | A Pix that your institution receives from a payer at the same ISPB. |

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.

| Answer | Result |
| - | - |
| `ALLOW` | Pix Lerian sends the Pix. |
| `DENY` | Pix Lerian reverses the debit and records the transfer as `REJECTED`. [Process transfer](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/process-transfer.md) answers `422` with `PIX-0336`. |
| `REVIEW` | The Pix waits in `FRAUD_ANALYSIS` when it can be held (see below). Otherwise Pix Lerian reverses the debit and the call answers `422` with `PIX-0338`. |

Pix Lerian also reverses the debit and answers `422` with `PIX-0337` in these cases:

* The partner gives no valid decision, and the `posture` of the route is `CLOSED`.
* The configuration of the flow is broken, under any posture. Examples are a missing route, a missing credential bundle, an empty `ANTIFRAUD_SECRETS_BACKEND`, an `hmac-v1` secret with fewer than 32 characters, and an address that Pix Lerian does not call.

When the partner gives no valid decision and the posture is `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 answers `REVIEW` waits in `FRAUD_ANALYSIS` only when all of these hold:

* `ANTIFRAUD_OUT_REVIEW_ALLOWED` is `true` on the SPI. The default is `false`.
* The `review_window_minutes` of the flow is above `0`.
* The Pix is not a Saque or a Troco.
* The deadline `decideBy` is still ahead.

The call answers `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:

1. **The payer cancels it.** [`POST /spi/v1/transfers/{id}/cancel`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/cancel-a-sent-pix-held-in-fraud-analysis) takes `X-Account-Id` and `X-Idempotency`, and has no body. It answers `200` with the transfer `REJECTED` and the reversal done. `fraudCheck.resolution` is `CANCELLED`. It answers `409` with `PIX-0339` when the Pix is not held, and `404` with `PIX-0340` for another account.
2. **The partner decides.** The partner calls [`POST /spi/v1/transfers/{id}/fraud-decision`](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/decide-a-sent-pix-held-in-fraud-analysis) with `analysisId` and `decision` (`ALLOW` or `DENY`), through an application of your institution that holds the permission below.
3. **Your back office decides.** A person of your institution calls the same route, and adds a `justification` of 10 to 500 characters.
4. **`decideBy` passes.** Pix Lerian reverses the debit and closes the transfer `REJECTED`, with `fraudCheck.resolution` `EXPIRED`.

For a short time after a cancel or a decision, a read can show the transfer as `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`.

| Status and code | Meaning |
| - | - |
| `409` `PIX-0339` | The transfer is not held, another decision, a cancel or the deadline ended the analysis first, or the call names another `analysisId`. |
| `409` `PIX-0344` | An `ALLOW` that arrives after `decideBy`. A `DENY` still works. |
| `422` `PIX-0343` | The body is not valid, or a person sent no `justification`. |
| `503` `PIX-0345` | Pix Lerian is recording the hold. Retry after the `Retry-After` time. |

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](https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-spi.md#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 a `feedbackEndpoint`, 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.

| Answer | Result |
| - | - |
| `ALLOW` | Pix Lerian approves the Pix and credits the account. |
| `DENY` or `REVIEW` | Pix Lerian refuses the Pix with the reason code `FRAD`, and the operation reports `PIX-0456`. Nothing is credited. |
| `DENY` or `REVIEW` with the partner reason `AG01` | Pix Lerian refuses the Pix with the reason code `AG01`, and the operation reports `PIX-0458`. |
| No valid answer, posture `OPEN` | Pix Lerian approves the Pix without screening. |
| No valid answer, posture `CLOSED` | Pix Lerian refuses the Pix with the reason code `DS04`, and the operation reports `PIX-0457`. |

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](https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-events.md).

## Turn a check on

***

Write the settings in the SPI runtime configuration, namespace `spi`, with the [Systemplane](https://docs.lerian.studio/en/reference/platform/systemplane/overview.md) admin API. The `admin` role of the SPI writes them. For each flow:

| Key | Meaning |
| - | - |
| `antifraud.<flow>.enabled` | Turns the check on. The default is off. |
| `antifraud.<flow>.route` | The partner route, as one JSON object. `{}` means not set. Pix Lerian checks the route when you write it. |
| `antifraud.<flow>.review_window_minutes` | Only for `out` and `intra_out`. How long the partner has to decide a `REVIEW`, in minutes, from 0 to 60. The default is 0, which holds nothing. |

The route holds these fields:

| Field | Meaning |
| - | - |
| `endpoint` | The address that receives the evaluation. |
| `feedbackEndpoint` | Optional. Only for `out` and `intra_out`. The address that receives the outcome of each screened sent Pix. |
| `auth` | `mode` (`hmac-v1`, `lerian-m2m` or `oauth2-client-credentials`). The two token modes also need `tokenUrl` and `clientId`. `oauth2-client-credentials` accepts `scopes`. Optional `staticHeaders` apply to every mode. |
| `syncBudgetMs` | The longest wait for one evaluation, retries included. From 100 to 1500 for `out` and `intra_out`. From 100 to 1000 for `in` and `intra_in`. |
| `attemptTimeoutMs` | The time limit of one attempt. It cannot be more than `syncBudgetMs`. |
| `maxAttempts` | The number of attempts, 1 or more. For `in` and `intra_in`, it must be exactly 1. |
| `posture` | `default` (`OPEN` or `CLOSED`) is required, and `bands` are optional. |

```json theme={null}
{
  "endpoint": "https://antifraud.example.com/evaluate",
  "auth": { "mode": "hmac-v1" },
  "syncBudgetMs": 800,
  "attemptTimeoutMs": 800,
  "maxAttempts": 1,
  "posture": { "default": "CLOSED" }
}
```

In BYOC, Pix 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, Pix Lerian refuses it. See the [environment variables](https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-environment-variables.md#antifraud-partner).

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 for `hmac-v1`. It is required for every auth mode. An `hmac-v1` secret has at least 32 characters.
* `certPem` and `keyPem`: 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](https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/process-transfer.md). 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:

| Header | Value |
| - | - |
| `Idempotency-Key` | The key of the evaluation. For a sent Pix, the transfer id. For a received Pix, `pix-cashin:` and the `endToEndId`. The same key returns the same analysis. |
| `X-Lerian-Decide-By` | The deadline of the decision, in RFC 3339 UTC. |
| `X-Lerian-Payload-Schema` | `pix-out.v1` for a sent Pix. `pix-cashin.v1` for a received Pix. |

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-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`: Pix 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:

| Field | Meaning |
| - | - |
| `decision` | `ALLOW`, `REVIEW` or `DENY`, in upper case. |
| `analysisId` | 1 to 64 printable ASCII characters, with no space. Required with `REVIEW`. |
| `score`, `reasons` | Optional. Pix Lerian does not decide by them. The reason `AG01` refuses a received Pix with `AG01`. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.