Saltar al contenido principal
Lerian SPI expone la superficie de mensajes de Pix como un conjunto de operaciones tipadas. El riel envía los mensajes de estas operaciones como tu participante directo, el ISPB en BACEN_SPI_PARTICIPANT_ISPB:
  • la prueba de conectividad;
  • la solicitud de reporte de la Conta PI y el registro de los responsáveis;
  • la solicitud, la cancelación y la resolución de mandato de Pix Automático (pain.009, pain.011, pain.012);
  • la instrucción, la resolución y la cancelación de programación de Pix Automático (pain.013, pain.014, camt.055);
  • el reporte de liquidación de MED 2.0.
Los cuerpos de solicitud de esas operaciones no reciben participantIspb, y un cuerpo que lo lleva recibe 422.

​
Incorporación y readiness

Registras un participante indirecto por su ISPB. Ingresa en PENDING, y el riel envía su solicitud de registro. Solo la confirmación de BACEN lo lleva a ACTIVE. Un rechazo de BACEN lo lleva a REGISTRATION_REJECTED. La acción de activación solo reactiva a un participante SUSPENDED. El orden de preparación recomendado antes de enviar pagos es:
  1. Sube un certificado Pix, solo el .cer público. El riel rechaza una clave privada subida.
  2. Confirma que el riel informa ready.
  3. Aprueba una prueba de conectividad.
  4. Envía pagos.
La misma superficie de Core también suspende y da de baja a un participante a lo largo de su ciclo de vida. La baja de un participante directo lo lleva a OFFBOARDED de inmediato. La baja de un participante indirecto lo lleva a OFFBOARD_PENDING, y el riel envía a BACEN un reda.031. La respuesta reda.016 de BACEN lleva al participante a OFFBOARDED, o de nuevo a ACTIVE si BACEN la rechaza. Mientras el reda.031 espera esa respuesta, una nueva solicitud de baja recibe 409. Cuando el riel sabe que el reda.031 no llegó a BACEN, puedes enviar la solicitud de baja de nuevo.

​
Enviar un Pix

Creas una orden de pago. La plataforma construye el mensaje ISO 20022 de transferencia de crédito (pacs.008), conserva la operación y la envía. BACEN devuelve una respuesta asíncrona de estado (pacs.002). El riel la valida y la aplica, y luego lleva el pago a COMPLETED o REJECTED. Lees de vuelta un pago por su ID de extremo a extremo, con su historial y una línea de tiempo por operación. Cuando el riel no puede conectarse a BACEN y no envía nada, el pago termina en FAILED, y la solicitud recibe 503 con el código SPI-1001. Una devolución en el mismo caso termina en NAO_REALIZADO, con la misma respuesta. Una operación que necesita atención aparece en la lista de operaciones atascadas, con las acciones que acepta. Envías una acción con un motivo. La resolución manual cierra una operación atascada. Requiere una aprobación APPROVED para esa operación. Para un Pix enviado que BACEN no respondió, la resolución declara el resultado en outcome: SETTLED o REJECTED. La aprobación nombra el mismo resultado en requestedAction: MANUAL_RESOLVE_SETTLED o MANUAL_RESOLVE_REJECTED. Una declaración SETTLED también lleva el instante de liquidación de BACEN tomado de la evidencia, en settledAt. El riel cierra el Pix como lo hace un pacs.002 y publica spi_payment.settled o spi_payment.rejected. Una respuesta posterior de BACEN no cambia el Pix. Cuando BACEN no responde a un Pix enviado dentro de su plazo, su fila ofrece RECONCILE_WITH_BACEN. Con esa acción, el riel le pide a BACEN el movimiento del pago (camt.060). Cuando la respuesta camt.054 de BACEN informa el pago como liquidado o rechazado, el riel lo completa o lo rechaza, como lo hace un pacs.002. Cualquier otra respuesta deja el pago abierto.

​
Recibir un Pix

El consumidor ICOM recibe mensajes firmados de BACEN y los pasa al ingreso interno autenticado del riel. Para un pacs.008 entrante, el riel valida el mensaje y registra el Pix como PENDING. Tu cliente entonces decide ese Pix de una de tres formas. Envía evidencia de fondos (saldo disponible, límite disponible, puntaje de riesgo) para que el riel la evalúe, declara que ya autorizó el crédito o envía un motivo de rechazo. El riel responde un rechazo FRAD como FRAD solo cuando tu cliente lo marca como la decisión de su sistema antifraude. Sin la marca, el riel responde DS04. El riel responde al SPI sobre un Pix aceptado, y el Pix llega a COMPLETED solo cuando el SPI confirma el crédito, o a REJECTED si el SPI lo rechaza. El riel rechaza un Pix que ninguna decisión concluye dentro de su ventana regulatoria, y una decisión posterior recibe 409. Un pago saliente no puede recibir fondeo como dinero entrante. Listas los Pix que recibes y los Pix que aún esperan una decisión. El evento spi_payment.received lleva el fin de la ventana regulatoria en decisionDeadline. Un Pix Agendado (PAGAGD) tiene 45 minutos y un Pix con sospecha de fraude (PAGFRD) tiene 40 segundos, ambos desde la recepción por el SPI. Cualquier otro Pix tiene 40 segundos desde el momento en que la institución del pagador aceptó la orden. El riel reserva los últimos 6 segundos de cada ventana para el trabajo después de la decisión.

