Saltar al contenido principal
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. 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. 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 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 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. 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. 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. 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.

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. El rol admin del SPI los escribe. Para cada flujo: La ruta tiene estos campos:
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. 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. 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: 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: 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.