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

# Verificación del socio antifraude en Pix Lerian

> Cómo Pix Lerian pide al socio antifraude de tu institución que verifique el Pix enviado y recibido, cómo activas cada verificación y qué debe implementar el socio.

Pix Lerian puede pedir al socio antifraude de tu propia institución que verifique un Pix antes de que Pix Lerian lo envíe al riel o lo acredite. El socio responde `ALLOW`, `REVIEW` o `DENY`. Cada verificación viene desactivada. La activas para tu institución.

## Las cuatro verificaciones

***

Cada verificación es un flujo. Un flujo tiene sus propios ajustes, ruta y credenciales.

| Flujo | Qué verifica el socio |
| - | - |
| `out` | Un Pix que tu institución envía a un beneficiario en otra institución. |
| `intra_out` | Un Pix que tu institución envía a un beneficiario en el mismo ISPB. |
| `in` | Un Pix que tu institución recibe de un pagador en otra institución. |
| `intra_in` | Un Pix que tu institución recibe de un pagador en el mismo ISPB. |

Con `intra_out` e `intra_in` activados, el socio verifica el mismo Pix dos veces. Un Pix Agendado que tu institución envía y una liquidación de Pix Automático no se verifican. Una devolución recibida no se verifica.

## Pix enviado

***

Con el flujo `out` o `intra_out` activado, Pix Lerian debita la cuenta, consulta al socio y solo entonces envía el Pix al riel. El socio tiene como máximo el `syncBudgetMs` de la ruta, que es de 1500 ms o menos.

| Respuesta | Resultado |
| - | - |
| `ALLOW` | Pix Lerian envía el Pix. |
| `DENY` | Pix Lerian revierte el débito y registra la transferencia como `REJECTED`. [Procesar transferencia](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/process-transfer.md) responde `422` con `PIX-0336`. |
| `REVIEW` | El Pix espera en `FRAUD_ANALYSIS` cuando se puede retener (consulta abajo). En otro caso, Pix Lerian revierte el débito y la llamada responde `422` con `PIX-0338`. |

Pix Lerian también revierte el débito y responde `422` con `PIX-0337` en estos casos:

* El socio no da una decisión válida, y la `posture` de la ruta es `CLOSED`.
* La configuración del flujo está rota, bajo cualquier posture. Ejemplos son una ruta ausente, un paquete de credenciales ausente, un `ANTIFRAUD_SECRETS_BACKEND` vacío, un secreto `hmac-v1` con menos de 32 caracteres y una dirección a la que Pix Lerian no llama.

Cuando el socio no da una decisión válida y la posture es `OPEN`, Pix Lerian envía el Pix sin verificación. La verificación muestra `origin` `FALLBACK` y la `cause`.

Si Pix Lerian no puede probar que revirtió el débito, la llamada responde `500` con `PIX-0000`. Lee la transferencia antes de actuar. Un reintento es una nueva iniciación, no una repetición de la misma llamada.

Toda lectura de una transferencia verificada trae `fraudCheck`. Guarda la `decision`, su `origin` (`PROVIDER` o `FALLBACK`), la `cause`, el `analysisId`, el `score` y los `reasons`. El `score` y los `reasons` son del socio, como los envió. El texto de un motivo puede nombrar a un tercero. Los eventos `outbound_transfer.completed` y `outbound_transfer.rejected` también llevan `fraudCheck`.

### Retener un Pix enviado para análisis

Un Pix enviado al que el socio responde `REVIEW` espera en `FRAUD_ANALYSIS` solo cuando se cumplen todas estas condiciones:

* `ANTIFRAUD_OUT_REVIEW_ALLOWED` es `true` en el SPI. El valor predeterminado es `false`.
* El `review_window_minutes` del flujo es mayor que `0`.
* El Pix no es un Saque ni un Troco.
* El plazo `decideBy` aún está por delante.

La llamada responde `201`. El débito y el uso del límite permanecen, y Pix Lerian no envía nada. El evento `outbound_transfer.fraud_analysis` anuncia la retención, y `GET /transfers` acepta `status=fraud_analysis`.

