pacs.004 saliente antes de enviarlo, y un fallo de registro no bloquea necesariamente el despacho. Las operaciones devuelven un estado aceptado-pero-no-liquidado y reconcilian contra la respuesta asíncrona del BACEN.
Habilitación y disponibilidad
Registras un participante por su ISPB. Un participante indirecto entra en
PENDING; el riel envía su solicitud de registro, y solo la confirmación del BACEN puede activarlo. La acción de activación solo reactiva a un participante que ya estaba suspendido. El riel ejecuta la disponibilidad en un orden obligatorio. Una prueba de conectividad aprobada es el prerrequisito para un envío.
- Sube un certificado Pix —solo el
.cerpúblico—. El riel rechaza una clave privada subida. - Confirma que el riel reporta que está listo.
- Pasa una prueba de conectividad.
- Ya puedes enviar pagos.
Enviar un Pix
Creas una orden de pago. La plataforma construye el mensaje ISO 20022 de transferencia de crédito (
pacs.008), persiste la operación y la despacha. El BACEN devuelve un callback de estado asíncrono (pacs.002). El riel lo valida y lo aplica, y luego mueve el pago a completed o rejected. Lees un pago por su end-to-end ID, con su historial y una línea de tiempo por operación.
Recibir un Pix
El consumidor ICOM recibe mensajes firmados del BACEN y los pasa a la entrada interna autenticada del riel. Para un
pacs.008 entrante, el riel valida el mensaje y registra el Pix como pendiente. Luego el cliente aporta la decisión de fondeo para ese Pix ya recibido. Un pago saliente no puede fondearse como dinero entrante. Los participantes listan los Pix que reciben.
Devolución
Inicias una devolución (
pacs.004) solo para un Pix liquidado que el riel recibió del BACEN y luego lees su estado. 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 la devolución de ese Pix y llega al riel como 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 completada o un error.
Existen dos superficies de devolución, y el riel registra cuál de ellas creó cada devolución en vez de inferirlo después. Una devolución integral revierte el Pix completo y mueve el pago padre fuera de completed. Una devolución parcial se identifica por el devolucaoId que eliges y nunca mueve el pago padre. Varias devoluciones parciales pueden coexistir para un mismo Pix.
Tres controles aplican a toda devolución, en ambas superficies:
- El pago padre debe ser un Pix entrante que liquidó. Solo un pago recibido que llegó a
completed—o que ya lleva una devolución— puede devolverse. - La ventana de devolución de BACEN. Una devolución debe solicitarse dentro de 90 días de la liquidación original del Pix, y el riel mide la ventana desde el instante de la liquidación, nunca desde la creación ni desde la última actualización. Un Pix sin instante de liquidación registrado no se bloquea: el riel registra el vacío y reenvía la solicitud.
- El techo de la suma. La suma de los valores de todas las devoluciones de un Pix no puede superar el valor de ese Pix. El riel lee solo el importe de ese pago y sus propias devoluciones; no calcula ninguna posición entre pagos.
EM_PROCESSAMENTO y llega a DEVOLVIDO o NAO_REALIZADO solo con la respuesta de BACEN —una aceptación de transporte no es una conclusión. Una devolución que falla libera el techo que retenía, y una devolución integral que falla devuelve el pago padre a completed sin rearmar su ventana de 90 días.
Solicitas una devolución como ORIGINAL (el valor por omisión cuando no envías naturaleza) o RETIRADA, la pata de Pix Saque y vuelto. Las dos naturalezas de MED —falla operativa y sospecha de fraude fundada— existen solo del lado de la respuesta: se derivan del motivo que el riel pone en el pacs.004, y nunca las pides.
Ciclo de vida de las claves DICT
Gestionas las claves Pix directamente contra el directorio DICT: registrar, listar, buscar, consultar, actualizar y eliminar una clave. También verificas por lote si un conjunto de claves existe. El riel lee las estadísticas de claves de DICT y las estadísticas antifraude del BACEN, tanto por clave como por persona.
Reivindicaciones de DICT
Una reivindicación mueve una clave Pix entre participantes por portabilidad o titularidad. Inicias una reivindicación contra un participante y luego la mueves por su ciclo de vida. El ciclo de vida abarca acknowledge, confirmar o rechazar, y completar o cancelar, entre los lados donante y reclamante. Cuando tanto
SCHEDULER_ENABLED=true como SCHEDULER_CLAIM_DEADLINE_ENABLED=true, el riel registra el procesamiento periódico de los plazos de las reivindicaciones. Intenta hacer avanzar las reivindicaciones según sus ventanas del BACEN, pero una reivindicación aún puede requerir atención.
BR Code y cobros
Un QR dinámico resuelve a un cobro persistido, así que creas el cobro primero y luego generas el payload que resuelve a é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 intereses y multa) o un lote de cobros con vencimiento.
- Genera el payload QR EMV dinámico, que enlaza al cobro por su txid o localizador y resuelve como un JWS firmado.
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.
Disputas MED
La superficie MED (Mecanismo Especial de Devolução) tramita casos de fraude y error de extremo a extremo:
- Abre un caso MED, analízalo y luego resuélvelo, ciérralo o cancélalo con evidencia adjunta.
- Presenta reportes de infracción, solicitudes de devolución, marcas de fraude y solicitudes de recuperación de fondos de DICT, cada una rastreada a lo largo de su grafo de ciclo de vida.
- Reporta los Pix liquidados internamente mediante el reporte de liquidación de MED 2.0.
Reporte de la Conta PI
Solicitas un reporte de cuenta (
camt.060) y luego lees el saldo (camt.053), el extracto (camt.052) o el detalle de asientos (camt.054) que devuelve el BACEN. Los reportes síncronos de volumetria (solo conteo), pagos rechazados, saldo y extracto completan la superficie de reporte, cada uno acotado a su período de referencia.