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

# Casos de uso de cobros

> Un solo endpoint, múltiples canales. Aprende qué campos enviar según cómo quieras cobrar.

## Un endpoint, múltiples canales

Todos los cobros se crean con el mismo endpoint `POST /payments`. Lo que cambia es **qué campos envías**, y eso determina cómo le llega el cobro a tu cliente.

| Quiero...                                 | Campo clave           | ¿Qué sucede?                                                                              |
| ----------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
| Cobrar por **WhatsApp**                   | `phone`               | El cliente recibe el link de pago por WhatsApp automáticamente                            |
| Cobrar por **Email**                      | `email`               | El cliente recibe el link de pago por correo electrónico                                  |
| Crear un **link de pago** (monto fijo)    | `amount`              | Se genera un `payment_link` con monto predefinido                                         |
| Crear un **link de pago** (monto abierto) | Sin `amount`          | Se genera un `payment_link` donde el cliente ingresa el monto                             |
| Crear una **referencia para el portal**   | `reference`           | El cliente busca su cobro en el [portal de pagos](/docs/config/portal) con esa referencia |
| Cobrar con **QR Bre-B**                   | `POST /charges/bre-b` | Se genera un código QR que el cliente escanea desde su app bancaria                       |
| **WhatsApp + Email + Referencia**         | Todos                 | Se envía por ambos canales y queda disponible en el portal                                |

<Note>
  Puedes combinar varios campos en una misma solicitud. Por ejemplo, enviar `phone` + `email` + `reference` para que el cobro llegue por todos los canales simultáneamente.
</Note>

***

## Cobrar por WhatsApp

Envía el campo `phone` con el número en formato E.164. OnePay envía automáticamente un mensaje de WhatsApp con el link de pago.

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: whatsapp-001" \
  -d '{
    "amount": 150000,
    "title": "Factura #1234",
    "phone": "+573201112233",
    "currency": "COP"
  }'
```

**Resultado:** El cliente recibe un mensaje de WhatsApp con el link de pago y los detalles del cobro. Al hacer clic, se abre la página de pago.

***

## Cobrar por Email

Envía el campo `email`. OnePay envía automáticamente un correo electrónico con el link de pago.

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: email-001" \
  -d '{
    "amount": 150000,
    "title": "Factura #1234",
    "email": "cliente@ejemplo.com",
    "currency": "COP"
  }'
```

**Resultado:** El cliente recibe un correo electrónico con el link de pago y puede completar el pago desde ahí.

***

## Link de pago con monto fijo

Si no necesitas enviar el cobro por WhatsApp ni email, simplemente crea el cobro con `amount` y `title`. Recibirás un `payment_link` que puedes compartir por el canal que prefieras (chat, redes sociales, SMS, etc.).

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: link-fijo-001" \
  -d '{
    "amount": 150000,
    "title": "Factura #1234",
    "currency": "COP"
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "amount": 150000,
  "status": "pending",
  "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  ...
}
```

**Resultado:** El cliente abre el link y ve el monto predefinido. Solo debe elegir el método de pago y completar la transacción.

***

## Link de pago con monto abierto

Si necesitas que el cliente **decida cuánto pagar** (donaciones, aportes voluntarios, pagos parciales), omite el campo `amount`.

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: link-abierto-001" \
  -d '{
    "title": "Donación Fundación ABC",
    "currency": "COP"
  }'
```

**Resultado:** El cliente abre el link y puede ingresar el monto que desee antes de completar el pago.

***

## Referencia para el portal de pagos

Si usas el [portal de pagos](/docs/config/portal), envía el campo `reference` para que el cliente pueda buscar su cobro por referencia en el portal.

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: portal-001" \
  -d '{
    "amount": 250000,
    "title": "Cuota mensual - Apartamento 401",
    "reference": "APTO-401-ENE-2025",
    "currency": "COP"
  }'
```

**Resultado:** El cliente ingresa al portal de pagos, busca la referencia `APTO-401-ENE-2025` y puede pagar directamente desde ahí.

<Note>
  El portal de pagos se configura desde el [administrador de OnePay](/docs/config/portal). Puedes personalizar la imagen, textos y branding.
</Note>

***

## Combinar canales

Puedes enviar múltiples campos para que el cobro llegue por varios canales a la vez:

```bash theme={null}
curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: multi-canal-001" \
  -d '{
    "amount": 350000,
    "title": "Mensualidad Febrero",
    "phone": "+573201112233",
    "email": "cliente@ejemplo.com",
    "reference": "MEM-2025-FEB",
    "currency": "COP",
    "redirect_url": "https://tuapp.com/pago-exitoso"
  }'
