Bre-B payment flow

What this guide covers

This guide replaces the previous QR-only narrative and documents the Bre-B flow as it appears in Cobru's original Spotlight materials.

The flow has two parts:

1. Create a cobru with Bre-B enabled in payment_method_enabled
2. Submit payment details to POST /{url} with payment: "breb"

Bre-B output modes

There are two very different ways to ship a Bre-B experience with Cobru:

If your goal is specifically to generate a Bre-B QR without the payment link, you need the second path: obtain the Bre-B payload string from Cobru and render the QR yourself.

Step 1 — Create the 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://yourapp.com/payment/success",
  "callback": "https://yourapp.com/api/cobru/webhook"
}

Spotlight and later integration learnings agree on one critical quirk: payment_method_enabled must be a JSON string, not a nested object.

Step 1.5 — Enable the right Bre-B capability

The create step must enable Bre-B with "breb": true inside payment_method_enabled.

Later deep research also found a second checkout literal, breb_qr, used by Cobru's hosted checkout internals.

For documentation purposes, treat them like this:

Step 2 — Submit Bre-B payment details

Call the cobru slug returned by POST /cobru/:

POST /{url}

{
  "payment": "breb"
}

The original Spotlight materials describe Bre-B as a fast bank-transfer method tied to the user's Bre-B app or key (llaves).

Generate a native Bre-B QR without the payment link

This is the section most teams are actually looking for.

If you do not want to send the payer to the hosted Cobru page, your flow is:

1. create the cobru with Bre-B enabled
2. call POST /{url} for the Bre-B checkout variant
3. extract the Bre-B payload string returned by Cobru
4. generate the QR image inside your own frontend or backend
5. show the QR plus the Bre-B key to the payer

Which field should you use for the QR?

The source materials are inconsistent, so your implementation should normalize all known field names:

Practical rule:

• first look for check_qr
• then fall back to qr_value
• if you are integrating against the later hosted-checkout path, also check payment_details.qr_bitcoin

Example normalization logic

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 did not return a Bre-B QR payload');
}

Example QR generation

import QRCode from 'qrcode';

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

Use the generated image in your own checkout UI. Do not encode the hosted Cobru URL if your goal is a native Bre-B QR.

Response fields to show in your UI

Time-to-live

Spotlight says qr_value and key_value live for 5 minutes.

Later reverse engineering also observed time_to_complete: 520 seconds in Cobru's page logic, which is roughly 8.6 minutes.

Treat the operational rule as:

• your UX should assume a very short-lived Bre-B instruction
• refresh or regenerate the QR when the payment window expires
• never reuse an old Bre-B payload for a new transaction

Current limitation

Later deep research found that Cobru does not expose a simple static Bre-B QR that any payer can scan forever.

The native Bre-B QR is transaction-scoped and, in later sandbox testing, may require real payer identification data or commercial enablement. That means:

• you can generate a Bre-B QR without using the hosted payment link
• but you still depend on Cobru returning a transaction-specific Bre-B payload first
• this is not the same thing as having a reusable static merchant QR

Alternative native QR path seen in later research

Later checkout research also found a QR-focused variant:

{
  "payment": "breb_qr"
}

Important caveats from that research:

• it was observed in a later Cobru checkout implementation, not in the original Spotlight contract
• sandbox testing suggested the payer's document data may be required
• the response path looked closer to payment_details.qr_bitcoin than the Spotlight check_qr wording

Use it only if:

• direct breb is not available in your environment
• Cobru support confirms breb_qr for your account
• you are prepared to test it with real sandbox-compatible payer data

Expected response shape

Spotlight shows a response that contains both an api.paymentorder object and an api.cobru object. The most important Bre-B fields are:

Example excerpt from the original materials:

[
  {
    "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"
    }
  }
]

Expiration window

The Spotlight materials explicitly state that both qr_value and key_value are valid for 5 minutes.

Treat them as short-lived payment instructions, not reusable identifiers.

How this differs from the QR addendum

The Spotlight contract above is the source of truth for the Bre-B payment flow.

A later verified integration pattern also exists:

• create a cobru with Bre-B enabled
• build the hosted Cobru URL from the returned slug
• render an external QR PNG that points to the hosted payment page
• send it through channels such as WhatsApp

That QR pattern is useful when your product needs to distribute a scannable payment link, but it is an addendum on top of the original Bre-B flow, not the base contract.

Recommended decision tree

When to use Bre-B

Use Bre-B when:

• the payer can complete an interoperable bank transfer
• your checkout should show Bre-B as a first-class option
• you can tolerate short-lived payment instructions and webhook-driven confirmation

If you need a hosted redirect flow with explicit bank selection, PSE is the better fit.

Related pages

• Create a cobru
• Submit payment details
• PSE bank codes
• PSE payments