Saltar al contenido principal
TED Lerian puede pedir al socio de antifraude de tu propia institución que analice una transferencia antes de que el dinero se mueva. El socio responde ALLOW, REVIEW o DENY. Cada verificación viene desactivada de forma predeterminada. Tú activas la verificación para tu institución.

Las cuatro verificaciones

Cada verificación es un flujo. Un flujo tiene sus propios ajustes, ruta y credenciales. TED Lerian lee los ajustes cuando crea una transferencia. Una transferencia creada con todos los flujos desactivados no se analiza, aunque actives un flujo después. Su fraudCheck es null.

TEDs enviadas y transferencias internas

TED Lerian espera al socio como máximo el syncBudgetMs de la ruta, que es 4000 ms o menos. Una TED se analiza después de que TED Lerian retiene el monto y antes de enviar la TED al STR. En una transferencia interna con los dos flujos activados, TED Lerian consulta primero el lado del pagador y después el lado del destinatario. Se detiene en el primer rechazo. La respuesta de creación puede devolver REJECTED o FRAUD_ANALYSIS. Toda lectura de transferencia trae fraudCheck. Tiene decideBy y una verificación por cada flujo que estaba activado cuando TED Lerian creó la transferencia. Cada verificación tiene la decision, su origin (PROVIDER o FALLBACK), la cause, el analysisId, el score, los reasons, la resolution y resolvedAt. El score y los reasons son los del socio, como los envió. El texto de un motivo puede nombrar a un tercero. decideBy es la hora de creación más la ventana de revisión del flujo, menos 2 minutos. La ventana de revisión es el ajuste review_window_minutes, de 10 a 30 minutos. Cuando los dos flujos internos están activados, vale la menor ventana. En una TED, el cierre de la ventana operativa puede adelantar decideBy: pasa a ser el cierre menos 2 minutos. El cierre de la ventana operativa no vale para una transferencia interna. Con el flujo out activado, TED Lerian rechaza una TED con 422 TED-0020 cuando la ventana operativa cierra en 2 minutos y 4 segundos o menos. En ese caso TED Lerian no retiene nada. Si TED Lerian no puede leer los ajustes de antifraude, rechaza el envío con un 503 antes de retener cualquier monto. Una transferencia en FRAUD_ANALYSIS termina de una de estas formas:
  1. El socio decide. El socio llama a la operación de resolución. En DENY, TED Lerian rechaza la transferencia con TED-0050. En ALLOW, envía una TED al STR, o liquida una transferencia interna cuando todos los lados aprueban.
  2. Tú cancelas. POST /v1/transfers/{transferId}/cancel responde 200, y TED Lerian libera la retención y el límite de uso. Mientras una llamada a Midaz o a Lerian SPB para la transferencia está en curso, la respuesta es 409 TED-0061.
  3. decideBy pasa. TED Lerian rechaza la transferencia con TED-0052, con el origen WORKER en la línea de tiempo, y libera la retención y el límite de uso.
Después de decideBy, TED Lerian aún acepta un DENY para una transferencia en FRAUD_ANALYSIS. Un ALLOW que llega en decideBy o después recibe 409 TED-0060. Un ALLOW para una TED que llega a tiempo, con la ventana operativa cerrada, rechaza la TED con TED-0020 o TED-0021. Si TED Lerian no puede leer la ventana, responde 503 TED-0022 y no hace ningún cambio. TED-0050, TED-0051 y TED-0052 llegan en rejection.code de una transferencia REJECTED. No son respuestas de error.

Cuando el socio no puede responder

Un socio puede agotar el tiempo, rechazar una llamada o enviar una respuesta inválida. En out, intra_out e intra_in, la posture de la ruta decide entonces:
  • CLOSED rechaza la transferencia con TED-0051.
  • OPEN deja que la transferencia siga sin análisis. La verificación muestra origin FALLBACK y la cause.
posture.default define la postura. Las bands opcionales la definen por monto: decide la primera banda cuyo upTo es igual o mayor que el monto. TED Lerian rechaza la transferencia con TED-0051, sea cual sea la postura, en estos casos:
  • La ruta no está definida.
  • El paquete de credenciales falta o no se puede leer.
  • ANTIFRAUD_SECRETS_BACKEND está vacío.
  • La dirección es una a la que TED Lerian no llama, o su certificado TLS no se verifica.
Si el gestor de secretos no responde, decide la postura. El flujo in no tiene postura. En una TED recibida, una respuesta que no viene del socio no acredita ni devuelve la TED. TED Lerian la envía a revisión manual.

TEDs recibidas

