Cobrar con link de pago

¿Qué vas a lograr?

Al terminar esta guía podrás crear cobros y enviarlos a tus clientes por múltiples canales. Todo se hace con un solo endpoint (POST /payments), y el canal de entrega depende de los campos que envíes.

Prerrequisitos

Cuenta de OnePay creada y verificada
Llaves de API generadas (ver cómo)
Webhooks configurados (ver cómo)

¿Qué canal necesitas?

Quiero…	Campo clave	¿Qué sucede?
Cobrar por WhatsApp	`phone`	El cliente recibe el link por WhatsApp
Cobrar por Email	`email`	El cliente recibe el link por correo
Crear un link de pago (monto fijo)	`amount`	Se genera un link con monto predefinido
Crear un link de pago (monto abierto)	Sin `amount`	El cliente ingresa el monto
Crear una referencia para el portal	`reference`	El cliente busca su cobro en el portal
Todos los canales	`phone` + `email` + `reference`	Se envía por todos los canales

Para ver ejemplos detallados de cada caso, consulta los Casos de uso de cobros.

Diagrama de flujo

Paso a paso

Crear la solicitud de cobro

Usa POST /payments con los campos que necesites según el canal de entrega:

WhatsApp
Email
Link manual
Monto abierto
Portal de pagos

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

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

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

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

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

Obtener el link de pago

En la respuesta recibirás un objeto con el payment_link:

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

Si enviaste phone: el cliente recibe el link automáticamente por WhatsApp.
Si enviaste email: el cliente recibe el link por correo electrónico.
Si enviaste reference: el cliente puede buscar el cobro en el portal de pagos.
Si no enviaste ninguno: copia payment_link y compártelo manualmente.

El cliente completa el pago

Al abrir el link, el cliente verá una página de pago con los métodos habilitados. Si el link es de monto abierto, el cliente ingresará el monto antes de pagar.

Recibe la notificación por webhook

Cuando el pago se complete, recibirás un webhook payment.approved:

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

Opciones adicionales

Configurar métodos de pago

Usa el campo allows para controlar qué métodos de pago estarán disponibles en el link:

{
  "allows": {
    "cards": true,
    "pse": true,
    "accounts": false,
    "wallets": true,
    "breb": true
  }
}

Establecer fecha de expiración

{
  "expiration_date": "2025-12-31 23:59:59"
}

Redireccionar después del pago

{
  "redirect_url": "https://tuapp.com/pago-exitoso"
}

Errores comunes

Error	Causa	Solución
`validation_error` (10001)	Falta el campo `title`	Asegúrate de enviar al menos el `title`
`idempotency_error` (10003)	Falta el header `x-idempotency`	Agrega un token de idempotencia único
Pago expirado	El cliente no pagó a tiempo	Crea un nuevo cobro o ajusta `expiration_date`

Inicio rápido

Cobrar (Recaudo)

Pagar (Dispersiones)

Webhooks

IA (MCP)

Verificación

Configuración

Artículos

¿Qué vas a lograr?

Prerrequisitos

¿Qué canal necesitas?

Diagrama de flujo

Paso a paso

Opciones adicionales

Configurar métodos de pago

Establecer fecha de expiración

Redireccionar después del pago

Errores comunes

Siguiente paso

Todos los casos de uso

Cobrar con débito directo

​¿Qué vas a lograr?

​Prerrequisitos

​¿Qué canal necesitas?

​Diagrama de flujo

​Paso a paso

​Opciones adicionales

​Configurar métodos de pago

​Establecer fecha de expiración

​Redireccionar después del pago

​Errores comunes

​Siguiente paso

Todos los casos de uso

Cobrar con débito directo

¿Qué vas a lograr?

Prerrequisitos

¿Qué canal necesitas?

Diagrama de flujo

Paso a paso

Opciones adicionales

Configurar métodos de pago

Establecer fecha de expiración

Redireccionar después del pago

Errores comunes

Siguiente paso