> ## 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.

# Verificação do parceiro antifraude no Pix Lerian

> Como o Pix Lerian pede ao parceiro antifraude da sua instituição que verifique o Pix enviado e recebido, como você liga cada verificação e o que o parceiro deve implementar.

O Pix Lerian pode pedir ao parceiro antifraude da sua própria instituição que verifique um Pix antes de o Pix Lerian enviá-lo ao trilho ou creditá-lo. O parceiro responde `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.

| Fluxo | O que o parceiro verifica |
| - | - |
| `out` | Um Pix que a sua instituição envia a um favorecido em outra instituição. |
| `intra_out` | Um Pix que a sua instituição envia a um favorecido no mesmo ISPB. |
| `in` | Um Pix que a sua instituição recebe de um pagador em outra instituição. |
| `intra_in` | Um Pix que a sua instituição recebe de um pagador no mesmo ISPB. |

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.

| Resposta | Resultado |
| - | - |
| `ALLOW` | O Pix Lerian envia o Pix. |
| `DENY` | O Pix Lerian estorna o débito e registra a transferência como `REJECTED`. [Processar transferência](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/process-transfer.md) responde `422` com `PIX-0336`. |
| `REVIEW` | O Pix espera em `FRAUD_ANALYSIS` quando pode ser retido (veja abaixo). Caso contrário, o Pix Lerian estorna o débito e a chamada responde `422` com `PIX-0338`. |

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 `posture` da 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_BACKEND` vazio, um segredo `hmac-v1` com menos de 32 caracteres e um endereço que o Pix Lerian não chama.

Quando o parceiro não dá uma decisão válida e a posture é `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 responde `REVIEW` espera em `FRAUD_ANALYSIS` somente quando todas estas condições valem:

* `ANTIFRAUD_OUT_REVIEW_ALLOWED` é `true` no SPI. O padrão é `false`.
* O `review_window_minutes` do fluxo é maior que `0`.
* O Pix não é um Saque nem um Troco.
* O prazo `decideBy` ainda está à frente.

A chamada responde `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:

1. **O pagador a cancela.** [`POST /spi/v1/transfers/{id}/cancel`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/cancel-a-sent-pix-held-in-fraud-analysis) recebe `X-Account-Id` e `X-Idempotency`, e não tem corpo. Responde `200` com a transferência `REJECTED` e o estorno feito. `fraudCheck.resolution` é `CANCELLED`. Responde `409` com `PIX-0339` quando o Pix não está retido, e `404` com `PIX-0340` para outra conta.
2. **O parceiro decide.** O parceiro chama [`POST /spi/v1/transfers/{id}/fraud-decision`](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/decide-a-sent-pix-held-in-fraud-analysis) com `analysisId` e `decision` (`ALLOW` ou `DENY`), por meio de uma aplicação da sua instituição que tem a permissão abaixo.
3. **O back office decide.** Uma pessoa da sua instituição chama a mesma rota e acrescenta uma `justification` de 10 a 500 caracteres.
4. **`decideBy` passa.** O Pix Lerian estorna o débito e encerra a transferência como `REJECTED`, com `fraudCheck.resolution` `EXPIRED`.

Por pouco tempo depois de um cancelamento ou de uma decisão, uma leitura pode mostrar a transferência como `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`.

