Cobro con QR (Bre-B)

POST /v1/co/breb/payin/qr

Genera un código QR Bre-B para que el usuario pague desde cualquier app del ecosistema Bre-B. El estado final se confirma vía webhook.

Autenticación: firma ECDSA (x-client-id, x-timestamp, x-nonce, x-signature, x-content-sha256). País CO, moneda COP.

El gateway crea primero una llave ALPHA efímera exclusiva de ese QR y luego el QR en la red — no necesitas gestionar llaves para cobrar.

Request body

{
  "channel": "ECOMM",
  "amount": 100000,
  "transactionPurpose": "00",
  "qrCodeReference": "FACT12345",
  "additionalInfo": { "invoice_number": "123", "store_label": "tienda-01" },
  "vat": { "vat_type": "FIXED", "vat_value": "100.00", "vat_base_value": "100.00" },
  "inc": { "inc_type": "FIXED", "inc_value": "10.00" },
  "reference": "pedido-987"
}

Campo	Tipo	Requerido	Descripción
amount	number	✅	Monto en pesos COP enteros, > 0 y ≤ 11.500.000. Debe incluir ya TIP/INC/VAT
channel	string	✅	Canal de presentación del QR. Ver valores permitidos
transactionPurpose	string	❌	Código de 2 dígitos (00 compras, 05 recaudo…). Default 00
qrCodeReference	string	❌	Referencia que viaja en la red Bre-B: máx 17 alfanuméricos, sin la letra P. Se genera una si no la envías
additionalInfo	object	❌	Metadatos passthrough (invoice_number, store_label…)
vat / inc / tip	object	❌	Informativos, no se suman al monto. Si no vienen se envían en 0.00
reference	string	❌	Tu referencia interna de conciliación (queda como txIdSource en Transacciones)

X-Idempotency-Key obligatoria

Este endpoint mueve dinero: la cabecera es obligatoria. Sin ella, 400 IDEMPOTENCY_KEY_REQUIRED antes de crear la llave o el QR. Ver Idempotencia.

Valores de channel

channel es obligatorio e indica desde qué punto de interacción se le presenta el QR al pagador. Es un ENUM cerrado: cualquier otro valor devuelve 400.

Valor	Nombre	Cuándo usarlo
IM	Manual	El cobro se genera a mano por un operador, sin un punto de venta automatizado (ej. un asesor que crea el QR en un back office)
POS	Point of Sale	Datáfono o caja registradora física fija en un local
APP	Mobile App	El QR se muestra dentro de tu app móvil
ECOMM	E-commerce	Checkout web / tienda online
MPS	Mobile POS	Punto de venta móvil: el vendedor cobra desde un dispositivo portátil en terreno (domicilios, ventas ambulantes)
CB	Corresponsal Bancario	Cobro en un corresponsal bancario (tienda, droguería, punto aliado que opera transacciones financieras)
OFC	Oficina	Cobro presencial en una oficina o sucursal del comercio
ATM	ATM	Cajero automático

Migración: MAN → IM

El valor MAN quedó descontinuado. Si tu integración envía channel: "MAN", actualízala a channel: "IM".

Response 201 Created

{
  "txId": "a1b2c3d4e5f6...",
  "status": "PENDING",
  "qrType": "DYNAMIC",
  "channel": "ECOMM",
  "qrCode": "00020101021226550015CO.COM.VISI.LLA...6304D0DF",
  "qrImage": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...",
  "qrCodeReference": "FACT12345",
  "qrCodeId": "7aa184b7-c549-467b-917f-460b4224b459",
  "keyId": "3f21c0aa-5d18-4e0b-9c77-1c2b9a55e401",
  "keyValue": "@Xk9dPq2mLr7TzB4n",
  "expiresAt": "2026-07-23T15:15:00.000Z",
  "amount": 100000,
  "currency": "COP",
  "estimatedFees": {
    "feeClient": 500,
    "feeBase": 420,
    "iva": 80,
    "netAmount": 99500,
    "currency": "COP"
  }
}

Campo	Descripción
txId	Identificador interno para consultar y cancelar el cobro
qrCode	Cadena EMVCo (para pintar el QR tú mismo con cualquier librería)
qrImage	Data URI completo del QR, listo para usar tal cual en un <img src>
qrCodeReference	Referencia enviada a la red Bre-B
qrCodeId	ID del recurso QR en Bre-B
keyId / keyValue	Llave efímera detrás del QR (informativa; se borra al finalizar)
expiresAt	Expiración del QR (15 minutos después de crearlo)
estimatedFees	Aparece cuando la tarifa tiene desglose base/IVA

No asumas el tipo de imagen

Cuando la red devuelve imagen, es un PNG (data:image/png;base64,…). Cuando no la devuelve, el QR se genera desde la carga EMV y se entrega como SVG (data:image/svg+xml;base64,…), que es lo que hoy devuelven los QR dinámicos de Bre-B. Ambos son data URIs válidos y ambos se pintan en un <img>: no parsees la cadena ni asumas el tipo MIME.

Errores

