> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wava.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Breb

> Breb QR code and bank transfer payment flow.

# Breb Payment Flow

Breb enables payments via bank transfer using a QR code or transfer key. The buyer scans the QR or enters the key in their banking app to complete the payment.

## How it works

```mermaid theme={null}
sequenceDiagram
    participant Merchant
    participant Wava API
    participant Breb
    participant Buyer

    Merchant->>Wava API: POST /v1/orders (national_id)
    Wava API->>Breb: Initiate payment
    Breb-->>Wava API: QR code + transfer key
    Wava API-->>Merchant: 200 OK (qr_code, key)
    Merchant->>Buyer: Display QR code / key
    Buyer->>Breb: Complete transfer via banking app
    Breb->>Wava API: Payment confirmed
    Wava API->>Merchant: Webhook (status: confirmed)
```

<Steps>
  <Step title="Create order">
    Call `POST /v1/orders` with the buyer's `id_number`, `id_type`, and the Breb gateway ID.
  </Step>

  <Step title="Display QR code and key">
    The response includes a `qr_code` (base64-encoded image) and a `key` (text string). Display both to the buyer — the QR code for scanning, and the key as a fallback for manual entry.
  </Step>

  <Step title="Buyer completes transfer">
    The buyer opens their banking app, scans the QR code or enters the transfer key, and confirms the payment.
  </Step>

  <Step title="Payment confirmed">
    Once the transfer is completed, the order status changes to `confirmed`. You receive a webhook notification, or you can poll for the status.
  </Step>
</Steps>

## Required fields

| Field                  | Required | Description                                                    |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `shopper.id_number`    | Yes      | Buyer's national ID (cedula)                                   |
| `shopper.id_type`      | Yes      | Document type ID from [Document Types](/orders/document-types) |
| `shopper.email`        | Yes      | Buyer's email                                                  |
| `shopper.phone_number` | Yes      | Buyer's phone number                                           |
| `shopper.country`      | Yes      | `CO`                                                           |

<Warning>
  Like Daviplata, Breb only accepts the following document types: **CC** (ID 1), **CE** (ID 2), and **TI** (ID 3).
</Warning>

## Example request

```bash theme={null}
curl -X POST "https://api.wava.co/v1/orders" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "description": "Invoice payment",
    "currency": "COP",
    "shopper": {
      "first_name": "Carlos",
      "last_name": "Rodriguez",
      "email": "carlos@email.com",
      "phone_number": "+573009876543",
      "country": "CO",
      "id_number": "87654321",
      "id_type": 1
    },
    "payment_gateway": {
      "id_payment_gateway": 9
    },
    "order_key": "invoice-11111"
  }'
```

## Example response

```json theme={null}
{
  "data": {
    "id_order": 12347,
    "status": "processing",
    "payment_gateway": {
      "breb": {
        "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA...",
        "key": "BREB-TXN-2025-ABCDEF123456"
      }
    }
  }
}
```

## Displaying the QR code

The `qr_code` field contains a base64-encoded PNG image. To display it in HTML:

```html theme={null}
<img src="data:image/png;base64,{qr_code_value}" alt="Payment QR Code" />
```

Display the `key` value as text alongside the QR code so the buyer can copy and paste it if they prefer not to scan.

## Important notes

* The buyer completes payment asynchronously (like Nequi), so you must rely on webhooks or polling for confirmation.
* Breb requires the same national ID fields as Daviplata, and only accepts CC, CE, and TI document types.
* The QR code and key have a limited validity window. If expired, cancel the order and create a new one.