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

# Crear un QR (Bre-B)

> Endpoint para crear un código QR para pagos con Bre-B.

Este endpoint permite generar un código QR para recibir pagos a través del sistema BRE-B (Banco de la República). El cliente escanea el código QR desde su aplicación bancaria para completar el pago.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="amount" type="number" required placeholder="15000">
  Monto a cobrar en pesos colombianos. Mínimo: 1000 COP.
</ParamField>

<ParamField body="customer_id" type="string" placeholder="9dd4158b-0e45-42bc-b56f-a4c1f856814d">
  ID del cliente que realizará el pago. Opcional. [Crear cliente](/client/customers/create).
</ParamField>

<ParamField body="title" type="string" placeholder="Pago de servicio">
  Título descriptivo del pago. Por defecto: "Pago BRE-B".
</ParamField>

<ParamField body="description" type="string" placeholder="Pago mensual del servicio">
  Descripción detallada del pago.
</ParamField>

<ParamField body="external_id" type="string" placeholder="order-123">
  Identificador único del pago en tu sistema.
</ParamField>

<ParamField body="expires_in" type="integer" placeholder="15">
  Tiempo de expiración del QR en minutos. Mínimo: 5, Máximo: 64800 (45 días). Por defecto: 15 minutos.
</ParamField>

<Note>
  El campo `qr.image` contiene la imagen del código QR en formato base64. Debes mostrarla al usuario para que la escanee desde su aplicación bancaria.

  ```html theme={null}
  <img src="data:image/png;base64,iVBORw0KGgoAAAANS..." />
  ```
</Note>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "9e184fda-62bb-477b-9020-fa59f44f2b99",
    "source": "Pago BRE-B",
    "currency": "COP",
    "amount": 15000,
    "amount_label": "$15.000",
    "title": "Pago BRE-B",
    "description": null,
    "phone": null,
    "expiration_at": null,
    "due_date": null,
    "document_link": null,
    "external_id": "order-123",
    "allows": null,
    "status": "pending",
    "is_test": false,
    "created_at": "2026-01-30T15:30:00.000000Z",
    "paid_at": null,
    "payment_link": null,
    "redirect_url": null,
    "provider_id": null,
    "qr": {
      "image": "data:image/png;base64,iVBORw0KGgoAAAANS...",
      "string": "00020101021226ABC123...",
      "id": "ABC123DEF456789"
    },
    "key": {
      "alias": "@A1B2C3D4",
      "id": "9e184fda-1234-5678-9020-fa59f44f2b99"
    },
    "expires_at": "2026-01-30T15:45:00.000000Z",
    "expires_in_seconds": 900,
    "customer": {
      "id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan@example.com",
      "phone": "+573001234567",
      "document_type": "CC",
      "document_number": "1234567890",
      "created_at": "2026-01-15T10:00:00.000000Z",
      "is_test": false
    }
  }
  ```

  ```json 422 theme={null}
  {
    "message": "El campo cantidad es obligatorio.",
    "code": 10001,
    "code_name": "validation_error",
    "errors": {
      "amount": [
        "El campo cantidad es obligatorio."
      ]
    }
  }
  ```

  ```json 503 theme={null}
  {
    "message": "No se pudo generar el código QR. Intente nuevamente.",
    "code": 90100,
    "code_name": "qr_generation_failed"
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>

### Campos de respuesta

| Campo                | Tipo    | Descripción                                  |
| -------------------- | ------- | -------------------------------------------- |
| `id`                 | string  | ID único del pago                            |
| `qr.image`           | string  | Imagen del QR en base64                      |
| `qr.string`          | string  | Contenido del QR como texto                  |
| `qr.id`              | string  | ID del QR en el sistema BRE-B                |
| `key.alias`          | string  | Alias de la llave BRE-B (ej: @A1B2C3D4)      |
| `key.id`             | string  | ID interno de la llave                       |
| `expires_at`         | string  | Fecha y hora de expiración (ISO 8601)        |
| `expires_in_seconds` | integer | Segundos restantes hasta la expiración       |
| `status`             | string  | Estado del pago: `pending`, `paid`, `failed` |

### Flujo de pago

1. Tu sistema llama a este endpoint para generar el QR
2. Muestra el QR al cliente
3. El cliente escanea el QR desde su app bancaria
4. El banco procesa el pago
5. OnePay envía un [webhook](/client/webhooks/charges) con el resultado
6. Tu sistema actualiza el estado del pedido

### Expiración

El QR tiene un tiempo de vida configurable mediante el parámetro `expires_in`:

* **Mínimo**: 5 minutos
* **Máximo**: 64800 minutos (45 días)
* **Por defecto**: 15 minutos

Una vez expirado, el QR ya no puede ser usado para realizar pagos y el cargo se marcará como `failed`.