​
Devolución (devolução)

Inicias una devolución (pacs.004) solo para un Pix liquidado que el riel recibió de BACEN, y luego lees el estado de la devolución. La devolución debita al receptor original y acredita al pagador original. No puedes iniciar una devolución para un Pix que envió tu cliente. La contraparte emite una devolución de ese Pix, y esta llega al riel como un mensaje entrante. Una devolución es la vía de movimiento de dinero de MED, la forma en que los fondos regresan a un pagador por una disputa o un error resuelto. Una devolución entrante no se liquida al llegar. El riel la retiene y la anuncia en un evento studio.lerian.br-spi.spi_payment.return_received que lleva su returnId. Tu cliente decide la devolución por ese returnId: autoriza la devolución o la rechaza con un motivo. Una devolución autorizada se liquida solo cuando el SPI la confirma. El riel rechaza una devolución que ninguna decisión concluye dentro de su ventana, y una decisión posterior recibe 409. Existen dos superficies de devolución, la solicitud de devolución y la devolución de pago. El riel registra cuál creó una devolución en lugar de inferirlo después. Una solicitud de devolución siempre es parcial, sea cual sea su valor, y usa el devolucaoId que eliges como su clave. Una devolución de pago por menos del valor del Pix también es parcial y requiere un devolucaoId. Una devolución de pago por el valor total es total: revierte todo el Pix y saca al pago principal de COMPLETED. Una devolución parcial deja el pago principal liquidado, y varias devoluciones parciales pueden coexistir para un mismo Pix. Cuando las devoluciones parciales liquidadas alcanzan el valor del Pix, el pago principal pasa a RETURNED. Se aplican tres barreras a toda devolución, en ambas superficies:
  • El pago principal debe ser un Pix entrante que se haya liquidado. Solo se puede devolver un pago recibido que llegó a COMPLETED (o que ya tiene una devolución).
  • La ventana de devolución de BACEN. Una devolución debe solicitarse dentro de los 90 días posteriores a la liquidación del Pix original. El riel mide la ventana desde el instante de liquidación, nunca desde la creación ni desde la última actualización. Un Pix sin instante de liquidación registrado no queda bloqueado: el riel registra el vacío y reenvía la solicitud.
  • El límite de la suma. Los valores de todas las devoluciones de un Pix no pueden superar el valor propio de ese Pix. Una devolución que termina en NAO_REALIZADO no cuenta. El riel lee solo el monto de ese pago y sus propias devoluciones. No calcula ninguna posición entre pagos.
Una aceptación de transporte no es una conclusión. Una solicitud de devolución acepta la naturaleza ORIGINAL (el valor predeterminado cuando no envías ninguna) o RETIRADA, el tramo de Pix Saque y troco. Una devolución de pago acepta un motivo: MD06, SL02, BE08 o FR01. Las dos naturalezas de MED (fallo operativo y sospecha fundada de fraude) se derivan de BE08 y FR01. Nunca las solicitas como naturaleza.

​
Ciclo de vida de las claves de DICT

Registras, actualizas y eliminas claves de Pix contra el directorio DICT. También listas, buscas y consultas claves, y verificas en lote si un conjunto de claves existe. El riel lee las estadísticas de claves de DICT y las estadísticas antifraude de BACEN, tanto por clave como por persona. Para la sincronización del directorio, el riel expone las operaciones VSync de BACEN. Verifica un conjunto de CIDs, resuelve un CID y lista los eventos del conjunto de CIDs. También solicita y transmite un archivo del conjunto de CIDs.

​
Reclamos de DICT (reivindicação)

Un reclamo mueve una clave de Pix entre participantes por portabilidad o titularidad. Inicias un reclamo contra un participante, y luego lo mueves a través de su ciclo de vida. El ciclo de vida cubre acuse de recibo, confirmar o rechazar, y completar o cancelar, tanto del lado donante como del reclamante. El job de plazos de reclamo se ejecuta de forma predeterminada y avanza los reclamos según sus ventanas de BACEN. Un reclamo aún puede requerir atención. Puedes abandonar un reclamo abierto que BACEN nunca registró. El reclamo termina en CANCELLED, y el riel no envía nada a BACEN.

