Saltar al contenido principal
SPI gestiona transferencias Pix, devoluciones, resultados asíncronos y el Block Balancer MED 2.0. Llama a Midaz para la acción del ledger que corresponde a la operación. Un Pix recibido nunca paga tarifa. Pix Lerian pide a Midaz que omita las tarifas en cada crédito de un Pix recibido y de una devolución, y Midaz solo lo atiende cuando la configuración overrides.allowFeeSkip está activada en el ledger de Pix. Un paquete de tarifas de retiro debe ser adicional: consulta el error PIX-0330. Lerian activa overrides.allowFeeSkip en el ledger de Pix cuando aprovisiona el servicio.
Las rutas de callbacks de entrada y retiro de efectivo son exclusivas del adaptador. Una aplicación cliente no debe publicar un callback ni afirmar el resultado de una liquidación del proveedor.

​
Envía un retiro en dos etapas

Un retiro se divide deliberadamente entre iniciación y procesamiento.
  1. Llama a Iniciar transferencia con un valor X-Idempotency nuevo. El plugin valida la solicitud y crea una iniciación de transferencia. Rechaza un destino manual del tipo SLRY (cuenta salario).
  2. Llama a Procesar transferencia para esa iniciación. El plugin ejecuta el débito requerido en Midaz y envía el trabajo al adaptador de conectividad.
  3. Lee la transferencia con Obtener transferencia. La aceptación del procesamiento no es un resultado final del pago.
  4. Deja que el adaptador de conectividad entregue el callback terminal. Lee de nuevo hasta que la transferencia llegue a un estado completado, rechazado u otro estado terminal conforme al contrato de respuesta.
Si el plugin no puede probar que no envió el pago, mantiene el débito y responde 201 con el estado PROCESSING. Un 502 con PIX-0325 significa que el plugin no envió el pago y revirtió el débito. Un 500 (PIX-0000) significa que la reversión no está registrada: lee la transferencia antes de actuar. Una transferencia o una devolución que permanece en PROCESSING durante 90 minutos o más se puede resolver con Desbloquear transferencia o Desbloquear devolución. El plugin consulta al SPI el resultado y lo aplica. Conserva el mismo valor de idempotencia solo para reintentar la misma llamada. Un pago de negocio nuevo necesita un valor nuevo.

​
Recibe una entrada de efectivo mediante el límite del adaptador

El adaptador recibe el evento del lado externo, llama a los callbacks internos de aprobación y liquidación del plugin, y el plugin valida y acredita el destino mediante Midaz. Tu aplicación observa este flujo mediante lecturas públicas de transferencias: usa direction=in para listar las transferencias que recibió una cuenta. No invoca los callbacks de aprobación ni liquidación. Una entrada de efectivo que no puede aprobarse o liquidarse no es una decisión de reintento del cliente. Inspecciona el estado público de la operación antes de tomar otra acción. Todo movimiento de Pix se registra contra @external/BRL por defecto. Cuando la configuración settlement_account_alias de SPI nombra una cuenta común, esa cuenta la reemplaza: un retiro la acredita y un Pix recibido la debita. Un retiro inmediato cuyo crédito esa cuenta no puede recibir responde 422 con PIX-0332. Cambia la configuración solo cuando no haya ninguna retención de Pix Programado vigente.

​
Acreditar un Pix recibido que está estacionado

Cuando Midaz no confirma el crédito de un Pix recibido, o de una devolución, Pix Lerian no lo descarta. Estaciona el crédito y emite inbound_transfer.credit_parked o refund.credit_parked (consulta Eventos). El evento nombra el motivo: Para LEDGER_OUTCOME_UNKNOWN y SETTLE_INTERRUPTED, llama de inmediato. Para ACCOUNT_BLOCKED y LEDGER_REFUSED, corrige la causa primero y no llames automáticamente. Llama a Acreditar un Pix recibido cuyo crédito en el ledger está estacionado o Acreditar una devolución de Pix recibida cuyo crédito en el ledger está estacionado para acreditarlo. La llamada nunca acredita dos veces: consulta primero a Midaz y responde 409 con PIX-0474 cuando Midaz no puede confirmar el crédito; concílialo a mano. Quien llama necesita el permiso para publicar transferencias, o devoluciones en la ruta de devolución.

​
Verificación de fraude en el Pix recibido

Tu institución puede verificar un Pix recibido con su propio sistema de fraude antes de que Pix Lerian lo apruebe. La verificación está desactivada de forma predeterminada. Cada tenant la activa en la configuración de runtime del SPI. Pix Lerian verifica primero la cuenta de destino. Un Pix que la verificación de la cuenta rechaza no llega a tu endpoint. Las liquidaciones de Pix Automático y las devoluciones recibidas no se verifican.

​
La solicitud