`decideBy` es el menor de dos tiempos, menos 3 minutos. El primero es el tiempo manual del Pix: 30 minutos de 08:00 a 20:00 en un día hábil, y 60 minutos en cualquier otro momento, en horario de America/Sao\_Paulo. El segundo es la ventana de análisis del flujo. `fraudCheck.decideBy` lo muestra.

Una transferencia en `FRAUD_ANALYSIS` termina de una de estas formas:

1. **El pagador la cancela.** [`POST /spi/v1/transfers/{id}/cancel`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/cancel-a-sent-pix-held-in-fraud-analysis) recibe `X-Account-Id` y `X-Idempotency`, y no tiene cuerpo. Responde `200` con la transferencia `REJECTED` y la reversión hecha. `fraudCheck.resolution` es `CANCELLED`. Responde `409` con `PIX-0339` cuando el Pix no está retenido, y `404` con `PIX-0340` para otra cuenta.
2. **El socio decide.** El socio llama a [`POST /spi/v1/transfers/{id}/fraud-decision`](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/decide-a-sent-pix-held-in-fraud-analysis) con `analysisId` y `decision` (`ALLOW` o `DENY`), mediante una aplicación de tu institución que tiene el permiso siguiente.
3. **Tu back office decide.** Una persona de tu institución llama a la misma ruta y agrega una `justification` de 10 a 500 caracteres.
4. **`decideBy` pasa.** Pix Lerian revierte el débito y cierra la transferencia como `REJECTED`, con `fraudCheck.resolution` `EXPIRED`.

Por poco tiempo después de una cancelación o de una decisión, una lectura puede mostrar la transferencia como `PENDING` con una `resolution`.

Con `ALLOW`, la ruta envía el Pix y responde `200` con la transferencia en `PROCESSING`. Con `DENY`, revierte el débito y responde `200` con la transferencia `REJECTED`. El registro muestra quién decidió: `resolutionOrigin` es `PARTNER` u `OPERATOR`, y `resolvedBy` es el subject del token. Pix Lerian nunca publica la `justification`.

| Estado y código | Significado |
| - | - |
| `409` `PIX-0339` | La transferencia no está retenida, otra decisión, una cancelación o el plazo cerró el análisis antes, o la llamada nombra otro `analysisId`. |
| `409` `PIX-0344` | Un `ALLOW` que llega después de `decideBy`. Un `DENY` aún vale. |
| `422` `PIX-0343` | El cuerpo no es válido, o una persona no envió `justification`. |
| `503` `PIX-0345` | Pix Lerian está registrando la retención. Reintenta después del tiempo de `Retry-After`. |

