Pix vía JD

Pix Directo vía JD convierte a tu institución en participante directo de Pix. Tu institución está presente por derecho propio en el sistema de liquidación (SPI) y en el directorio de claves (DICT) de BACEN. Se conecta mediante la infraestructura certificada de JD (JDPI). Tu institución es dueña de su participación en Pix, y JD provee la conectividad regulada con la red de BACEN. Si el riel te resulta nuevo, empieza por ¿Qué es Pix?. Explica las modalidades, el SPI, el DICT y los modelos de participación. Cuando otro motor de core bancario de tu institución usa el mismo canal JD y el mismo ISPB, JD Courier comparte el canal entre los motores. Todo lo que hace el riel es una sola API. Su especificación OpenAPI es la fuente de esta documentación. Cada operación lleva las reglas que un integrador no puede adivinar solo con el esquema.

​

El tenant y sus participantes directos

---

Un tenant contiene uno o más participantes directos. Por defecto, contiene la única institución que su vínculo nombra. Con el catálogo de organizaciones, puede contener las varias instituciones reguladas de un grupo económico. Cada una de ellas es participante directo por derecho propio, con sus propios libros. Consulta Multiorganización y ledgers. Cada llamada se autentica con las credenciales machine-to-machine del propio tenant. 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 un dato de enrutamiento. Decide sobre qué posición de liquidación se mueve el dinero. 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. Su llamante es el PSP del pagador, una parte que nunca registraste. El modelo directo e indirecto explica los dos tipos de participación. También muestra quién mantiene la cuenta de liquidación en el Banco Central, y dónde se aloja el dinero de cada institución hospedada.

​

El mapa de dominios

---

Cada dominio de abajo es una sección de la referencia de API. Esta página da una frase por dominio. La referencia tiene el contrato completo: cuándo llamar cada operación, qué lado la llama y qué rechaza. Cada enlace abre una operación típica de su sección.

• Entradas de claves: registra, cambia y elimina las claves Pix de tus cuentas en el DICT. También tiene la verificación por lotes y los dos flujos de eliminación masiva, para el cierre de cuenta y para la eliminación de titular.
• Reclamaciones de claves: el proceso de BACEN para tomar una clave de otro PSP. Cubre la portabilidad de tu propia clave y las reclamaciones de titularidad, con ambos lados de la negociación.
• 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. También tiene la superficie de lectura que cierra el ciclo.
• Devoluciones: la devolución de un pago que recibiste, iniciada por el receptor. Cada una es una fila de transacción nueva, limitada al monto original.
• Límites: límites de transacciones salientes por cuenta. El primer pago saliente de la cuenta los crea, y el riel los aplica 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. La introducción de la sección documenta las rutas anónimas del payload público y de JWKS.
• Créditos en espera: acredita, o devuelve a su pagador, un Pix recibido que el ledger no aceptó. Mira Pix recibido que espera a un operador.
• Webhooks: las rutas entrantes que JDPI llama en tu sistema. Cubren el cash-in, la devolución iniciada por el banco del receptor y la validación de cuenta, síncrona y asíncrona.
• Participantes indirectos: el registro de las instituciones que llegan al SPI a través de tu ISPB. Cubre su ciclo de vida, las posiciones de liquidación, los avisos de entrega y el feed de conciliación.
• MED 2.0: el mecanismo especial de devolución de BACEN. Cubre 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 el webhook de devolución, con código de devolución BE08 o FR01. Las listas de MED contienen solo los MED de los pagos que este riel registró o de las recuperaciones de valor que este riel abrió. Una solicitud de devolución o una recuperación de valor para cualquier otro pago responde 404 PIX-0063.
• Pix Automático: autorizaciones recurrentes, sus programaciones y códigos QR compuestos. También tiene las rutas 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. La documentación de la plataforma cubre sus rutas, y esta referencia no.

​

Órdenes de pago y devoluciones

---

Estas reglas aplican a todo cliente que envía dinero a través del riel:

• Envía el header X-Idempotency en cada orden de pago (POST /v1/transactions) y en cada devolución (POST /v1/refunds). Usa una cadena de negocio estable de 255 bytes o menos. Sin él, el riel responde 400 PIX-0061 antes de cualquier llamada al ledger o a JDPI.
• Un reenvío con una clave registrada no mueve dinero. Responde 409 PIX-0029. Una orden de pago con el endToEndId de una orden registrada recibe la misma respuesta. Lee el resultado de la primera solicitud con un GET.
• Un reenvío con la clave de una orden rechazada responde 409 PIX-0133. JD rechazó esa orden o nunca la recibió, así que no se movió dinero. Para pagar, envía una orden nueva con una clave nueva.
• La clave pertenece al pagador. El pagador es la organización que paga, más el participante indirecto en una orden o devolución indirecta. Dos pagadores pueden usar el mismo valor de clave.
• Una orden de pago no lleva la clave Pix del pagador. Un cuerpo con un campo key de nivel superior responde 400 PIX-0061. La clave del receptor, payee.key, no cambia.
• Una devolución de un Pix que recibió un participante indirecto lleva su indirectId. De lo contrario, el riel responde 422 PIX-0135. Consulta Participantes indirectos.
• Una orden de pago puede llevar una etiqueta de comisión en feeContext. La etiqueta selecciona el paquete de comisiones de Midaz que fija el precio del Pix. Una etiqueta rechazada responde 400 PIX-0061 o 422 PIX-0162, y no se retiene nada. Consulta Fija el precio de un TED o Pix con un contexto de comisión.
• Un débito de Pix Automático se contabiliza en la cuenta que nombra la autorización. Cuando la autorización no nombra ninguna cuenta, el débito usa la única cuenta del pagador. Un pagador con dos o más cuentas y sin cuenta en la autorización recibe 400 PIX-0061, antes de cualquier asiento.

​

Pix por clave a un tercero

---

Para pagar una clave Pix de cualquier institución, consulta primero la clave y paga con lo que devuelve la consulta:

1. Consulta la clave del receptor con Consultar una clave Pix antes de pagarla (GET /v1/entries/{entryId}/lookup). entryId es el valor de la clave, codificado para URL. account_id es la cuenta del pagador, la cuenta de la que sale el pago. La consulta al DICT se hace en nombre del pagador: el DICT la cuenta contra el CPF o CNPJ del pagador. Cuando este despliegue actúa como varios participantes directos, ispb nombra el que paga. Cuando el pago pasa por un participante indirecto, envía su indirectId, el mismo que lleva la orden de pago, y envía el CPF o CNPJ del pagador en el header X-Payer-Document en lugar de account_id. El DICT entonces genera el endToEndId bajo el ISPB de ese participante. Con indirectId, omite ispb.
2. Lee la respuesta. Devuelve un endToEndId y un bloque payee con exactamente los campos que espera POST /v1/transactions. El número de cuenta llega entero en payee.accountNumber, tal como lo devuelve el DICT, y payee.accountDigit llega vacío.
3. Paga con POST /v1/transactions, enviando ese endToEndId y ese payee tal como están. El pago va a JD como un pago iniciado por clave. Sin el endToEndId, sale como una orden digitada manualmente.

Una consulta sirve para un pago. Consulta la clave de nuevo antes de cada pago, y solo cuando el pagador esté por pagar: una consulta que no va seguida de un pago igual consume la cuota de DICT del pagador y de la institución. Para comprobar que existe una lista de claves, usa POST /v1/entries/verification. La consulta responde estos errores: El límite de consultas. Por defecto, un pagador puede hacer 100 consultas cada 60 segundos. El pagador es la cuenta en account_id, o el documento en X-Payer-Document, contado aparte para cada participante indirecto. El límite aplica siempre, aparte de los límites generales de solicitudes. El operador lo ajusta en el namespace de systemplane plugin-br-pix-jd.http, con las claves rate_limit.key_lookup.max y rate_limit.key_lookup.window_sec. Un pago por clave a un receptor de tu propia institución se verifica contra el DICT. Antes de que el pago se liquide en tu libro, el riel compara el ISPB, la agencia, la cuenta, el tipo de cuenta y el documento del receptor con la cuenta a la que el DICT vincula la clave. Un campo que difiere responde 422 PIX-0033, nombrando el campo, y no se mueve dinero. Envía el payee que devolvió la consulta y la verificación pasa.

​

Pix desde un código QR

---

Para pagar un código QR, decodifícalo primero con Decodificar código QR (POST /v1/qrcodes/decode). Luego paga con POST /v1/transactions y envía estos valores de la respuesta de la decodificación, sin cambiarlos:

• endToEndId, y la key decodificada como payee.key.
• qrCodeType: STATIC o DYNAMIC.
• txId: obligatorio para un código DYNAMIC, opcional para un código STATIC.

Para un receptor en otra institución, el pago va a JD como un pago por código QR, y el receptor lo concilia por su txId. Sin qrCodeType, el pago sale como un pago por clave. Una combinación inválida responde 400 PIX-0061 antes de que se retenga cualquier monto. Para un pago a través de un participante indirecto, la decodificación lleva su indirectId y el CPF o CNPJ del pagador en X-Payer-Document. Mira Declara al cliente del participante indirecto.

