Skip to main content

​
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 WhatsAppphoneEl cliente recibe el link de pago por WhatsApp automáticamente
Cobrar por EmailemailEl cliente recibe el link de pago por correo electrónico
Crear un link de pago (monto fijo)amountSe genera un payment_link con monto predefinido
Crear un link de pago (monto abierto)Sin amountSe genera un payment_link donde el cliente ingresa el monto
Crear una referencia para el portalreferenceEl cliente busca su cobro en el portal de pagos con esa referencia
Cobrar con QR Bre-BPOST /charges/bre-bSe genera un código QR que el cliente escanea desde su app bancaria
WhatsApp + Email + ReferenciaTodosSe 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": "[email protected]",
    "currency": "COP"
  }'
Resultado: El cliente recibe un correo electrónico con el link de pago y puede completar el pago desde ahí.
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.
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": "[email protected]",
    "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?

CampoTipoEfecto
amountnumberDefine el monto fijo. Si se omite, el link es de monto abierto
titlestringMensaje que ve el cliente en la página de pago (requerido)
phonestringEnvía el cobro por WhatsApp (formato E.164: +573201112233)
emailstringEnvía el cobro por email
referencestringCrea una referencia para el portal de pagos
redirect_urlstringURL de redirección después del pago
expiration_datedateFecha límite para pagar (YYYY-MM-DD HH:MM:SS)
allowsobjectControla 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

  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

​
Expiración del QR

ParámetroValor
Mínimo5 minutos
Máximo45 días (64800 minutos)
Por defecto15 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.