Todo lo que en estas páginas aprovisiona o configura el riel describe un despliegue single-tenant, donde tu equipo opera el servicio. En la oferta multi-tenant gestionada de Lerian (SaaS), todo lo específico del cliente — las credenciales de JD, el dominio público de QR, el vínculo con el ledger de Midaz, la conexión con el CRM y cada servicio con el que habla el riel — lo aprovisiona y lo resuelve la plataforma automáticamente, por tenant. No hay nada que configures más allá de tu propia integración.
Un tenant, un participante directo
Un tenant es un participante directo. Cada llamada se autentica con las credenciales machine-to-machine del propio participante directo, y el tenant viene del bearer validado — nunca de un payload ni de una ruta. Las instituciones que hospedas como participantes indirectos viven dentro de tu tenant y nunca tienen credenciales propias. El id de un indirecto en una solicitud es dato de enrutamiento: decide sobre qué posición de liquidación se mueve el dinero, y la garantía de que la solicitud realmente pertenece a esa institución te toca darla a ti antes de enviarla. La única excepción anónima son las rutas del payload público de QR y de JWKS, cuyo llamante es el PSP del pagador — una parte que nunca se registró contigo.
El mapa de dominios
Cada dominio de abajo es una sección de la referencia de API. Una sola frase aquí; la referencia lleva el contrato completo — cuándo se llama cada operación, desde qué lado y qué rechaza. Cada enlace lleva a una operación representativa de su sección.
- Entradas de claves — registra, cambia y elimina las claves PIX vinculadas a tus cuentas en el DICT, además de la verificación por lotes y los dos flujos de eliminación masiva (cierre de cuenta y eliminación de titular).
- Reclamaciones de claves — el proceso de BACEN para tomar una clave de otro PSP: portabilidad de tu propia clave, o una reclamación de titularidad, con ambos lados de la negociación expuestos.
- Bancos — el catálogo nacional de participantes del SPI, leído en vivo desde JDPI.
- Transacciones — pagos salientes, por SPI (de dos fases, asíncronos) o liquidados en tu propio libro cuando el receptor es on-us, además de la superficie de lectura que cierra el ciclo.
- Devoluciones — devolución de un pago que recibiste, iniciada por el receptor, siempre una fila de transacción nueva limitada al monto original.
- Límites — límites de transacciones salientes por cuenta, inicializados por el primer pago saliente de la cuenta y aplicados antes de que se mueva dinero.
- Códigos QR — códigos estáticos y dinámicos inmediatos con payloads firmados de alojamiento propio, decodificación y listado; las rutas anónimas del payload público y de JWKS se documentan en la introducción de esa sección.
- Webhooks — el espejo entrante que JDPI llama en tu sistema: cash-in, devolução iniciada por el banco del receptor y validación síncrona de cuenta.
- Participantes indirectos — el registro de las instituciones que llegan al SPI a través de tu ISPB: ciclo de vida, posiciones de liquidación, avisos de entrega y el feed de conciliación.
- MED 2.0 — el mecanismo especial de devolución de BACEN: informes de infracción, solicitudes de devolución en ambos roles, recuperaciones de valor del lado del creador y marcadores de fraude; el crédito de una devolución que ganaste llega en su propio webhook, bajo MED Inbound Credit.
- Pix Automático — autorizaciones recurrentes, las programaciones que las sustentan, códigos QR compuestos y los tramos entrantes de registro, liquidación y eventos que JDPI llama en tu sistema.
- Systemplane — la superficie de configuración en tiempo de ejecución para operadores; los clientes de pagos nunca la necesitan. Sus rutas se documentan con la plataforma, no como una sección de esta referencia.
Dinero: una API, dos unidades
Cada campo monetario del contrato propio de esta API es un conteo int64 de centavos —
110001 significa R$ 1.100,01 — tanto en cuerpos JSON como en query, path y header. Cada campo monetario de un cuerpo escrito por JDPI — los espejos de webhook, el crédito entrante de MED y las rutas entrantes, de liquidación y de eventos de Pix Automático — es un número JSON en reales (1100.01), porque ese es el contrato de JD en los payloads que JD envía; el riel convierte a centavos en la frontera. El discriminador es qué lado escribió el cuerpo, nunca el idioma del campo: los campos con nombre en portugués en las superficies de escritura propias de esta API siguen siendo centavos enteros. La descripción de cada campo en la referencia indica su unidad.
Errores
Los errores son RFC 9457
application/problem+json, y cada uno lleva un código de taxonomía PIX-XXXX en el miembro code — haz coincidir por el código, nunca por el texto legible. La disciplina de estados es de atribución: un 4xx significa que lo que falló es la solicitud, o los datos que la solicitud nombra, y el cuerpo nombra el campo o la entidad; un 5xx nombra la dependencia que falla (por ejemplo 503 PIX-1050, JDPI temporalmente no disponible) en lugar de esconderse detrás de un error genérico. El catálogo completo, con el detail exacto que lleva cada código, es la lista de errores de Pix JD.
Cómo llegan los movimientos Pix a Midaz
El plugin de participación directa registra cada movimiento Pix liquidado en Midaz como una transacción del ledger. El tramo externo va contra la cuenta de compensación (por ejemplo,
@external/BRL). Los movimientos liquidados incluyen cash-out, cash-in, devoluciones (devolução), tramos de efectivización de MED y la liquidación de Pix Automático. Midaz guarda el asiento. La identidad del pagador y del receptor (banco, agencia, cuenta, nombre y documento del titular, clave Pix) vive solo en el registro de transacción del propio plugin. Toda referencia de BACEN vive solo en ese registro.
La correlación entre los dos sistemas funciona mediante identificadores, no metadatos:
- El ID end-to-end (E2E) es la clave de idempotencia del asiento de Midaz, por lo que una liquidación reintentada nunca puede registrar dos veces en el ledger. Los tramos posteriores del mismo E2E (una devolução o una efectivización de MED) derivan su clave del E2E con un sufijo de flujo. Nunca chocan con el asiento original.
- El plugin guarda el ID del asiento de Midaz en su propio registro de transacción. Usa ese ID para confirmar o cancelar el débito pendiente de un cash-out de dos fases.
Por dónde empezar
- Configurar el riel — la cadena de aprovisionamiento, en orden: el ledger de Midaz y los registros del CRM, las veinte rutas contables, las claves del systemplane que llevan tu ISPB y la verificación que prueba que cada paso quedó aplicado.
- Hospedar participantes indirectos — los tres pasos adicionales de aprovisionamiento para un despliegue que liquida Pix en nombre de otras instituciones. Omítelo si liquidas solo el Pix de tus propios clientes.
- Variables de entorno — la configuración del momento del despliegue: la conectividad con JD, los endpoints del ledger y del CRM, el alojamiento de QR y los proveedores de notificaciones.
- La referencia de API — elige tu dominio en el mapa de arriba; cada enlace lleva a una operación representativa de su sección.
Lerian aprovisiona la configuración específica del proveedor para la participación directa vía JD junto con tu integración. Para configurar la participación directa en Pix, ponte en contacto con nuestro equipo.