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

# Usa SPI con Pix Lerian

> Prueba el comportamiento de retiro, callback de entrada de efectivo, devolución y retención de saldo MED 2.0 de Pix Lerian v1.0.0 con Midaz y el proveedor mock incluido.

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.

<Note>
  Las rutas de callbacks de entrada y retiro de efectivo son exclusivas del adaptador. En esta versión, el proveedor mock incluido es la forma compatible de probarlas. Una aplicación cliente no debe publicar un callback ni afirmar el resultado de una liquidación del proveedor.
</Note>

## Envía un retiro en dos etapas

Un retiro se divide deliberadamente entre iniciación y procesamiento.

1. Llama a [Iniciar transferencia](/es/reference/interfaces/pix-lerian/spi/initiate-transfer) con un valor `X-Idempotency` nuevo. El plugin valida la solicitud y crea una iniciación de transferencia.
2. Llama a [Procesar transferencia](/es/reference/interfaces/pix-lerian/spi/process-transfer) para esa iniciación. El plugin ejecuta el débito requerido en Midaz y envía el trabajo al proveedor mock.
3. Lee la transferencia con [Obtener transferencia](/es/reference/interfaces/pix-lerian/spi/get-transfer). La aceptación del procesamiento no es un resultado final del pago.
4. Deja que el proveedor mock entregue el callback terminal. Lee de nuevo hasta que la transferencia se complete, se rechace o llegue a otro estado terminal conforme al contrato de respuesta.

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; 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 y la evidencia de pruebas del mock antes de tomar otra acción.

## Crea y observa una devolución

Usa [Crear devolución](/es/reference/interfaces/pix-lerian/spi/create-refund) para una transferencia apta y luego léela mediante [Obtener devolución](/es/reference/interfaces/pix-lerian/spi/get-refund). 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.

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

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`. Una retención que ya está en liquidación no puede liberarse.
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. Usa el cierre manual, la devolución del excedente y las funciones de auditoría solo mediante controles operativos autorizados. No son endpoints normales de la aplicación.

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](/es/interfaces/pix-lerian/pix-lerian-dict).