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.

Cada QR usa una llave ALPHA efímera que el gateway crea automáticamente y elimina cuando la transacción termina — no necesitas gestionar llaves para cobrar.

Onboarding requerido

Tu comercio debe estar vinculado previamente en Bre-B (customer + cuenta) por nuestro equipo. Sin onboarding, el endpoint responde 409.

Request body

{
  "type": "DYNAMIC",
  "channel": "ECOMM",
  "amount": 50000,
  "reference": "orden-8842",
  "qrCodeReference": "ORD8842",
  "transactionPurpose": "00",
  "vat": { "vat_type": "FIXED", "vat_value": "0.00", "vat_base_value": "0.00" },
  "inc": { "inc_type": "FIXED", "inc_value": "0.00" }
}

Campo	Tipo	Requerido	Descripción
type	string	❌	DYNAMIC (default) o STATIC. El dinámico exige amount; el estático puede ir sin monto (el pagador lo define)
channel	string	❌	Canal de presentación: MAN, POS, APP, ECOMM (default), MPS, ATM, MPOS
amount	number	✅ si DYNAMIC	Monto en pesos COP enteros, máximo 11.500.000. Debe incluir IVA/INC/propina
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
reference	string	❌	Tu referencia interna (vuelve como txIdSource en Transacciones)
transactionPurpose	string	❌	Código de propósito de 2 dígitos (default 00 = compras)
terminalLabel	string	❌	Identificador de terminal POS
additionalInfo	object	❌	Metadatos passthrough (p.ej. invoice_number, store_label)
vat	object	❌	{ vat_type, vat_value, vat_base_value } — default 0.00
inc	object	❌	{ inc_type, inc_value } — default 0.00
tip	object	❌	{ tip_type, tip_value | tip_percentage }

Precaución

amount va en pesos enteros y no puede superar 11.500.000 COP por transacción. El QR expira a los 15 minutos (fijo); al expirar, el QR y su llave efímera se eliminan de la red.

Response 201 Created

{
  "txId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "status": "PENDING",
  "qrType": "DYNAMIC",
  "channel": "ECOMM",
  "qrCode": "<payload EMVCo del QR>",
  "qrImage": "data:image/png;base64,...",
  "qrCodeReference": "ORD8842",
  "qrCodeId": "9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4",
  "keyId": "key-uuid",
  "keyValue": "@aB3xY9kQm2Wz7Rt5",
  "expiresAt": "2026-06-01T10:15:00.000Z",
  "amount": 50000,
  "currency": "COP",
  "estimatedFees": {
    "feeClient": 1500,
    "feeBase": 1261,
    "iva": 239,
    "netAmount": 48500,
    "currency": "COP"
  }
}

Campo	Descripción
txId	ID único de la transacción en Rivopay
qrCode	Payload EMVCo del QR (para renderizar con cualquier librería QR)
qrImage	Imagen PNG del QR en base64 (data URI)
qrCodeReference	Referencia enviada a la red Bre-B
qrCodeId	ID del recurso QR en Bre-B
keyId / keyValue	Llave ALPHA efímera asociada al QR (se elimina al terminar)
expiresAt	Expiración del QR (15 minutos después de crearlo)
amount	Monto, o null si es un QR STATIC sin monto
estimatedFees	Solo presente si el QR tiene monto. Para STATIC sin monto, los fees se calculan al pagar

Consultar estado

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

Si sigue PENDING, la consulta sincroniza contra Bre-B en el momento.

{
  "txId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "status": "COMPLETED",
  "amount": 50000,
  "currency": "COP",
  "feeClient": 1500,
  "netAmount": 48500,
  "createdAt": "2026-06-01T10:00:00.000Z",
  "updatedAt": "2026-06-01T10:05:00.000Z"
}

Estados posibles: PENDING, COMPLETED, FAILED, CANCELLED, EXPIRED.

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": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
  "qrCodeId": "9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4",
  "status": "ACTIVE",
  "qrType": "DYNAMIC",
  "channel": "ECOMM",
  "qrCode": "<payload EMVCo>",
  "qrImage": "data:image/png;base64,...",
  "qrCodeReference": "ORD8842",
  "amount": 50000,
  "createdAt": "2026-06-01T10:00:00.000Z"
}

Listar QRs

GET /v1/co/breb/payin/qrcodes

Lista los QRs de tu comercio en Bre-B (paginado).

Query param	Descripción
pageSize	Resultados por página (1–100, default 20)
pageNumber	Página (default 1)
type	Filtra por tipo (STATIC / DYNAMIC)
keyId / keyType / keyValue	Filtra por la llave asociada

{
  "qrCodes": [
    {
      "qrCodeId": "9f8e7d6c-...",
      "status": "ACTIVE",
      "type": "DYNAMIC",
      "channel": "ECOMM",
      "qrCode": "<payload EMVCo>",
      "amount": 50000,
      "qrCodeReference": "ORD8842",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "pagination": { "total_items": 1, "total_pages": 1 }
}

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": "50000", "currency": "COP" },
  "key": { "key_type": "ALPHA", "key_value": "@tienda" },
  "merchant": { "name": "Tienda XYZ" },
  "vat": { "vat_type": "FIXED", "vat_value": "0.00" },
  "inc": { "inc_type": "FIXED", "inc_value": "0.00" },
  "qrCodeReference": "ORD8842",
  "additionalInfo": {}
}

Cancelar / eliminar un QR

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

Elimina el QR en la red y marca la transacción como EXPIRED si seguía pendiente. Un QR con pago liquidado (COMPLETED) no se puede cancelar (409).

{ "txId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d", "status": "CANCELLED" }

Errores

Código	Causa
400	type inválido, amount faltante en DYNAMIC, monto > 11.500.000, o qrCodeReference inválida
403	Servicio Bre-B no habilitado, o producción no habilitada para tu cuenta
409	Comercio sin onboarding Bre-B, o cancelación de un QR ya pagado
422	Bre-B rechazó la operación — incluye providerStatus y detail
502	Bre-B no disponible — reintenta
503	Servicio temporalmente suspendido para tu cuenta