​

Pix recibido que espera a un operador

---

Cuando el ledger rechaza el crédito de un Pix recibido porque el saldo de destino no acepta créditos, el riel no registra nada. Responde a JD con 500 PIX-0151, y JD entrega el Pix de nuevo. GET /v1/transactions muestra el Pix como PENDING, con pendingReason BALANCE_NOT_RECEIVING. Una entrega posterior de JD, o la pasada de conciliación del riel, registra el crédito cuando el saldo empieza a aceptar créditos. Cuando tu Tracer rechaza el crédito en el ledger, por una regla, un límite o una revisión, el riel tampoco registra nada. Responde a JD con 500 PIX-4011, y JD entrega el Pix de nuevo. El Pix muestra pendingReason TRACER_DENIED. Una entrega posterior de JD registra el crédito cuando tu Tracer lo deja pasar. Este rechazo viene de la verificación de Tracer en el ledger, no del filtrado en la validación de cuenta. Para actuar antes, un operador de tu institución puede:

• Acreditar el Pix con Acreditar un Pix recibido en espera, una vez que el saldo acepte créditos y tu Tracer lo deje pasar. La ruta responde 200, con la transacción EXECUTED. Mientras tu Tracer rechaza el crédito, responde 422 PIX-4018.
• Devolver el Pix a su pagador con Devolver a su pagador un Pix recibido en espera. La devolución va por el SPI por el monto total, con el motivo BE08, y no registra nada en el ledger. La ruta responde 202, con la devolución PENDING. Si el ledger ya acepta el crédito, la acción acredita el Pix en su lugar y responde 409 PIX-0158. Cuando el SPI liquida la devolución, el Pix recibido pasa a ERROR, con pendingReason RETURNED.

Una devolución recibida de un Pix que enviaste solo se puede acreditar. Las dos acciones funcionan hasta 23 horas después de que llegó el Pix. Cuando el ledger rechazó el crédito porque el saldo no acepta créditos, porque tu Tracer lo rechazó, o porque el ledger no conoce la cuenta o la ruta contable, funcionan hasta 7 días menos 1 hora. Después, responden 409 PIX-0159. Necesitan el permiso parked-credits (acción post). Después de un 5xx, espera dos minutos y luego envía el crédito.

​

Débitos de Pix Automático que esperan

---

El SPI puede liquidar un débito de Pix Automático que el ledger del pagador luego rechaza. El riel responde a JD con un error que JD reintenta, y JD entrega el débito otra vez. El débito se registra cuando la causa desaparece. Listar débitos en espera de Pix Automático muestra estos débitos, del más nuevo al más antiguo, cada uno con su pendingReason:

• INSUFFICIENT_BALANCE: el pagador no tiene los fondos. Dale fondos al pagador.
• TRACER_DENIED: tu Tracer rechazó el débito, por una regla, un límite o una revisión. Comprueba esa regla, ese límite o esa revisión en Tracer.

Un débito sale de la lista cuando se registra. ispb restringe la lista a los pagadores de un participante directo. La lectura de un agendamiento por su endToEndId muestra el mismo pendingReason, y waitingSince.

​

Reclamaciones sobre las claves de tus clientes

---

Cuando otra institución reclama una clave que tiene tu cliente, respondes a la reclamación:

• Entrega la clave con Confirmar una reclamación de clave Pix. La clave queda en la cuenta de tu cliente hasta que el reclamante concluye la reclamación. Si la reclamación se cancela o vence, la clave vuelve a ACTIVE.
• Rechaza la reclamación con Cancelar una reclamación de clave Pix. El Bacen acepta el rechazo de una reclamación de posesión solo como una declaración de fraude, así que envía fraudDeclared true. Sin él, el riel responde 400 PIX-0061 y no envía nada al DICT. También puedes rechazar como fraude una reclamación de posesión que confirmaste, hasta su plazo de conclusión.

Para avisar a tu cliente cuando se abre una reclamación, define JOBS_CLAIM_RECEIVED_POLL_ENABLED=true para emitir key.claim-received.

​

Dinero: una API, dos unidades

---

El contrato propio de esta API da cada campo monetario como un conteo int64 de centavos. Por ejemplo, 110001 significa R$ 1.100,01. Esa regla cubre los cuerpos JSON, query, path y header. JDPI escribe algunos cuerpos: las rutas de webhook y las rutas entrantes, de liquidación y de eventos de Pix Automático. En esos cuerpos, cada campo monetario es un número JSON en reales (1100.01). Ese es el contrato de JD en los payloads que JD envía. El riel convierte a centavos en la frontera. El lado que escribió el cuerpo define la unidad, nunca el idioma del campo. Los campos con nombre en portugués en las superficies de escritura propias de esta API siguen llevando centavos enteros. La descripción de cada campo en la referencia indica su unidad.

