Casos de uso de cobros

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

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.

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.

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.

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

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:

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

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, envía el campo reference para que el cliente pueda buscar su cobro por referencia en el portal.

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

El portal de pagos se configura desde el administrador de OnePay. Puedes personalizar la imagen, textos y branding.

Combinar canales

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

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:

{
  "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:

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

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

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:

{
  "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:

<img src="data:image/png;base64,iVBORw0KGgoAAAANS..." alt="QR Bre-B" />

Flujo

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

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.

¿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 para ver el flujo completo con tarjetas, cuentas bancarias, Nequi y Daviplata.

API

Empresas

Métodos de pago

Recaudo

Balances

Webhooks

Fintech as a service

Un endpoint, múltiples canales

Cobrar por WhatsApp

Cobrar por Email

Link de pago con monto fijo

Link de pago con monto abierto

Referencia para el portal de pagos

Combinar canales

Resumen: ¿Qué campo uso?

Configurar métodos de pago disponibles

Escuchar el resultado

Cobrar con QR Bre-B

Mostrar el QR al cliente

Flujo

Expiración del QR

¿Necesitas debitar directamente?

​Un endpoint, múltiples canales

​Cobrar por WhatsApp

​Cobrar por Email

​Link de pago con monto fijo

​Link de pago con monto abierto

​Referencia para el portal de pagos

​Combinar canales

​Resumen: ¿Qué campo uso?

​Configurar métodos de pago disponibles

​Escuchar el resultado

​Cobrar con QR Bre-B

​Mostrar el QR al cliente

​Flujo

​Expiración del QR

​¿Necesitas debitar directamente?

Un endpoint, múltiples canales

Cobrar por WhatsApp

Cobrar por Email

Link de pago con monto fijo

Link de pago con monto abierto

Referencia para el portal de pagos

Combinar canales

Resumen: ¿Qué campo uso?

Configurar métodos de pago disponibles

Escuchar el resultado

Cobrar con QR Bre-B

Mostrar el QR al cliente

Flujo

Expiración del QR

¿Necesitas debitar directamente?