Con el flujo in activado, TED Lerian no acredita una TED recibida antes de que el socio responda. Una TED en FRAUD_REVIEW termina de una de estas formas:
  1. El socio decide. El socio llama a la operación de resolución. En ALLOW, TED Lerian acredita la TED. En DENY, devuelve la TED con el motivo 9.
  2. Un operador resuelve la revisión. El operador usa resolve-review, como en cualquier otra revisión manual.
  3. decideBy pasa. decideBy es 15 minutos antes del plazo regulatorio de 60 minutos, es decir, 45 minutos después de la liquidación interbancaria. TED Lerian marca la revisión abierta como EXPIRED. Con antifraud.in.auto_return_enabled activado, devuelve la TED con el motivo 9. Con él desactivado, la TED queda con el operador.
La operación de resolución responde 409 TED-0060 en estos casos:
  • La TED no espera este análisis.
  • El analysisId es distinto.
  • Hay otra decisión registrada.
  • decideBy pasó.
  • Un DENY llega después de que el crédito de la TED por un operador pudo haber llegado al ledger.
No repitas un 409. Un 503 significa que TED Lerian no terminó. Repite con el mismo X-Idempotency. TED-0053 significa que la decisión llegó antes de que TED Lerian registrara el análisis, o que la misma clave sigue en curso. Con TED-1000 o TED-0080, la decisión queda registrada, y la repetición la termina.

Activar una verificación

Escribe los ajustes en el namespace plugin-br-ted-lerian.policy con la API de administración de systemplane de TED Lerian, en el plano /v1/system. El rol editor escribe los ajustes. Para cada flujo: La ruta tiene estos campos:
TED 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, TED Lerian la rechaza. Consulta las variables de entorno. En BYOC, TED Lerian lee un paquete de credenciales del gestor de secretos que ANTIFRAUD_SECRETS_BACKEND nombra. La ruta es tenants/{ENVIRONMENT_NAME}/single-tenant/plugin-br-ted-lerian/external/antifraud-<flow>/credentials. <flow> es out, intra-out, intra-in o in. Con vault, la ruta queda bajo el mount KV v2 secret. El paquete acepta estas claves:
  • secret: el secreto del cliente, o el secreto HMAC en hmac-v1. Es obligatorio en todos los modos de autenticación.
  • certPem y keyPem: un par de certificado de cliente opcional. Envía los dos o ninguno.
  • header.<Name>: un header opcional que TED Lerian envía en cada llamada.

Qué recibe el socio

Con un flujo activado, TED Lerian envía al socio estos datos de las dos partes:
  • El nombre completo.
  • El CPF o CNPJ.
  • El ISPB, la agencia, la cuenta y el tipo de cuenta.
También envía el monto y el código de finalidad.
  • TEDs enviadas y transferencias internas: la descripción y el metadata de la transferencia. El lado del pagador también recibe clientReference.
  • TEDs recibidas: la descripción que escribió la institución emisora, el nuop, el número de control del STR y la hora de la liquidación.

Qué implementa el socio

TED Lerian envía cada evaluación como un POST de un cuerpo JSON al endpoint de la ruta. Los headers son: Cada cuerpo tiene transferId, flow (EXTERNAL o INTRA), amount, currency (BRL), payer, payee y createdAt. También tiene purposeCode, sin ceros a la izquierda, y description cuando existen. ted-out.v1 suma clientReference y metadata. ted-in.v1 suma metadata en una transferencia interna, y messageCode, numCtrlStr, settledAt y nuop en una TED recibida. Cada parte tiene name, taxId, ispb, branch, account y accountType. Las TED enviadas y las transferencias internas también llevan personType. El lado con cuenta en tu institución lleva accountId. TED 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: TED 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 necesita un analysisId, a menos que el cuerpo diga DENY. TED Lerian repite un 408, 429 o 5xx con la misma Idempotency-Key, dentro de syncBudgetMs y maxAttempts. No repite un 403. En los modos de token, cuando maxAttempts es 2 o más, repite un 401 una vez, después de obtener un token nuevo. Cualquier estado distinto de 200 o 202, un cuerpo de más de 64 KiB, o un REVIEW sin analysisId válido no es una decisión. TED Lerian lo trata como una respuesta que no vino del socio (consulta Cuando el socio no puede responder). El socio envía la decisión final de un REVIEW con estas operaciones. Las dos exigen el rol editor. Una aplicación con el rol operator no puede llamarlas. El cuerpo es analysisId, decision (ALLOW o DENY) y reasons opcional. X-Idempotency es obligatorio, y su valor es <analysisId>:<decision>. Los reasons de una resolución reemplazan los motivos de la evaluación en la verificación. El score se mantiene. Cuando la ruta del flujo out, intra_out o intra_in tiene un feedbackEndpoint, TED Lerian informa el resultado de cada TED enviada y transferencia interna analizada. No envía feedback para las TED recibidas. El cuerpo tiene evaluationKey, analysisId, decisionOrigin (PROVIDER o FALLBACK), outcome y occurredAt. outcome es SETTLED, REJECTED, CANCELLED, EXPIRED o RETURNED. La Idempotency-Key es la clave de la evaluación, dos puntos y el resultado. El feedback necesita OUTBOX_ENABLED con el valor true. Sin él, el análisis funciona y TED Lerian no envía feedback.