Crear un QR (Bre-B)

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

POST https://api.onepay.la/v1/charges/bre-b

Crear un QR (Bre-B)

cURL

curl --request POST \
  --url https://api.onepay.la/v1/charges/bre-b \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "amount": 123,
  "customer_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "external_id": "<string>",
  "expires_in": 123
}
'

201

{
  "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": "[e-mail]",
    "phone": "[phone]",
    "document_type": "CC",
    "document_number": "1234567890",
    "created_at": "2026-01-15T10:00:00.000000Z",
    "is_test": false
  }
}

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

x-idempotency · string · required

Token único para garantizar la idempotencia de la petición

Body

amount · number · required

Monto a cobrar en pesos colombianos. Mínimo: 1000 COP.

customer_id · string

ID del cliente que realizará el pago. Opcional. Crear cliente.

title · string

Título descriptivo del pago. Por defecto: “Pago BRE-B”.

description · string

Descripción detallada del pago.

external_id · string

Identificador único del pago en tu sistema.

expires_in · integer

Tiempo de expiración del QR en minutos. Mínimo: 5, Máximo: 64800 (45 días). Por defecto: 15 minutos.

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.

<img src="data:image/png;base64,iVBORw0KGgoAAAANS..." />

201

{
  "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": "[e-mail]",
    "phone": "[phone]",
    "document_type": "CC",
    "document_number": "1234567890",
    "created_at": "2026-01-15T10:00:00.000000Z",
    "is_test": false
  }
}

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 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.