Flujo de pago Bre-B

Qué cubre esta guía

Esta guía reemplaza la narrativa anterior centrada solo en QR y documenta el flujo Bre-B tal como aparece en los materiales originales de Spotlight de Cobru.

El flujo tiene dos partes:

1. Crear un cobru con Bre-B habilitado en payment_method_enabled
2. Enviar detalles de pago a POST /{url} con payment: "breb"

Modos de salida de Bre-B

Hay dos formas muy distintas de ofrecer una experiencia Bre-B con Cobru:

Si tu objetivo es específicamente generar un QR Bre-B sin el link de pago, necesitas la segunda ruta: obtener el string de payload Bre-B desde Cobru y renderizar tú mismo el QR.

Paso 1 — Crear el cobru

{
  "amount": 20000,
  "description": "Cobro Bre-B",
  "expiration_days": 1,
  "client_assume_costs": false,
  "iva": 0,
  "payment_method_enabled": "{\"breb\":true}",
  "payer_redirect_url": "https://tuapp.com/pago/exitoso",
  "callback": "https://tuapp.com/api/cobru/webhook"
}

Spotlight y los learnings posteriores coinciden en un quirk crítico: payment_method_enabled debe ser un string JSON, no un objeto anidado.

Paso 1.5 — Habilitar la capacidad correcta de Bre-B

El paso de creación debe habilitar Bre-B con "breb": true dentro de payment_method_enabled.

El research profundo posterior también encontró un segundo literal de checkout, breb_qr, usado por los internos del checkout hosted de Cobru.

Para fines de documentación, trátalos así:

Paso 2 — Enviar los detalles de pago Bre-B

Llama el slug del cobru retornado por POST /cobru/:

POST /{url}

{
  "payment": "breb"
}

Los materiales originales de Spotlight describen Bre-B como un método de transferencia rápida ligado a la app Bre-B o a la llave (llaves) del usuario.

Generar un QR Bre-B nativo sin el link de pago

Esta es la sección que la mayoría de equipos realmente necesita.

Si no quieres mandar al pagador a la página hosted de Cobru, el flujo es:

1. crear el cobru con Bre-B habilitado
2. llamar POST /{url} para la variante Bre-B de checkout
3. extraer el string de payload Bre-B que retorna Cobru
4. generar la imagen QR en tu frontend o backend
5. mostrar el QR junto con la llave Bre-B al pagador

¿Qué campo debes usar para armar el QR?

Los materiales fuente son inconsistentes, así que tu integración debe normalizar todos los nombres de campo conocidos:

Regla práctica:

• primero busca check_qr
• luego usa qr_value como fallback
• si integras contra la ruta posterior del checkout hosted, revisa también payment_details.qr_bitcoin

Ejemplo de normalización

const qrPayload =
  response?.check_qr ??
  response?.qr_value ??
  response?.payment_details?.qr_bitcoin ??
  response?.fields?.check_qr ??
  response?.fields?.qr_value;

const keyValue =
  response?.key_value ??
  response?.payment_details?.key_value ??
  response?.fields?.key_value;

if (!qrPayload) {
  throw new Error('Cobru no retornó un payload QR Bre-B');
}

Ejemplo de generación del QR

import QRCode from 'qrcode';

const qrDataUrl = await QRCode.toDataURL(qrPayload, {
  errorCorrectionLevel: 'M',
  margin: 1,
  width: 320,
});

Usa la imagen generada dentro de tu propio checkout. Si tu objetivo es un QR Bre-B nativo, no codifiques la URL hosted de Cobru.

Campos que deberías mostrar en tu UI

Tiempo de vida

Spotlight dice que qr_value y key_value viven 5 minutos.

El reverse engineering posterior también observó time_to_complete: 520 segundos en la lógica de la página de Cobru, o sea aproximadamente 8.6 minutos.

La regla operativa correcta es:

• tu UX debe asumir una instrucción Bre-B de vida muy corta
• debes regenerar o refrescar el QR cuando expire la ventana
• nunca reutilices un payload Bre-B viejo para una nueva transacción

Limitación actual

El research profundo posterior encontró que Cobru no expone un QR Bre-B estático simple que cualquier pagador pueda escanear indefinidamente.

El QR Bre-B nativo está ligado a la transacción y, en pruebas posteriores de sandbox, puede requerir datos reales del pagador o habilitación comercial. Eso significa:

• sí puedes generar un QR Bre-B sin usar el link hosted
• pero primero dependes de que Cobru te devuelva un payload Bre-B específico de la transacción
• esto no equivale a tener un QR estático reutilizable de comercio

Ruta alternativa de QR nativo observada en research posterior

El research posterior del checkout también encontró una variante enfocada en QR:

{
  "payment": "breb_qr"
}

Caveats importantes de ese research:

• fue observada en una implementación posterior del checkout de Cobru, no en el contrato Spotlight original
• las pruebas en sandbox sugirieron que puede requerir documento real del pagador
• la respuesta parece más cercana a payment_details.qr_bitcoin que al wording check_qr de Spotlight

Úsala solo si:

• breb directo no está disponible en tu entorno
• soporte de Cobru confirma breb_qr para tu cuenta
• estás listo para probar con datos de pagador compatibles con sandbox

Forma de respuesta esperada

Spotlight muestra una respuesta que contiene tanto un objeto api.paymentorder como un objeto api.cobru. Los campos Bre-B más importantes son:

Fragmento de ejemplo de los materiales originales:

[
  {
    "model": "api.paymentorder",
    "fields": {
      "method": "breb",
      "franchise": "breb",
      "state": "PENDIENTE",
      "amount": "20000.00",
      "qr_value": "9893839849384938434.COM.CRB.LLA04...",
      "key_value": "@llave0343"
    }
  },
  {
    "model": "api.cobru",
    "fields": {
      "url": "urmndopt"
    }
  }
]

Ventana de expiración

Los materiales de Spotlight indican explícitamente que tanto qr_value como key_value viven 5 minutos.

Trátalos como instrucciones de pago de corta duración, no como identificadores reutilizables.

Cómo se relaciona esto con la addenda de QR

El contrato Spotlight de arriba es la fuente principal del flujo de pago Bre-B.

Además existe un patrón posterior verificado:

• crear un cobru con Bre-B habilitado
• construir la URL hosted de Cobru usando el slug retornado
• generar un PNG QR externo que apunte a la página de pago hosted
• enviarlo por canales como WhatsApp

Ese patrón QR es útil cuando tu producto necesita distribuir una imagen escaneable, pero es una addenda sobre el flujo Bre-B original, no el contrato base.

Árbol de decisión recomendado

Cuándo usar Bre-B

Usa Bre-B cuando:

• el pagador puede completar una transferencia interoperable bancaria
• tu checkout debe mostrar Bre-B como opción principal
• puedes trabajar con instrucciones de pago de vida corta y confirmación por webhook

Si necesitas un flujo hosted con selección explícita de banco, PSE encaja mejor.

Páginas relacionadas

• Crear un cobru
• Enviar detalles de pago
• Códigos de bancos PSE
• Pagos PSE