​
BR Code y cobros

Un QR dinámico se resuelve en un cobro persistido, así que primero creas el cobro y luego generas el payload que se resuelve en él. Un QR estático se genera a partir de datos de pago estáticos. No requiere ni apunta a un cobro.
  • Crea un cobro: Cob (inmediato), CobV (con vencimiento, con interés y multa), o un lote de cobros con vencimiento.
  • Genera el payload del QR EMV dinámico, que se vincula al cobro por su txid o localizador y se resuelve como un JWS firmado.
También generas un QR estático, decodificas un payload, lo validas y registras un perfil de receptor (recebedor). Del lado del pagador, resuelves un QR dinámico escaneado en su cobro. El riel devuelve el cobro solo después de que el certificado del sitio del receptor y la firma del payload pasan sus verificaciones.

​
Pix Automático (recurrente)

Pix Automático autoriza pagos recurrentes y programados a través de la familia recurrente de ISO 20022:
  • Crea una autorización recurrente (recorrência) o una solicitud de una.
  • Solicita la confirmación del mandato (pain.009), cancélalo (pain.011), o acéptalo / recházalo (pain.012).
  • Programa una instrucción (pain.013) y acéptala / recházala (pain.014).
  • Solicita la cancelación de una instrucción programada (camt.055) y resuelve una cancelación recibida (camt.029).
  • Solicita un reintento de liquidación (retentativa) cuando un cobro programado falla.
La solicitud de cancelación (camt.055) tampoco recibe counterpartyIspb ni requestedBy. El riel lee los dos participantes y el lado que solicita a partir del pain.013 de la programación. El riel acepta los motivos CCLD y FAIL solo cuando tu institución es el participante del pagador en la programación. En la respuesta a un camt.055 recibido (camt.029), participantIspb nombra al participante al que se dirigió el camt.055. Cualquier otro valor recibe 422. Cuando el riel envía un camt.055 y ningún camt.029 lo responde en 12 horas, la cancelación surte efecto: el riel cancela la programación y publica spi_schedule.resolved. Si BACEN puede no haber recibido el camt.055, o si el cobro ya puede haberse liquidado, el riel lleva la operación a REQUIRES_OPERATOR_ACTION en su lugar. El riel puede rechazar una solicitud de cancelación recibida (camt.055) con un camt.029. Si BACEN rechaza ese camt.029 y no acepta ningún reenvío en las 12 horas posteriores a la llegada del camt.055, el riel cancela la programación. Si el cobro ya pudo haberse liquidado, el riel mantiene la programación y mueve su operación a REQUIRES_OPERATOR_ACTION.

​
Disputas de MED

Manejas los casos de fraude y error de MED (Mecanismo Especial de Devolução) en DICT, y reportas las liquidaciones internas en SPI:
  • Presenta solicitudes de devolución, marcadores de fraude y solicitudes de recuperación de fondos de DICT. Una recuperación de fondos se rastrea a través de su gráfico de ciclo de vida.
  • Lee, acusa recibo, cancela, cierra y actualiza reportes de infracción de DICT.
  • Reporta los Pix liquidados internamente mediante el reporte de liquidación de MED 2.0.

​
Reportes de la Conta PI

Solicitas un reporte de cuenta (camt.060) para el saldo (camt.053), el extracto (camt.052) o el detalle de movimiento (camt.054). El reporte siempre cubre la Conta PI de tu participante directo. Lees el saldo y el extracto de vuelta a través de la API. Reportes síncronos completan la superficie de reportes: una volumetria de solo conteo, un conteo de pagos rechazados con una lista paginada, y listados de saldo y de extracto. Cada ventana de reporte cubre como máximo 92 días. También registras los responsáveis de la Conta PI de tu participante directo (reda.022) y lees de vuelta su último registro conocido.

​
Archivo regulatorio

Lerian SPI archiva cada sobre ICOM que envía a BACEN o recibe de él, y cada solicitud y respuesta del DICT, con sus encabezados. También archiva los certificados que los firman o verifican. Cada elemento lleva su plazo de retención del Manual de Segurança do SFN, capítulo 7. Si el riel no puede archivar un mensaje saliente, no lo envía. GET /api/v1/spi/regulatory-archive/{itemId} devuelve un elemento archivado byte a byte, para que puedas verificar su firma de nuevo. La ruta acepta solo un usuario, no una aplicación, con el recurso br-spi-regulatory-archive de Access Manager y la acción read. El riel registra quién leyó qué elemento y cuándo antes de devolver el contenido. Una lectura que el riel no puede registrar no devuelve nada. Configuras el almacenamiento del archivo con las variables de entorno REGULATORY_ARCHIVE_*. Solo un entorno de desarrollo puede iniciar sin él.