Para el usuario, Pix puede parecer una única acción: escanear un código QR, confirmar en la aplicación del banco y ver la pantalla de pago completado. Sin embargo, para la infraestructura del destinatario existe una secuencia de objetos, identificadores, estados y eventos que debe modelarse con cuidado.
Solicitud de pago, código QR, Pix recibido, txid, EndToEndId, devolución y webhook no son palabras distintas para lo mismo. Cada concepto representa una parte del flujo. Cuando la integración mezcla estas capas, aparecen problemas como pedidos liberados demasiado pronto, pagos recibidos sin pedido correspondiente, devoluciones sin trazabilidad y reprocesamiento de eventos.
Entender el ciclo de Pix es especialmente importante porque es un método de pago instantáneo, pero eso no significa que toda la arquitectura que lo rodea sea síncrona ni que la aplicación pueda depender de una única respuesta HTTP.
¿Pix es una transferencia o un flujo de cobro?
Puede presentarse al usuario como una transferencia instantánea, pero una integración comercial suele necesitar un flujo de cobro alrededor del pago.
La empresa debe representar la intención de cobrar, el importe, el vencimiento y la referencia de negocio, y después confirmar si se recibió realmente el Pix correspondiente.
El pago en sí es un evento financiero. La solicitud de pago es el contexto comercial que prepara y organiza ese evento.
Separar ambos es esencial para conciliar pedidos e ingresos.
¿Qué es una solicitud de pago Pix?
La solicitud de pago es un objeto que representa una petición de pago con reglas e información que permiten generar o asociar un código QR.
Según el caso, puede ser de pago inmediato o tener fecha de vencimiento, además de los atributos propios del flujo utilizado.
Desde el punto de vista arquitectónico, la solicitud responde a algo parecido a «¿qué queremos recibir?».
El Pix recibido responde «¿qué se ha liquidado realmente?».
La aplicación no debería confundir una intención con un hecho financiero.
¿Qué es txid?
El txid es un identificador asociado a la solicitud de pago y cumple una función importante al correlacionar el contexto creado por el destinatario con el Pix recibido.
No debe tratarse solo como un detalle visual del código QR.
Bien utilizado, ayuda a vincular solicitud, pedido, confirmación y conciliación.
La empresa sigue necesitando sus propios identificadores internos, pero txid se convierte en un enlace importante dentro del ecosistema Pix.
¿txid es lo mismo que EndToEndId?
No.
El txid está vinculado a la solicitud y al contexto definido en el flujo del destinatario.
EndToEndId identifica el Pix efectivamente procesado en el sistema y acompaña al evento financiero.
Esta separación resulta útil porque la solicitud se crea antes del pago, mientras que el identificador de extremo a extremo aparece asociado a la transacción realizada.
Para conciliar y devolver importes, saber qué identificador pertenece a cada capa evita muchas confusiones.
¿Qué es un código QR estático?
El código QR estático es un formato en el que determinados datos de pago se representan directamente en la carga de datos y pueden reutilizarse según el caso de uso.
Puede resultar útil en situaciones sencillas, como la recepción habitual de pagos en un punto físico, pero ofrece menos control dinámico sobre cada intención comercial.
Si varias ventas utilizan el mismo QR, la aplicación necesita otra estrategia para identificar qué pago pertenece a cada pedido.
Por eso, la sencillez al generarlo puede implicar más complejidad al conciliar.
¿Qué es un código QR dinámico?
El código QR dinámico permite dirigir el flujo a información de cobro asociada a una intención concreta.
Esto facilita controlar el importe, la validez, la referencia y el estado de la solicitud.
Para comercio electrónico e integraciones automatizadas, este modelo suele resultar más natural, porque cada pedido puede tener su propia solicitud y una correlación explícita.
El código QR es solo la forma de iniciación para el pagador. La verdad de negocio sigue estando en los objetos y eventos que observa la aplicación.
¿Un código QR dinámico garantiza el pago?
No.
Generar el código QR no significa recibir el dinero.
La aplicación debe esperar pruebas de que se ha recibido realmente un Pix asociado.
Es el mismo principio que se aplica a otros medios de pago: crear una intención no equivale a completar el efecto financiero.
¿Cómo cambia de estado una solicitud de pago?
Las solicitudes tienen sus propios estados.
Una solicitud puede estar activa, ser eliminada por el destinatario y, cuando se recibe un Pix asociado al txid dentro del flujo aplicable, alcanzar el estado completado.
Una solicitud completada representa un hecho diferente de una que solo se ha creado.
El sistema comercial debe reaccionar al evento correcto, no a la existencia del código QR.
¿Es posible eliminar una solicitud de pago?
Sí. Conforme al flujo y a las reglas aplicables, el destinatario puede eliminar una solicitud todavía válida.
Esto resulta útil cuando el cliente desiste, el pedido caduca o la empresa decide que esa intención ya no debe pagarse.
Una solicitud completada no debe tratarse como un objeto desechable, porque existe un Pix asociado que debe seguir siendo rastreable.
Después del pago, la lógica deja de ser «eliminar la solicitud» y pasa a implicar una devolución cuando corresponda.
¿Caducar y eliminar son lo mismo?
No exactamente.
La caducidad deriva de la ventana temporal definida para la solicitud o del producto Pix utilizado.
La eliminación es una acción del destinatario para invalidar una solicitud que todavía podría estar disponible.
Para la aplicación, ambos casos pueden impedir una nueva iniciación válida, pero la causa y la transición son diferentes.
Esta diferencia importa para la atención al cliente y la auditoría.
¿Qué ocurre si el cliente paga después de que caduque el pedido?
Es uno de los escenarios que más ponen a prueba una integración.
El pedido comercial puede caducar antes de que el cliente complete el proceso en la aplicación pagadora. Según el estado real de la solicitud y la forma de iniciación, la aplicación debe estar preparada para gestionar un Pix recibido en un contexto comercial que ya ha cambiado.
La regla correcta no es ignorar el dinero.
El sistema debe reconocer el ingreso, correlacionarlo en la medida de lo posible y decidir si reabre el pedido, crea una excepción operativa o inicia una devolución conforme a la política del negocio.
¿Cómo confirmar que se ha recibido un Pix?
La confirmación debe proceder de pruebas del PSP del destinatario o de la infraestructura integrada.
Puede llegar mediante una notificación asíncrona y también mediante una consulta de Pix recibidos a través de las interfaces disponibles.
La aplicación no debería depender de que el navegador del cliente vuelva a la página de confirmación.
El cliente puede cerrar la pantalla, perder la conexión o completar el pago en otro dispositivo.
El hecho financiero existe independientemente de la sesión web.
¿Cuál es la función del webhook en Pix?
El webhook permite avisar a la aplicación cuando se produce un evento Pix relevante.
Esto reduce la necesidad de consultar continuamente al PSP para saber si se ha pagado la solicitud.
Pero el webhook no debe tratarse como un mensaje que «manda» sobre el estado sin validación.
Los eventos pueden reenviarse. La aplicación debe procesarlos de forma idempotente y correlacionarlos con el objeto correcto.
¿Puede llegar un webhook duplicado?
Sí, y el sistema debe asumir que la duplicidad es posible en cualquier integración asíncrona fiable.
Si el mismo evento se entrega más de una vez, volver a procesarlo no debería liberar dos pedidos, abonar dos veces un saldo ni iniciar dos devoluciones.
La estrategia suele combinar los identificadores del evento o de la transacción con controles de idempotencia.
¿Y si el webhook no llega?
La ausencia de webhook no debería hacer invisible un Pix para siempre.
Una rutina de conciliación o consulta puede descubrir pagos que no se reflejaron localmente por un fallo de entrega, una indisponibilidad o un error de procesamiento.
El webhook acelera la sincronización. La conciliación garantiza la integridad del registro.
Depender exclusivamente de una notificación debilita el cierre financiero.
¿Qué es EndToEndId en la práctica?
EndToEndId actúa como referencia esencial del Pix efectivamente procesado.
Ayuda a identificar la transacción en el ecosistema y aparece en operaciones posteriores, incluidos los flujos de devolución.
Para el comercio, esto significa conservar el identificador junto con la solicitud de pago y la entidad financiera interna.
Perderlo dificulta las investigaciones futuras.
¿Cómo funciona una devolución Pix?
La devolución es una operación asociada a un Pix original.
La aplicación identifica la transacción recibida e inicia una devolución con un identificador propio, dentro de las reglas de la API utilizada.
Un mismo Pix puede admitir varias devoluciones, siempre que el total devuelto respete los límites aplicables y no supere el importe original.
Así surge de forma natural el concepto de devolución parcial.
¿Devolver es lo mismo que cancelar un Pix?
No.
Una vez procesado el Pix, no existe una función de «deshacer» que borre la transacción original.
La devolución es un nuevo movimiento vinculado al Pix recibido.
Esta distinción importa para el historial y la contabilidad.
La transacción original sigue existiendo; la devolución registra el movimiento inverso posterior.
¿Cómo funciona una devolución parcial?
Si de una compra de R$ 500 solo hay que devolver R$ 120, la aplicación puede crear una devolución parcial cuando el flujo admitido lo permita.
El resto del importe sigue asociado al Pix original.
Esto significa que el sistema no debería modelar solo «devuelto: sí o no».
Debe seguir el importe recibido, el importe ya devuelto y el saldo todavía elegible para devolución.
¿Puede haber varias devoluciones para el mismo Pix?
Sí, dentro de las reglas y los límites aplicables.
Esta posibilidad hace aún más importante el modelado.
Cada devolución necesita su propia identidad y su propio estado, mientras todas siguen vinculadas al Pix original.
Sin esa separación, una segunda devolución puede sobrescribir la primera o la aplicación puede perder la suma ya devuelta.
¿Solicitar una devolución significa que ha terminado?
No necesariamente.
Como en otras operaciones financieras, la aplicación debe distinguir la solicitud de la finalización.
El flujo puede exigir una consulta posterior del estado o la recepción de una actualización.
Marcar inmediatamente como «devuelto» sin confirmación puede crear una discrepancia entre el sistema y el movimiento real.
¿Cómo evitar devolver más de lo recibido?
El dominio debe calcular el importe todavía disponible para devolución.
Este cálculo debe considerar todas las devoluciones completadas y, según la política, las operaciones en curso que reservan parte del importe.
Confiar solo en el formulario de atención al cliente no basta.
La regla debe residir en la capa financiera que controla el objeto.
¿Qué es una solicitud de pago inmediato?
Una solicitud de pago inmediato representa un flujo en el que se espera el pago sin la fecha futura propia de una solicitud con vencimiento.
Es habitual en checkout, puntos de venta y recorridos en los que el cliente paga en ese momento.
Aunque sea «inmediata», sigue habiendo una diferencia entre crear la solicitud, mostrar el QR y recibir el Pix.
¿Qué es una solicitud con vencimiento?
La solicitud con vencimiento incorpora una lógica temporal y comercial diferente.
Puede representar una obligación pagadera hasta una fecha determinada e incluir reglas que no tienen sentido en un checkout instantáneo.
La aplicación debe elegir el objeto adecuado al caso de uso, en lugar de tratar todo Pix como el mismo flujo.
Cuando el objetivo sea cobrar ciclos sucesivos mediante autorización previa, consulta la guía de autorización y cancelación en Pix Automático, que distingue este servicio de la solicitud Pix puntual.
¿Pix es siempre instantáneo desde el punto de vista del comercio?
El esquema se diseñó para pagos instantáneos, pero la percepción de la aplicación depende de la integración, la notificación y el procesamiento interno.
Un Pix puede completarse en el ecosistema y tardar unos segundos en aparecer en el sistema del comercio si el webhook llega con retraso.
Ese intervalo basta para generar condiciones de carrera cuando el checkout consulta el estado al mismo tiempo que llega el evento.
Por eso, el sistema debe ser idempotente.
¿Cómo gestionar una condición de carrera entre consulta y webhook?
Imagina que el checkout consulta la solicitud y descubre el pago completado justo cuando llega el webhook.
Dos procesos pueden intentar marcar el pedido como pagado.
Si la transición no es idempotente, la aplicación puede ejecutar dos veces las acciones de cumplimiento del pedido.
El estado del pago y la orden de liberación deben admitir una repetición segura.
¿Debe el pedido tener el mismo estado que la solicitud Pix?
No.
El pedido y la solicitud pertenecen a dominios distintos.
La solicitud puede estar creada mientras el pedido espera el pago. Cuando se recibe el Pix, el pago cambia de estado y el pedido decide qué hacer: reservar existencias, conceder acceso, iniciar la expedición u otra acción.
Esta separación permite gestionar devoluciones sin confundir necesariamente el estado comercial del pedido.
¿Qué ocurre si el importe recibido es inesperado?
La arquitectura debe tratarlo como una excepción explícita.
Según el flujo, la solicitud puede imponer un importe concreto. En otros contextos, especialmente con formas de iniciación más abiertas, la empresa puede recibir un Pix cuyo importe no corresponda al pedido esperado.
El sistema no debería forzar silenciosamente la correspondencia.
Es mejor registrar el evento y enviarlo a una regla de tratamiento o conciliación.
¿Cómo conciliar Pix?
La conciliación parte de los identificadores y los importes.
La solicitud interna debe estar vinculada al txid. El Pix recibido debe conservar EndToEndId, importe y marcas de tiempo. El movimiento financiero interno debe apuntar a esos registros.
Después, la empresa puede saber qué solicitudes se pagaron, qué Pix no encontraron contexto, qué devoluciones se produjeron y qué diferencias siguen abiertas.
¿Qué es un Pix huérfano?
Es un ingreso que el sistema no puede asociar automáticamente a una intención de negocio conocida.
Puede ocurrir por una referencia ausente, una integración paralela, un pago fuera del flujo esperado o una incoherencia operativa.
El dinero no debe ignorarse.
La conciliación debe registrarlo e investigarlo hasta clasificar el movimiento.
¿Cómo se diferencia Pix de la tarjeta en una máquina de estados?
Las tarjetas suelen tener la autorización y la captura como conceptos centrales.
No debe obligarse a Pix a imitar ese modelo.
El recorrido resulta más natural cuando la aplicación representa la solicitud de pago, espera el ingreso, confirma el Pix y después sigue las posibles devoluciones.
Una abstracción multimétodo debe compartir conceptos como intención, intento, éxito y devolución, sin inventar una captura donde no existe.
¿Cómo encaja Pix en una plataforma multi-PSP?
Una capa de pagos puede ofrecer una interfaz coherente para crear solicitudes, consultar estados, recibir eventos e iniciar devoluciones.
Pero debe conservar las particularidades de Pix, como txid, EndToEndId y la semántica de las solicitudes de pago.
Una buena abstracción reduce el esfuerzo de integración sin borrar los conceptos esenciales del método.
¿Qué debe ser idempotente?
La creación de operaciones con efectos financieros o comerciales debe protegerse frente a repeticiones accidentales.
El procesamiento de webhooks, la confirmación del pago, el cumplimiento del pedido y las devoluciones son ejemplos claros.
Si un evento se entrega dos veces, el sistema debe reconocer que representa el mismo hecho.
Si un operador pulsa dos veces «devolver», la capa financiera no debería ejecutar dos devoluciones independientes sin una intención explícita.
¿Cómo gestionar un timeout al crear una solicitud de pago?
La aplicación debe saber si la llamada falló antes o después de que el PSP creara el objeto.
Cuando el resultado es incierto, crear inmediatamente otra solicitud puede duplicar la intención.
Los identificadores idempotentes y las consultas posteriores ayudan a resolver esta ambigüedad.
El principio es el mismo que en otras API financieras: la ausencia de respuesta no demuestra la ausencia de efectos.
¿Cómo gestionar un timeout en una devolución?
Con aún más cuidado, porque existe un efecto financiero.
Si la solicitud salió y se perdió la respuesta, repetirla sin consultar el estado puede crear una nueva devolución, según cómo utilice los identificadores la integración.
El identificador de la devolución debe ser estable para esa intención, y el sistema debe verificar el resultado antes de crear otra operación.
¿Cómo observar una operación Pix?
Entre las métricas útiles están el tiempo entre creación y pago, la tasa de caducidad, los pagos huérfanos, el retraso de los webhooks, los fallos de correlación, las devoluciones, las diferencias de importe y la latencia de las API implicadas.
También es importante diferenciar los problemas del pagador, los del PSP y los de la propia aplicación.
Sin esa separación, todo pago incompleto se convierte en un «fallo de Pix».
¿Qué no debería registrarse en los logs?
La observabilidad no debe convertirse en una recopilación indiscriminada de datos sensibles.
El equipo debe registrar identificadores, estados, tiempos, resultados normalizados y la información necesaria para investigar, respetando la minimización de datos y las políticas de seguridad.
Guardar siempre la carga de datos original completa rara vez es la mejor estrategia permanente.
¿Necesita Pix una pantalla de «esperando el pago»?
En comercio electrónico, normalmente sí.
La experiencia debe dejar claro que mostrar el QR no significa que el pago esté confirmado.
La interfaz puede actualizar el estado automáticamente cuando llega el evento o consultarlo periódicamente dentro de límites razonables.
Lo importante es que el frontend refleje la verdad financiera que conoce el backend.
¿Puede el navegador ser la fuente de verdad?
No.
La confirmación debe existir en el servidor.
El navegador es solo una interfaz de presentación y puede desaparecer en cualquier momento.
Si la aplicación depende de una acción del cliente después de pagar para registrar el resultado correcto, inevitablemente perderá eventos.
¿Cómo evitar liberar dos veces el mismo pedido?
La transición «pago confirmado» debe tratarse como un evento idempotente.
Aunque webhook, polling y consulta manual descubran el mismo Pix, todos deben converger en un único efecto comercial.
Puede implementarse mediante control de estado, una clave única y una transacción en la base de datos.
Cuando boleto y Pix ofrecen vías para saldar la misma obligación, hay que coordinar los instrumentos y tratar los ingresos adicionales. La guía de boleto con Pix y prevención de duplicidades desarrolla este caso, incluida la cancelación cruzada y la conciliación.
¿Cómo cambia Pix el diseño del checkout?
En muchos casos separa claramente los dispositivos: el cliente compra en el ordenador y paga en el móvil.
Esto significa que una redirección del navegador no basta para confirmar el pago.
El checkout debe orientarse a estados y eventos.
La página solo observa el backend y muestra lo que este sabe.
¿Cómo gestionar el abandono?
Si el usuario genera el QR y nunca paga, la solicitud debe caducar o eliminarse según las reglas del flujo.
La empresa puede medir ese abandono para mejorar la experiencia, pero no debería confundir la generación de una solicitud con un intento financiero completado.
También importa para las métricas de conversión: el denominador debe estar bien definido.
¿Cómo gestionar un reembolso después de cancelar el pedido?
Primero, confirma que se recibió un Pix y qué importe sigue siendo reembolsable.
Después, crea la devolución vinculada a la transacción correcta.
El pedido comercial puede cambiar antes o después de la devolución, pero la operación financiera debe tener vida propia.
Separar los dominios evita que cancelar el pedido borre pruebas del dinero ya recibido.
¿Qué estandariza el Banco Central y qué abstrae el PSP?
El ecosistema Pix tiene reglamentos, manuales e interfaces técnicas definidos por el Banco Central do Brasil y los participantes del esquema.
Los PSP pueden ofrecer API propias que encapsulan parte de esta complejidad para los comercios.
Esto significa que los nombres de endpoints y objetos visibles para el comercio pueden variar, aunque la infraestructura subyacente siga Pix.
Una plataforma debe conocer esa diferencia para no confundir el contrato del PSP con un concepto universal del esquema.
¿Cómo diseñar un dominio Pix robusto?
Empieza representando la intención de cobro, la solicitud externa, el Pix recibido y la devolución como entidades relacionadas, pero distintas.
Conserva txid y EndToEndId en los contextos adecuados.
Modela los estados intermedios. Trata los webhooks como eventos repetibles. Utiliza consultas y conciliación para recuperar pérdidas de información. Controla los importes devueltos.
Este diseño parece más elaborado que guardar simplemente «pix_status». En producción, reduce las excepciones.
¿Cuál es la diferencia entre solicitud de pago, Pix y devolución?
La solicitud representa lo que el destinatario pretende recibir.
Pix representa el pago efectivamente procesado.
La devolución representa un movimiento posterior vinculado al Pix original.
El código QR es un mecanismo de iniciación, no el pago en sí.
El webhook es un mecanismo de notificación, no la fuente exclusiva de verdad.
Estas distinciones constituyen la base de una integración fiable.
Pix instantáneo también exige arquitectura
La velocidad del esquema no elimina los estados, los eventos ni los fallos distribuidos.
Al contrario: cuando el dinero cambia de estado en segundos, la aplicación debe reaccionar correctamente sin depender de suposiciones.
Una implementación robusta distingue solicitud y pago, conserva identificadores, procesa eventos con idempotencia, concilia lo que no llegó y trata la devolución como una operación financiera independiente.
Eso es lo que convierte un código QR funcional en infraestructura de pagos fiable.