Para evitar duplicidades en un cobro con boleto y Pix, representa una única obligación comercial, conserva la identidad de cada instrumento y confirma los ingresos en el servidor. Garantiza que solo una confirmación salde el pedido y autorice la entrega. Después, sigue la cancelación del instrumento alternativo y concilia cualquier importe adicional recibido. Ocultar el código QR o el código de barras en pantalla no basta para impedir un segundo pago.
El reto aparece cuando el dinero y los mensajes siguen caminos distintos. El cliente puede pagar por un canal mientras el otro todavía aparece disponible. Una confirmación puede llegar después de otra aunque represente un pago anterior. La integración debe explicar estos acontecimientos sin duplicar entregas, borrar ingresos ni devolver el importe equivocado.
Esta guía presenta una propuesta de arquitectura y un caso totalmente ficticio de R$ 249. Los estados internos sugeridos no son nombres de endpoints ni funciones anunciadas de AZPay. Las referencias regulatorias se consultaron el 22 de octubre de 2026; la disponibilidad del producto y los procedimientos operativos deben confirmarse con el participante contratado.
¿Qué significa boleto con Pix y qué cambia en el cobro híbrido?
Boleto con Pix suele describir una presentación que ofrece un código de barras y un código QR para pagar la misma obligación. La nota del Banco Central sobre la modernización del boleto (se abre en una pestaña nueva ↗) distingue esta posibilidad de la creación del boleto dinámico. Por tanto, tener un código QR no convierte automáticamente un boleto en dinámico ni transforma dos cobros independientes en una integración coordinada.
La Resolución BCB 587/2026 (se abre en una pestaña nueva ↗), de 18 de septiembre, establece una regulación específica para el cobro híbrido. Según el artículo 5, los cambios pertinentes entran en vigor el 1 de febrero de 2027. En octubre de 2026, es necesario distinguir las soluciones ya ofrecidas en el mercado de esa regulación futura.
El artículo 11-AA previsto restringe la modalidad a Pix Cobrança con vencimiento, combinado con un boleto común o dinámico sin vínculo con un activo financiero. Su oferta es opcional; el PSP receptor debe ser la institución emisora del boleto. El texto también exige coherencia entre los esquemas de pago y la cancelación del Pix en los supuestos especificados. Estas condiciones impiden tratar cualquier combinación de QR y boleto como equivalente.
Para contratar o revisar una integración, pide pruebas de cómo funciona hoy y de cómo cumplirá con la entrada en vigor aplicable. El nombre comercial del producto, por sí solo, no demuestra vínculo entre instrumentos, cancelación coordinada ni tratamiento de excepciones. Los controles descritos a continuación son una propuesta de ingeniería para conservar hechos y decisiones del negocio, sin sustituir el reglamento ni el contrato del participante.
Una obligación, dos instrumentos e ingresos con identidad propia
La obligación es lo que debe pagar el cliente: por ejemplo, R$ 249 por un pedido concreto. El boleto y el cobro Pix son instrumentos relacionados con esa obligación. El ingreso es un hecho financiero acreditado. Estas tres capas deben seguir siendo distinguibles cuando llegan mensajes repetidos o pagos muy próximos.
Un modelo conceptual puede utilizar order_id para el pedido, obligation_id para la obligación y una referencia externa por instrumento. Los nombres son ilustrativos. Si el pedido puede generar plazos, complementos o cobros sustitutivos, order_id por sí solo no identifica qué obligación se está satisfaciendo. Registra también importe, moneda, vencimiento y versión de las condiciones comerciales.
En Pix, conserva la relación entre cobro, txid y el EndToEndId del ingreso. En el boleto, mantén la referencia reconocida por el emisor dentro del contexto del contrato, sin asumir que un identificador aislado sea globalmente único. La especificación oficial de la API Pix 2.10.0 (se abre en una pestaña nueva ↗) es la referencia para los objetos Pix; la API comercial del PSP puede exponer otra estructura.
Cada instrumento debe apuntar a la misma obligación, pero cada ingreso necesita identidad propia. Dos notificaciones del mismo Pix representan una repetición del mensaje. Un Pix y un boleto realmente pagados representan dos hechos financieros distintos. Deduplicar ambos como si fueran el mismo evento ocultaría el importe excedente.
¿Qué evidencia permite marcar la obligación como pagada?
Mostrar un boleto, generar un QR o recibir un justificante del cliente no debe, por sí solo, ordenar la liquidación automática de la obligación. El servidor necesita una confirmación verificable del proveedor según el contrato del canal. Registra el origen de la evidencia, el identificador externo, el importe y los horarios disponibles para la investigación.
Separa también el momento del pago, el momento de su confirmación por el proveedor y el momento en que tu aplicación recibió la información. Un evento que llegó primero no demuestra que el pago correspondiente ocurriera primero. Esta diferencia importa para decidir qué incidencia exige corrección y para explicar una reclamación al participante.
El Banco Central aclara que el pago mediante QR de Pix es instantáneo y no sigue las ventanas de compensación de boletos en días laborables, en su orientación sobre documentos con código QR (se abre en una pestaña nueva ↗). Esto no define un plazo universal de notificación a tu aplicación. Confirma los horarios, cortes y formas de consulta de cada servicio contratado.
En la práctica, webhook y consulta deben converger en el mismo registro financiero. La integración no obtiene dos pagos por haber descubierto un ingreso por dos caminos. El artículo sobre cobro, confirmación y devolución en Pix profundiza en estas identidades sin mezclarlas con el estado del pedido.
¿Cómo se separan los estados de la obligación y de los instrumentos?
Una máquina de estados plausible comienza con la obligación abierta. Cuando llega evidencia insuficiente o contradictoria, puede quedar en verificación. Una confirmación válida por el importe íntegro permite registrar una asignación y pasar a pagada. Si el pedido se cancela comercialmente, la obligación puede cerrarse sin pago, conservando la capacidad de reconocer el dinero que llegue después.
En paralelo, cada instrumento sigue su propio ciclo. Puede estar en emisión, disponible para pago, con cancelación solicitada, con cancelación confirmada o con pago confirmado. Los estados deben adaptarse a las posibilidades reales del PSP. Una solicitud de cancelación no puede traducirse silenciosamente en cancelación completada.
Un ingreso adicional no tiene por qué devolver una obligación pagada al estado abierto. Crea una excepción financiera vinculada al mismo historial. Del mismo modo, devolver el excedente no deshace el pago que sigue correctamente asignado al pedido. Evita resumir toda esta situación en un único campo status.
Mantén separadas tres preguntas: ¿está satisfecha la obligación? ¿Cada instrumento sigue admitiendo pago según la evidencia externa? ¿Hay dinero recibido cuyo destino sigue sin resolverse? Así, atención al cliente puede informar de que el pedido está pagado y de que se está tratando un ingreso adicional, sin contradecir al equipo financiero.
¿Cómo se garantiza una sola liquidación cuando llegan dos procesos a la vez?
La decisión de asignar el pago a la obligación debe ser atómica. Si dos consumidores leen abierta al mismo tiempo y después actualizan a pagada, ambos pueden disparar la entrega. Una propuesta es proteger la transición mediante una transacción y una restricción de unicidad para la asignación íntegra de esa obligación. El diseño debe considerar el modelo de datos y su política de pagos parciales.
Dentro de esa transacción local, registra el ingreso ya validado, intenta la asignación permitida y persiste el mensaje de autorización de entrega en una outbox. Si la obligación ya está satisfecha, registra el nuevo ingreso como excepción; no descartes el hecho financiero. Una restricción separada debe reconocer la misma transacción externa cuando vuelva a aparecer mediante consulta o webhook.
El consumidor de la entrega también debe reconocer el mismo comando. La outbox permite reanudar una publicación interrumpida, pero no convierte automáticamente las existencias, la emisión fiscal o la expedición en operaciones idempotentes. La clave de liberación debe corresponder a la entrega prevista para esa obligación, no al canal que notificó el pago.
La cancelación externa sigue siendo asíncrona respecto a la transacción local. No mantengas abierta una transacción de base de datos mientras esperas a la API del PSP. Registra la acción pendiente y procésala con recuperación. Esta separación permite garantizar una única decisión comercial local mientras se sigue supervisando la coordinación financiera.
La idempotencia en API de pago protege la repetición de un comando dentro del alcance documentado. No hace que una clave utilizada en el boleto impida un Pix independiente. En los cobros con alternativas, la identidad de la obligación y la regla de asignación son controles adicionales.
Caso ficticio: un pedido de R$ 249 recibe Pix y boleto
Considera una tienda ficticia con un pedido de R$ 249, sin intereses, descuentos ni comisiones en este ejemplo. La obligación tiene dos opciones vinculadas. El cliente paga el boleto y, sin advertir la confirmación, también completa el Pix. La aplicación recibe primero la notificación Pix; la confirmación del boleto llega después. Esta secuencia ilustra una excepción posible, no el comportamiento universal de un producto.
Al verificar el Pix de R$ 249, la aplicación registra el ingreso y satisface la obligación una sola vez. El comando de entrega se persiste con una identidad única. Después registra la acción necesaria para retirar la opción alternativa, de acuerdo con el mecanismo del participante. La interfaz pasa a mostrar pago confirmado, sin ofrecer un nuevo cobro.
Cuando llega el evento del boleto, la integración determina primero si confirma un pago distinto. Si es solo un mensaje ya procesado, registra la repetición sin un nuevo efecto. Si existe un segundo ingreso confirmado de R$ 249, conserva ese hecho y abre una incidencia por exceso. El pedido sigue teniendo una entrega, no dos. La duplicidad es una incidencia que debe investigarse; por sí sola, no demuestra fraude.
Los importes brutos son R$ 498 recibidos, R$ 249 asignados a la obligación y R$ 249 pendientes de regularización. No conviertas R$ 498 en ingresos de una venta de R$ 249. Tampoco modifiques artificialmente el registro Pix a R$ 0 para que el total parezca correcto. La diferencia necesita un destino documentado.
Antes de corregir, el equipo consulta la cronología financiera del participante. El orden de las notificaciones no decide por sí solo qué pago se conserva y qué movimiento debe regularizarse. El tratamiento depende de hechos confirmados, la regla aplicable, las responsabilidades del participante y el procedimiento disponible. La aplicación debe seguir la resolución, incluida cualquier devolución ya realizada externamente. Si hay que devolver el Pix inicialmente asignado y conservar el boleto, registra una reasignación con un rastro de ajuste. La obligación sigue satisfecha, la entrega no se repite y la asignación original continúa siendo auditable.
Si se devuelven realmente R$ 249 y no hay otros movimientos, el cierre bruto será R$ 498 recibidos menos R$ 249 devueltos, con R$ 249 conservados. La incidencia solo se cierra cuando la evidencia externa y los asientos locales explican ese resultado. Solicitar la devolución todavía no demuestra su finalización.
¿Por qué cancelar el instrumento alternativo no cierra la investigación?
La acción de cancelación necesita una intención persistida, identidad estable, resultado y mecanismo de consulta cuando esté disponible. Si se pierde la respuesta, el estado local debe reflejar incertidumbre. Una nueva llamada solo es segura dentro de las garantías documentadas para esa operación; generar otra referencia sin investigar puede dificultar la recuperación.
También puede existir una carrera entre pago y cancelación. La aplicación puede descubrir el éxito financiero antes de conseguir confirmar la retirada de la otra opción. En vez de prometer una ventana de protección inventada, trata el intervalo como una situación observable: sigue la acción pendiente, su tiempo de espera y cualquier evento contradictorio.
Si el PSP ofrece coordinación entre instrumentos, comprueba qué evento acredita esa coordinación y cómo se comunican las excepciones. Si no hay evidencia suficiente, la operación debe consultar y escalar la discrepancia. Retirar el botón del checkout sigue siendo útil para orientar al cliente, pero no controla una copia del boleto o del QR que ya salió de tu interfaz.
El diseño de webhooks idempotentes ayuda a recibir, validar y procesar mensajes repetidos. Aquí, añade el vínculo entre los instrumentos para que un evento válido no se aplique a la obligación equivocada ni se trate como autorización para una segunda entrega.
¿Cómo se gestiona la devolución sin crear un tercer movimiento indebido?
Una incidencia de duplicidad debe identificar qué ingreso se regularizará, el importe pendiente y quién ejecuta la acción. Antes de iniciar cualquier devolución, consulta los movimientos ya realizados por el participante y las solicitudes todavía en curso. Atención al cliente y automatización no deben trabajar con controles independientes sobre el mismo excedente.
Para el supuesto concreto de un Pix liquidado después de que la obligación ya se haya pagado por boleto, el artículo 41-A, apartado 3, previsto por la Resolución BCB 587/2026 (se abre en una pestaña nueva ↗) atribuye al PSP receptor la devolución íntegra con recursos propios en un plazo máximo de 24 horas. Esta disposición también entra en vigor el 1 de febrero de 2027. No la generalices a cualquier duplicidad ni a fechas anteriores.
En el modelo de aplicación propuesto, una devolución tiene identidad propia y vínculo con el ingreso original. Si hay un timeout, conserva esa identidad e investiga el resultado. No generes una segunda devolución solo porque el operador no recibió respuesta. Mientras la primera siga indeterminada, debe seguir computando en el control del importe reservado para la corrección.
Separa también la devolución del excedente del reembolso de la compra. El cliente puede recuperar el pago adicional y después cancelar el pedido por otro motivo. Son dos intenciones distintas, con sus propias bases y límites. El historial debe explicar ambas sin devolver dos veces el mismo ingreso ni confundir el excedente con una reducción de la venta.
¿Cómo se cierra la conciliación del cobro con alternativas?
La rutina debe comparar obligación, instrumentos emitidos, ingresos, asignaciones, solicitudes de cancelación y movimientos de devolución. Haz la correspondencia por identidad y utiliza importe, moneda y tiempo como comprobaciones adicionales. Dos cobros de R$ 249 en el mismo día no pertenecen necesariamente al mismo pedido.
Una invariante útil para el caso sencillo es: el total recibido menos el total devuelto debe explicarse mediante importes asignados e importes todavía pendientes de regularización. En el ejemplo, R$ 498 menos R$ 0 equivale a R$ 249 asignados más R$ 249 pendientes. Después de confirmar la devolución, R$ 498 menos R$ 249 equivale a los R$ 249 asignados.
Las comisiones, los ajustes y las diferencias de calendario deben tener movimientos separados. No cambian la identidad de quien pagó ni justifican borrar el excedente. El ledger de pagos proporciona el rastro interno; la conciliación entre venta, captura y liquidación explica cómo compararlo con las fuentes externas.
Crea colas distintas para ingresos sin obligación conocida, importes discrepantes, instrumentos alternativos con cancelación no confirmada y excesos todavía sin resolver. Cada incidencia necesita responsable, siguiente acción y evidencia de cierre. La antigüedad de la excepción importa tanto como su cantidad: un total pequeño puede ocultar a un cliente que lleva mucho tiempo esperando una solución.
¿Y si el pedido ha caducado o el importe no coincide?
La caducidad del pedido no borra un ingreso posterior. Una propuesta es registrar la entrada y suspender la decisión comercial hasta comprobar la disponibilidad de existencias, las condiciones de venta y la política de regularización. Reabrir automáticamente un pedido puede ser inadecuado cuando el precio, la entrega o la reserva ya han cambiado.
Si el importe recibido es inferior o superior al esperado, no apliques silenciosamente la regla del ejemplo de pago íntegro. Valida primero los intereses, la penalización, el descuento y el vencimiento comunicados por el participante. Después clasifica la diferencia. Un error al interpretar la regla del importe puede parecer una duplicidad o una insuficiencia sin que exista un segundo pago.
Cuando el producto y el negocio admitan pagos parciales, sustituye la restricción de una asignación íntegra por un control transaccional de los importes asignados. No aceptes sumas concurrentes superiores al saldo de la obligación. Esta adaptación exige un diseño propio; el ejemplo de R$ 249 no debe copiarse como si cubriera plazos, complementos y todas las modalidades de boleto.
¿Qué se prueba antes de ofrecer ambos caminos al cliente?
Prueba la notificación Pix repetida, la confirmación de boleto repetida y el mismo ingreso descubierto por consulta y webhook. El resultado esperado es un registro financiero por hecho externo y una única liberación de la obligación íntegra. Después, fuerza los dos ingresos distintos al mismo tiempo: ambos deben permanecer en el historial, con solo uno asignado y el exceso remitido a su tratamiento.
Simula un fallo después de persistir el pago de la obligación y antes de publicar la entrega. La recuperación debe reenviar el comando sin repetir el efecto comercial. Simula también interrupciones antes y después de solicitar la cancelación. La cola debe reanudar la acción y reconocer el resultado externo sin confundir solicitud con finalización.
Invierte el orden de las notificaciones y conserva horarios financieros diferentes de los de llegada. Prueba pago tras caducidad, referencia desconocida, importe discrepante y consulta temporalmente no disponible. Ninguno de estos casos debe autorizar una entrega por la mera similitud del importe ni hacer que el sistema ignore dinero confirmado.
Por último, simula una devolución en curso, una respuesta perdida y una regularización ya ejecutada por el participante. Atención al cliente debe encontrar la misma incidencia utilizada por la automatización. El criterio de aceptación es poder reconstruir los importes recibidos, asignados, devueltos y pendientes a partir de la evidencia, sin depender de la memoria de quien estaba de guardia.
¿Qué contrato de integración debe quedar claro?
Antes de habilitar el recorrido, confirma con el participante cómo se vinculan los instrumentos, qué consulta acredita el pago, qué referencias vuelven en las notificaciones, cómo se cancela la alternativa y cómo se tratan los pagos conflictivos. Documenta también los estados intermedios, los procedimientos de recuperación y el canal de escalado.
En la interfaz, informa de que los caminos son alternativas para una misma obligación. Tras la confirmación, muestra el estado conocido e instrucciones de atención al cliente cuando haya discrepancias. Evita indicar al cliente que pague de nuevo mientras haya un ingreso en verificación. La comunicación debe reflejar lo que puede demostrar el servidor.
Para evaluar una integración con AZPay, consulta el Dev Central y confirma el contrato del servicio previsto. Esta guía no afirma que la plataforma ofrezca boleto híbrido. Su propuesta es hacer verificable la decisión de ingeniería: una obligación identificada, hechos financieros conservados, una autorización de entrega comercial y una resolución trazable de cualquier importe adicional.