La ruta exige el permiso `transfer-fraud-decision` con la acción `post`. Es de nivel de tenant, y los roles `editor` y `contributor` lo tienen. En BYOC, solo la declaración de permisos de SPI lo concede: consulta [Permisos que solo concede la declaración de SPI](https://docs.lerian.studio/es/interfaces/pix-lerian/pix-lerian-spi.md#permissions-that-only-the-spi-declaration-grants). La cancelación exige el permiso `transfers` con la acción `post` para la cuenta.

### El resultado de cada Pix enviado

Cuando la ruta de un flujo de envío tiene un `feedbackEndpoint`, Pix Lerian informa cómo terminó cada Pix verificado. Envía el reporte hasta 24 horas después de que el Pix terminó. El cuerpo tiene `evaluationKey` (el id de la transferencia), `analysisId`, `decisionOrigin` (`PROVIDER` o `FALLBACK`), `outcome` y `occurredAt`. `outcome` es `SETTLED`, `CANCELLED`, `EXPIRED` o `REJECTED`. El `Idempotency-Key` es el id de la transferencia, dos puntos y el resultado. El socio debe aplicar cada resultado una vez.

## Pix recibido

***

Con el flujo `in` o `intra_in` activado, Pix Lerian consulta al socio antes de aprobar un Pix recibido. El socio tiene como máximo el `syncBudgetMs` de la ruta, que es de 1000 ms o menos.

Pix Lerian comprueba primero la cuenta de destino. Un Pix que la comprobación de la cuenta rechaza no llega al socio.

| Respuesta | Resultado |
| - | - |
| `ALLOW` | Pix Lerian aprueba el Pix y acredita la cuenta. |
| `DENY` o `REVIEW` | Pix Lerian rechaza el Pix con el código de motivo `FRAD`, y la operación informa `PIX-0456`. No se acredita nada. |
| `DENY` o `REVIEW` con el motivo `AG01` del socio | Pix Lerian rechaza el Pix con el código de motivo `AG01`, y la operación informa `PIX-0458`. |
| Sin respuesta válida, posture `OPEN` | Pix Lerian aprueba el Pix sin verificación. |
| Sin respuesta válida, posture `CLOSED` | Pix Lerian rechaza el Pix con el código de motivo `DS04`, y la operación informa `PIX-0457`. |

Una configuración rota rechaza el Pix con `DS04`, bajo cualquier posture. Las causas son las mismas de un Pix enviado.

La respuesta del socio se guarda como `fraudCheck` en la transferencia, y los eventos `inbound_transfer.completed` e `inbound_transfer.credit_parked` la llevan. El evento `inbound_transfer.denied` anuncia cada Pix recibido que Pix Lerian rechazó en la aprobación. Ninguna transferencia existe para él. Consulta [Eventos](https://docs.lerian.studio/es/interfaces/pix-lerian/pix-lerian-events.md).

## Activar una verificación

***

Escribe los ajustes en la configuración de runtime del SPI, namespace `spi`, con la API de administración de [Systemplane](https://docs.lerian.studio/es/reference/platform/systemplane/overview.md). El rol `admin` del SPI los escribe. Para cada flujo:

| Clave | Significado |
| - | - |
| `antifraud.<flow>.enabled` | Activa la verificación. El valor predeterminado es desactivada. |
| `antifraud.<flow>.route` | La ruta del socio, como un único objeto JSON. `{}` significa no definida. Pix Lerian comprueba la ruta cuando la escribes. |
| `antifraud.<flow>.review_window_minutes` | Solo para `out` e `intra_out`. Cuánto tiempo tiene el socio para decidir un `REVIEW`, en minutos, de 0 a 60. El valor predeterminado es 0, que no retiene nada. |

La ruta tiene estos campos:

| Campo | Significado |
| - | - |
| `endpoint` | La dirección que recibe la evaluación. |
| `feedbackEndpoint` | Opcional. Solo para `out` e `intra_out`. La dirección que recibe el resultado de cada Pix enviado verificado. |
| `auth` | `mode` (`hmac-v1`, `lerian-m2m` u `oauth2-client-credentials`). Los dos modos de token también exigen `tokenUrl` y `clientId`. `oauth2-client-credentials` acepta `scopes`. `staticHeaders` opcionales valen para todo modo. |
| `syncBudgetMs` | La espera más larga por una evaluación, con los reintentos incluidos. De 100 a 1500 para `out` e `intra_out`. De 100 a 1000 para `in` e `intra_in`. |
| `attemptTimeoutMs` | El límite de tiempo de un intento. No puede ser mayor que `syncBudgetMs`. |
| `maxAttempts` | El número de intentos, 1 o más. Para `in` e `intra_in`, debe ser exactamente 1. |
| `posture` | `default` (`OPEN` o `CLOSED`) es obligatorio, y `bands` son opcionales. |

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

En BYOC, Pix Lerian llama a un `endpoint`, `feedbackEndpoint` o `tokenUrl` solo cuando es `https` en una dirección pública, a menos que su host esté en `ANTIFRAUD_ALLOWED_PRIVATE_HOSTS`. Cuando escribes una ruta que no cumple esta regla, Pix Lerian la rechaza. Consulta las [variables de entorno](https://docs.lerian.studio/es/interfaces/pix-lerian/pix-lerian-environment-variables.md#antifraud-partner).

En BYOC, Pix Lerian lee un paquete de credenciales del gestor de secretos que `ANTIFRAUD_SECRETS_BACKEND` nombra. La ruta es `tenants/{env}/single-tenant/plugin-br-pix-lerian-spi/external/antifraud-<flow>/credentials`. `{env}` es el valor de `ENV_NAME`, en minúsculas y sin espacios. `<flow>` es `out`, `intra-out`, `intra-in` o `in`. El paquete acepta estas claves:

* `secret`: el secreto del cliente, o el secreto HMAC para `hmac-v1`. Es obligatorio en todo modo de autenticación. Un secreto `hmac-v1` tiene al menos 32 caracteres.
* `certPem` y `keyPem`: un par opcional de certificado de cliente. Envía los dos o ninguno.
* `header.<Name>`: un header opcional que Pix Lerian envía en cada llamada.

## Qué recibe el socio

***

Con un flujo activado, Pix Lerian envía al socio estos datos de las dos partes: el nombre completo, el CPF o CNPJ, el tipo de persona, el ISPB, la sucursal, la cuenta y el tipo de cuenta. También envía el monto, el `endToEndId`, la descripción y la clave Pix del beneficiario. Un Pix enviado también lleva el `metadata` que el llamador envió a [Procesar transferencia](https://docs.lerian.studio/es/reference/interfaces/pix-lerian/spi/process-transfer.md). Pix Lerian lo pasa sin leerlo.

## Qué implementa el socio

***

Pix Lerian envía cada evaluación como un `POST` de un cuerpo JSON al `endpoint` de la ruta. Los headers son:

| Header | Valor |
| - | - |
| `Idempotency-Key` | La clave de la evaluación. Para un Pix enviado, el id de la transferencia. Para un Pix recibido, `pix-cashin:` y el `endToEndId`. La misma clave devuelve el mismo análisis. |
| `X-Lerian-Decide-By` | El plazo de la decisión, en RFC 3339 UTC. |
| `X-Lerian-Payload-Schema` | `pix-out.v1` para un Pix enviado. `pix-cashin.v1` para un Pix recibido. |

El cuerpo de un Pix enviado tiene `transferId`, `endToEndId`, `flow` (`EXTERNAL` o `INTRA`), `initiationType`, `transactionType`, `amount`, `currency` (`BRL`), `description`, `txId`, `payer`, `payee`, `createdAt` y `metadata`. El cuerpo de un Pix recibido tiene `endToEndId`, `flow`, `initiationType`, `amount`, `currency`, `description`, `txId`, `payer` y `payee`. Cada parte tiene `name`, `taxId`, `personType`, `ispb`, `branch`, `account`, `accountType` y `key`. El pagador de un Pix enviado y el beneficiario de un Pix recibido llevan `accountId`.

Pix Lerian firma cada llamada con el `auth.mode` de la ruta:

* `hmac-v1`: `X-Webhook-Timestamp` tiene la hora Unix en segundos. `X-Webhook-Signature` es `v1,sha256=` seguido del HMAC-SHA256 en hexadecimal de `v1:<timestamp>.<raw body>` con el `secret`.
* `lerian-m2m` y `oauth2-client-credentials`: Pix Lerian obtiene un token en `auth.tokenUrl` con el `clientId` y el `secret`. Envía el token como bearer token.

El socio responde `200` con un cuerpo JSON:

| Campo | Significado |
| - | - |
| `decision` | `ALLOW`, `REVIEW` o `DENY`, en mayúsculas. |
| `analysisId` | De 1 a 64 caracteres ASCII imprimibles, sin espacio. Obligatorio con `REVIEW`. |
| `score`, `reasons` | Opcionales. Pix Lerian no decide por ellos. El motivo `AG01` rechaza un Pix recibido con `AG01`. |

Un `202` cuenta como `REVIEW` y exige un `analysisId`, a menos que el cuerpo diga `DENY`. Cualquier estado distinto de `200` o `202`, o un `REVIEW` sin `analysisId` válido, no es una decisión. Pix Lerian entonces aplica la `posture` de la ruta.


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