Código	Causa
400	amount ausente / ≤ 0 / no numérico; amount > 11.500.000; qrCodeReference inválida (>17, no alfanumérica o con P); o falta X-Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED)
403	Bre-B no habilitado para la cuenta, o producción no habilitada
409	Onboarding incompleto — contacta con soporte
422	Monto fuera de los límites min/max de tu tarifa, o Bre-B rechazó la creación (incluye providerStatus y detail)
502	Bre-B no disponible — reintenta
503	Cuenta suspendida temporalmente

Nota

Si la creación del QR falla después de crear la llave, la llave se borra sola: no quedan recursos huérfanos.

Ciclo de vida

• Vigencia 15 minutos (expiresAt, expirationInSeconds: 900). Vencido sin pago → EXPIRED y se borran QR + llave en la red.
• Estados: PENDING → PROCESSING (pago autorizado, en manos del banco) → COMPLETED | FAILED | EXPIRED.
• El pago entrante se atribuye por qr_code_reference en la autorización síncrona; el monto debe coincidir exacto con amount o se rechaza — pero el cobro queda abierto para un nuevo intento y el rechazo se registra en lastRejection.
• Al liquidar recibes el webhook payin.completed / payin.failed (HMAC-SHA256 en x-signature) — ver Webhooks.

Endpoints relacionados

Método	Ruta	Uso
GET	/v1/co/breb/payin/qr/{txId}	Estado del cobro (consulta a la red y sincroniza)
GET	/v1/co/breb/payin/{txId}	Igual, ruta genérica
GET	/v1/co/breb/payin/qr/{txId}/detail	Detalle del QR en la red (cadena, imagen, estado)
POST	/v1/co/breb/payin/qr/decode	Decodificar una cadena EMVCo escaneada
DELETE	/v1/co/breb/payin/qr/{txId}	Cancelar el QR (→ EXPIRED + borra QR y llave). 409 si ya está COMPLETED

Consultar estado

GET /v1/co/breb/payin/qr/{txId} — alias: GET /v1/co/breb/payin/{txId}

{
  "txId": "a1b2c3d4e5f6...",
  "status": "COMPLETED",
  "amount": 100000,
  "currency": "COP",
  "feeClient": 500,
  "netAmount": 99500,
  "createdAt": "2026-07-23T15:00:00.000Z",
  "updatedAt": "2026-07-23T15:05:00.000Z"
}

Intento de pago rechazado (lastRejection)

Si alguien intentó pagar por un monto distinto al esperado, el pago se rechaza pero el cobro sigue abierto: la transacción continúa PENDING y el pagador puede reintentar con el valor correcto hasta que venza. La respuesta incluye el último rechazo:

{
  "txId": "a1b2c3d4e5f6...",
  "status": "PENDING",
  "amount": 100000,
  "currency": "COP",
  "lastRejection": {
    "reason": "AMOUNT_MISMATCH",
    "amount": 90000,
    "rejectedAt": "2026-07-23T15:07:11.000Z",
    "retriable": true
  }
}

Campo	Descripción
reason	Motivo del rechazo (AMOUNT_MISMATCH)
amount	Monto que intentó pagar el pagador
rejectedAt	Momento del rechazo
retriable	true → el cobro sigue vivo y admite un nuevo intento

Precaución

Un lastRejection con retriable: true no es un cobro fallido: no cierres el pedido. Sigue esperando payin.completed o el vencimiento del QR.

Detalle del QR en la red

GET /v1/co/breb/payin/qr/{txId}/detail

Consulta el recurso QR directamente en Bre-B (útil para re-obtener la imagen o verificar su estado en la red).

{
  "txId": "a1b2c3d4e5f6...",
  "qrCodeId": "7aa184b7-c549-467b-917f-460b4224b459",
  "status": "ACTIVE",
  "qrType": "DYNAMIC",
  "channel": "ECOMM",
  "qrCode": "00020101021226550015CO.COM.VISI.LLA...",
  "qrImage": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...",
  "qrCodeReference": "FACT12345",
  "amount": 100000,
  "createdAt": "2026-07-23T15:00:00.000Z"
}

Decodificar un QR

POST /v1/co/breb/payin/qr/decode

Decodifica una cadena EMVCo de cualquier QR Bre-B y devuelve su información estructurada.

{ "qrCodeData": "0002010102122661..." }

Response 200 OK:

{
  "type": "DYNAMIC",
  "status": "ACTIVE",
  "channel": "ECOMM",
  "amount": { "value": "100000", "currency": "COP" },
  "key": { "key_type": "ALPHA", "key_value": "@Xk9dPq2mLr7TzB4n" },
  "merchant": { "name": "Tienda XYZ" },
  "vat": { "vat_type": "FIXED", "vat_value": "100.00" },
  "inc": { "inc_type": "FIXED", "inc_value": "10.00" },
  "qrCodeReference": "FACT12345",
  "additionalInfo": {}
}

Cancelar / eliminar un QR

DELETE /v1/co/breb/payin/qr/{txId}

Elimina el QR y su llave en la red, y marca la transacción como EXPIRED si seguía pendiente. Un QR ya pagado (COMPLETED) no se puede cancelar (409).

{ "txId": "a1b2c3d4e5f6...", "status": "CANCELLED" }