| Status e código | Significado |
| - | - |
| `409` `PIX-0339` | A transferência não está retida, outra decisão, um cancelamento ou o prazo encerrou a análise antes, ou a chamada cita outro `analysisId`. |
| `409` `PIX-0344` | Um `ALLOW` que chega depois de `decideBy`. Um `DENY` ainda vale. |
| `422` `PIX-0343` | O corpo não é válido, ou uma pessoa não enviou `justification`. |
| `503` `PIX-0345` | O Pix Lerian está registrando a retenção. Tente de novo depois do tempo de `Retry-After`. |

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](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-spi.md#permissions-that-only-the-spi-declaration-grants). 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 um `feedbackEndpoint`, 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.

| Resposta | Resultado |
| - | - |
| `ALLOW` | O Pix Lerian aprova o Pix e credita a conta. |
| `DENY` ou `REVIEW` | O Pix Lerian recusa o Pix com o código de motivo `FRAD`, e a operação informa `PIX-0456`. Nada é creditado. |
| `DENY` ou `REVIEW` com o motivo `AG01` do parceiro | O Pix Lerian recusa o Pix com o código de motivo `AG01`, e a operação informa `PIX-0458`. |
| Sem resposta válida, posture `OPEN` | O Pix Lerian aprova o Pix sem verificação. |
| Sem resposta válida, posture `CLOSED` | O Pix Lerian recusa o Pix com o código de motivo `DS04`, e a operação informa `PIX-0457`. |

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

## 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](https://docs.lerian.studio/pt/reference/platform/systemplane/overview.md). O papel `admin` do SPI as grava. Para cada fluxo:

| Chave | Significado |
| - | - |
| `antifraud.<flow>.enabled` | Liga a verificação. O padrão é desligada. |
| `antifraud.<flow>.route` | A rota do parceiro, como um único objeto JSON. `{}` significa não definida. O Pix Lerian confere a rota quando você a grava. |
| `antifraud.<flow>.review_window_minutes` | Somente para `out` e `intra_out`. Quanto tempo o parceiro tem para decidir um `REVIEW`, em minutos, de 0 a 60. O padrão é 0, que não retém nada. |

A rota tem estes campos:

| Campo | Significado |
| - | - |
| `endpoint` | O endereço que recebe a avaliação. |
| `feedbackEndpoint` | Opcional. Somente para `out` e `intra_out`. O endereço que recebe o resultado de cada Pix enviado verificado. |
| `auth` | `mode` (`hmac-v1`, `lerian-m2m` ou `oauth2-client-credentials`). Os dois modos de token também exigem `tokenUrl` e `clientId`. `oauth2-client-credentials` aceita `scopes`. `staticHeaders` opcionais valem para todo modo. |
| `syncBudgetMs` | A espera mais longa por uma avaliação, com as novas tentativas incluídas. De 100 a 1500 para `out` e `intra_out`. De 100 a 1000 para `in` e `intra_in`. |
| `attemptTimeoutMs` | O limite de tempo de uma tentativa. Não pode ser maior que `syncBudgetMs`. |
| `maxAttempts` | O número de tentativas, 1 ou mais. Para `in` e `intra_in`, deve ser exatamente 1. |
| `posture` | `default` (`OPEN` ou `CLOSED`) é obrigatório, e `bands` são opcionais. |

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

No BYOC, o Pix Lerian chama um `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](https://docs.lerian.studio/pt/interfaces/pix-lerian/pix-lerian-environment-variables.md#antifraud-partner).

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 para `hmac-v1`. É obrigatório em todo modo de autenticação. Um segredo `hmac-v1` tem pelo menos 32 caracteres.
* `certPem` e `keyPem`: 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](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/spi/process-transfer.md). 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:

| Header | Valor |
| - | - |
| `Idempotency-Key` | A chave da avaliação. Para um Pix enviado, o id da transferência. Para um Pix recebido, `pix-cashin:` e o `endToEndId`. A mesma chave devolve a mesma análise. |
| `X-Lerian-Decide-By` | O prazo da decisão, em RFC 3339 UTC. |
| `X-Lerian-Payload-Schema` | `pix-out.v1` para um Pix enviado. `pix-cashin.v1` para um Pix recebido. |

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

| Campo | Significado |
| - | - |
| `decision` | `ALLOW`, `REVIEW` ou `DENY`, em maiúsculas. |
| `analysisId` | De 1 a 64 caracteres ASCII imprimíveis, sem espaço. Obrigatório com `REVIEW`. |
| `score`, `reasons` | Opcionais. O Pix Lerian não decide por eles. O motivo `AG01` recusa um Pix recebido com `AG01`. |

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.


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