​

Nombres de campo en inglés

---

En MED 2.0, Pix Automático y la consulta de clave, un campo que las versiones anteriores aceptaban con dos nombres, uno en inglés y uno en portugués obsoleto, ahora tiene solo su nombre en inglés. Por ejemplo: recoveryId (antes idRecValores), recurrenceId (antes idRecorrencia), cancellationId (antes idCancelamento), taxId (antes cpfCnpj) y payee.accountNumber en la consulta de clave (antes nrConta). La referencia da el nombre de cada campo.

• Un cuerpo de solicitud con un nombre en portugués se rechaza con 400 PIX-0061, como cualquier campo que la API no declara. No se registra nada. Envía el nombre en inglés.
• Un parámetro de query con un nombre en portugués se ignora. Un listado filtrado por él vuelve sin filtro. Verifica el nombre de cada filtro en la referencia.
• Las respuestas llevan cada campo una vez, con su nombre en inglés.
• Las rutas de recuperación de valores de MED son GET /v1/med/recoveries/awaiting-return y POST /v1/med/recoveries/{idRecValores}/return. Los paths awaiting-devolver y devolver ya no existen.

Los cuerpos que escribe JDPI mantienen los nombres de campo de JD: las rutas de webhook y las rutas de entrada, liquidación y eventos de Pix Automático.

​

Errores

---

Los errores son RFC 9457 application/problem+json. Cada error 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 lista de errores de Pix JD tiene cada código, con el detail exacto de cada uno.

​

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, tramos de efectivización de MED y la liquidación de Pix Automático. Midaz guarda el asiento. El registro de transacción del propio plugin guarda la identidad del pagador y del receptor (banco, agencia, cuenta, nombre y documento del titular, clave Pix) y toda referencia de BACEN. La correlación entre los dos sistemas funciona mediante identificadores. El plugin los escribe como metadatos en cada asiento de Midaz. Los metadatos que escribe el plugin guardan solo identificadores y clasificación, nunca montos, nombres ni documentos:

• En cada asiento: contractVersion (2), plugin (br-pix-direct-jd), rail (PIX), flow y aggregateId. flow es CASH_OUT, CASH_IN, P2P, REFUND, MED o AUTOMATIC_DEBIT. aggregateId es el identificador que el plugin da al movimiento.
• Cuando el movimiento los tiene: endToEndId, el ID E2E, y direction, IN u OUT. Un asiento REFUND también lleva originalAggregateId, el movimiento devuelto. Los asientos del pagador de una orden de pago con etiqueta de comisión llevan feeContext.

El plugin también 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. Cada asiento tiene una clave de idempotencia que se mantiene igual cuando el plugin reintenta la misma liquidación. Para ver el detalle bancario detrás de un asiento del ledger, consulta la API de transacciones del plugin por el id de transacción del plugin o por el ID E2E. El ledger se mantiene como contabilidad pura.

​

Informe a Bacen de un Pix liquidado en tus libros

Un Pix entre dos cuentas de tu institución se liquida en tus libros y no pasa por el SPI. El riel informa cada pago y cada devolución de este tipo a Bacen a través de JD. Consultar el estado de la transacción (GET /v1/transactions/{transactionId}) muestra el informe en el campo internalSettlementReport. El campo aparece solo para ese tipo de Pix después de que llega a EXECUTED. Su status es uno de estos valores: Para un informe en REJECTED o INCOMPLETE, abre un ticket en el Lerian Support Portal.

​

Por dónde empezar

---

1. Configurar el riel: el recorrido de configuración, en el orden en que actúas, para un servicio que ya funciona. Cubre los requisitos previos, la firma de órdenes de pago, el ledger de Midaz y los registros del CRM, las rutas contables, los ajustes del plugin y las verificaciones que prueban cada paso. Síguelo de arriba abajo.
2. Firma de la orden de pago: el paso 2 del recorrido, solo si JD exige órdenes de pago firmadas para tu institución.
3. Variables de entorno: las variables de despliegue del servicio, con su formato y su valor predeterminado.
4. El modelo directo e indirecto: los dos tipos de participación, y dónde se aloja el dinero de un participante indirecto. Después lee Hospedar participantes indirectos, con los pasos adicionales para un despliegue que liquida Pix para otras instituciones. Omite ambos si liquidas solo el Pix de tus propios clientes.
5. La referencia de API: elige tu dominio en el mapa de arriba. Cada enlace abre una operación típica de su sección.