```

**Resultado:**

* El cliente recibe el cobro por WhatsApp
* También recibe el cobro por email
* Puede buscar la referencia en el portal de pagos
* Al pagar, es redirigido a `redirect_url`

***

## Resumen: ¿Qué campo uso?

| Campo             | Tipo     | Efecto                                                         |
| ----------------- | -------- | -------------------------------------------------------------- |
| `amount`          | `number` | Define el monto fijo. Si se omite, el link es de monto abierto |
| `title`           | `string` | Mensaje que ve el cliente en la página de pago (requerido)     |
| `phone`           | `string` | Envía el cobro por WhatsApp (formato E.164: `+573201112233`)   |
| `email`           | `string` | Envía el cobro por email                                       |
| `reference`       | `string` | Crea una referencia para el portal de pagos                    |
| `redirect_url`    | `string` | URL de redirección después del pago                            |
| `expiration_date` | `date`   | Fecha límite para pagar (`YYYY-MM-DD HH:MM:SS`)                |
| `allows`          | `object` | Controla qué métodos de pago están disponibles                 |

## Configurar métodos de pago disponibles

Usa el campo `allows` para controlar qué métodos de pago verá el cliente en el link:

```json theme={null}
{
  "allows": {
    "cards": true,
    "pse": true,
    "accounts": false,
    "wallets": true,
    "breb": true
  }
}
```

## Escuchar el resultado

Independientemente del canal que uses, el resultado del pago se notifica por [webhook](/client/webhooks/payments):

```json theme={null}
{
  "payment": {
    "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
    "status": "succeeded",
    "amount": 150000
  },
  "event": {
    "type": "payment.approved",
    "timestamp": 1689262934,
    "environment": "test"
  }
}
```

## Cobrar con QR Bre-B

[Bre-B](/client/breb/index) es el sistema de pagos inmediatos del Banco de la República. Con `POST /charges/bre-b` generas un código QR que el cliente escanea desde su aplicación bancaria para aprobar el pago al instante.

<Note>
  Este caso de uso usa un endpoint diferente (`POST /charges/bre-b`) en lugar de `POST /payments`.
</Note>

```bash theme={null}
curl https://api.onepay.la/v1/charges/bre-b \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: breb-qr-001" \
  -d '{
    "amount": 50000,
    "title": "Pago en tienda",
    "expires_in": 15
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "9e184fda-62bb-477b-9020-fa59f44f2b99",
  "amount": 50000,
  "status": "pending",
  "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
}
```

### Mostrar el QR al cliente

El campo `qr.image` contiene la imagen en base64. Muéstrala directamente en tu frontend:

```html theme={null}
<img src="data:image/png;base64,iVBORw0KGgoAAAANS..." alt="QR Bre-B" />
```

### Flujo

```mermaid theme={null}
sequenceDiagram
    participant Tu App
    participant OnePay API
    participant App Bancaria
    participant Usuario

    Tu App->>OnePay API: POST /charges/bre-b
    OnePay API-->>Tu App: QR (imagen base64)
    Tu App->>Usuario: Muestra el QR en pantalla
    Usuario->>App Bancaria: Escanea el QR
    App Bancaria->>OnePay API: Procesa el pago
    OnePay API->>Tu App: Webhook (aprobado/rechazado)
```

1. Tu sistema llama a `POST /charges/bre-b` para generar el QR
2. Muestras el QR al cliente (en pantalla, impreso, etc.)
3. El cliente escanea el QR desde su app bancaria
4. El banco procesa el pago en segundos
5. OnePay te notifica el resultado por [webhook](/client/webhooks/charges)

### Expiración del QR

| Parámetro   | Valor                   |
| ----------- | ----------------------- |
| Mínimo      | 5 minutos               |
| Máximo      | 45 días (64800 minutos) |
| Por defecto | 15 minutos              |

Una vez expirado, el QR ya no puede usarse y el cargo se marca como `failed`.

Para más detalles del endpoint, consulta la [referencia de QR Bre-B](/client/charges/bre-b).

***

## ¿Necesitas debitar directamente?

Si ya tienes la tarjeta o cuenta bancaria autorizada del cliente y quieres cobrar sin que el cliente interactúe con un link, consulta los [casos de uso de débitos automáticos](/client/use-cases/charges) para ver el flujo completo con tarjetas, cuentas bancarias, Nequi y Daviplata.