Pago QR interoperable

Roles

• Billetera — paga QR de cualquier emisor interoperable (POST /v1/qr/pay).
• Aceptador / comercio — emite QR EMV IEP (POST /v1/qr/commerce). Las billeteras resuelven el cobro vía GET /resolve (CIMPRA) y Gallo acredita con QROperacionFinalizadaAdquirente.
• Cashout — extracción a cuenta bancaria con confirmación automática o manual.

API

POST /v1/qr/preview     # lector: EMV → collector + payHints (auth)
POST /v1/qr/pay          # billetera → QRDebin (auto-resolve si faltan vendedor*)
POST /v1/qr/commerce     # EMV IEP (aceptador)
GET  /resolve            # IEP resolve público (otras billeteras; host iep.*)
POST /v1/qr/cashout      # CashOut
POST /v1/qr/cashout/confirma
GET  /v1/qr              # list (role=billetera|aceptador|cashout, status, q=búsqueda)
GET  /v1/qr/:id
POST /v1/qr/:id/contracargo
POST /v1/qr/billetera    # alta billetera

• Iniciadores sobre Gallo (p.ej. Sigil): usar POST /v1/qr/preview + POST /v1/qr/pay con el EMV. Gallo resuelve IEP/legacy; no hace falta llamar GET /resolve desde el producto.
• GET /v1/qr?q=… busca por debinId, qrIdTrx, paymentReference o CVU (comprador/vendedor).
• El QR comercio sigue IEP (CIMPRA 525/530): el EMV lleva dominio invertido + refs; el CVU del comercio se entrega en GET /resolve (collector.account) a billeteras externas. Estático → open_amount; dinámico → closed_amount. Solo TRANSFER (PCT).
• En POST /v1/qr/pay, si el QR es dinámico con importe (EMV tag 54), el importe enviado debe coincidir o podés omitirlo (se toma del QR). Un importe distinto responde 400.
• tiempoExpiracion (QR dinámico) ahora tiene default 10 minutos; en homologación Coelsa acepta máximo 10.
• Contracargos: cada POST /v1/qr/:id/contracargo genera un ori_trx_id propio, lo que habilita contracargos parciales múltiples sobre la misma operación.

Flags relevantes: DEBIN_ENABLED, QR_AUTO_CONFIRM_DEBIT, QR_AUTO_CONFIRM_CASHOUT, QR_REVERSE_DOMAIN, QR_ADMIN_CUIT, QR_POSTAL_CODE_DEFAULT, IEP_ACCESS_TOKEN (opcional).

Referencia: /developers/referencia.

Avisos inbound (Coelsa)

• GET /resolve — IEP API resolve (CIMPRA): billeteras envían el EMV crudo y reciben open_amount / closed_amount con collector, order y payment_methods_allowed. En HOMO: https://coelsa-homo.gallo-pay.com/resolve (VPN; sin token).
• QRIntencionPago — validación sincrónica del aceptador: Gallo responde en el body validation_status (PASS/FAIL) más validation_data (MCC, código postal, payment_reference) y el eco de qr_id_trx / id_debin / id_billetera / fecha_negocio. El QR pasa a pending_confirm y emitimos qr.pending.
• QRConfirmaDebito — respuesta sync APPROVED/REJECTED + débito ledger, con el mismo eco de campos requerido por el diccionario Coelsa.
• QROperacionFinalizada — finalize billetera / chargeback (incluye id e importe del contracargo cuando aplica)
• QROperacionFinalizadaAdquirente — crédito aceptador
• QRReverso / AvisoCashoutPendiente

Nota: si un AvisoReversaDebito referencia un debin QR, la contabilidad la resuelve el flujo QR (no se genera un crédito adicional, evitando duplicar saldo).

Hacia tu backend emitimos los webhooks qr.* (created, pending, debit.confirmed, debit.rejected, finalized, credited, chargeback, cashout.*, commerce.created). Ver tipos de evento.

Promociones (cashback)

En POST /v1/qr/pay podés enviar promoCode. El importe ante Coelsa no cambia; el reintegro se acredita async al comprador. Detalle en la guía de promociones.

Producto: /soluciones/qr.