Pix Lerian envía una solicitud POST con un cuerpo JSON:
  • contractVersion: 1.0.
  • eventType: PIX_CASHIN.
  • approvalId: un UUID. Cada solicitud sobre el mismo Pix lleva el mismo valor.
  • requestedAt y respondBy: marcas de tiempo en UTC. respondBy es el momento hasta el cual Pix Lerian espera tu respuesta.
  • cashin: el monto, el endToEndId, el pagador (debitParty), el receptor (creditParty) y la cuenta que recibe el crédito (account).
Cada solicitud lleva estos headers:
  • X-Webhook-Timestamp: la hora Unix, en segundos, de la firma.
  • X-Webhook-Signature: v1,sha256=<hex>, donde <hex> es el HMAC-SHA256 en minúsculas de v1:<timestamp>.<raw body> con antifraud_hook_secret como clave.
  • Idempotency-Key: el approvalId.
  • Tu header, cuando configuras uno.
Verifica la firma sobre el cuerpo sin procesar antes de decidir.

​
La respuesta

Responde con un estado 2xx y un objeto JSON con un campo decision:
  • APPROVE o ALLOW: Pix Lerian aprueba el Pix.
  • REJECT, DENY o REVIEW: Pix Lerian rechaza el Pix con el código de motivo FRAD, y no se acredita nada. Cuando la respuesta trae el motivo AG01, el rechazo sale con AG01 en su lugar, y la operación informa PIX-0458.
Pix Lerian puede volver a preguntar por el mismo Pix con la misma Idempotency-Key. Da la misma decisión cada vez.

​
Cuando tu endpoint no responde

Pix Lerian aplica la decisión de contingencia cuando no recibe una decisión: ante un timeout, un error de conexión, un estado fuera de 2xx, una redirección, una respuesta que no puede leer o una configuración incompleta. Después de fallas repetidas, Pix Lerian deja de llamar a tu endpoint por un tiempo corto y aplica la contingencia. Un rechazo por la contingencia sale con el código de motivo DS04.
La contingencia predeterminada es APPROVE. Con este valor predeterminado, mientras tu endpoint no responde, Pix Lerian aprueba los Pix recibidos sin tu verificación, hasta antifraud_hook_fallback_max_approve_amount cuando configuras ese valor.

​
Crea y observa una devolución

Usa Crear devolución para una transferencia apta y luego léela mediante Obtener devolución. reasonCode acepta solo MD06, SL02, FR01 y BE08. Una devolución que el riel rechaza responde 422 (PIX-0013). Una devolución sigue su propio ciclo de vida asíncrono. No la marques como completada hasta que el plugin registre el resultado terminal del proveedor y el efecto correspondiente en Midaz. Un reintento con el mismo valor de X-Idempotency dentro de la hora siguiente a la primera respuesta 2xx devuelve la respuesta original con el header X-Idempotency-Replayed: true. El valor sigue ligado a la devolución hasta que queda FAILED. Un reintento que cambia la transferencia, el monto, el reasonCode o el motivo responde 412 (PIX-0031). Después de un 5xx o de un 409 (PIX-0406), el primer intento todavía puede estar en PROCESSING con su débito. Llama a Listar devoluciones con transferId antes de reintentar.

​
Usa el Block Balancer MED 2.0

El Block Balancer retiene fondos para una transacción disputada antes de decidir la devolución. Es un flujo operativo controlado, no un atajo para transferencias normales. La referencia de la API llama bloqueo cautelar a cada retención: consulta Crear un bloqueo cautelar, Liquidar un bloqueo cautelar y Liberar un bloqueo cautelar al titular de la cuenta. Las rutas de devolución de DICT liquidan las retenciones de una devolución MED: consulta DICT.
  1. Crea una retención para la transacción disputada. El plugin coloca una retención pendiente de Midaz desde el saldo disponible en la cuenta de bloqueo configurada. Una repetición del mismo request_ref devuelve la retención existente.
  2. Si el caso termina antes de la liquidación, libera una retención PENDING. No puedes liberar una retención que ya está en liquidación.
  3. Inicia la liquidación de Phase 1 para una retención o un grupo apto. La retención pasa a SETTLING. La rama devuelve la retención pendiente y envía una devolución, o confirma la retención, gestiona cualquier excedente y envía el pago requerido.
  4. Completa Phase 2 solo a partir del resultado observado de la operación vinculada. Un éxito deja la retención en SETTLED. Un fallo la compensa a PENDING.
  5. Cierra una retención después de una devolución manual, devuelve un excedente de liquidación al titular de la cuenta y lee los registros de auditoría con las rutas de la referencia de la API en Bloqueos cautelares.
El Block Balancer aplica un límite conjunto a sus propias liquidaciones y a las devoluciones salientes normales de la misma transacción original. No intentes calcular alrededor de esa protección desde el cliente. Para el flujo de infracciones y recuperación de fondos del lado de DICT, consulta DICT.