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_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -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 WhatsApp y el correo salen por defecto. Si envías notify: false, el cobro se crea sin avisarle al cliente aunque hayas enviado phone y email. Mira Crear el cobro sin avisar al cliente.

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

Crear el cobro sin avisar al cliente

Si tu sistema entrega el link por otro canal (impresión, tu propia app u otro proveedor de mensajería), envía notify: false. El cobro se crea igual y el link funciona, pero no sale WhatsApp ni correo al crearlo, aunque envíes phone y email:

{
  "notify": false
}

notify: false no silencia los webhooks, los recordatorios de las reglas de cobranza ni el reenvío manual. Consulta Crear cobro para ver todos los detalles.

Errores comunes

Error	Causa	Solución
`validation_error` (10001)	Falta el campo `title`	Asegúrate de enviar al menos el `title`
`validation_error` (10001)	`notify` no es booleano (por ejemplo, la cadena `"false"`)	Envía `true` o `false`
`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

Crear el cobro sin avisar al cliente

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

​Crear el cobro sin avisar al cliente

​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

Crear el cobro sin avisar al cliente

Errores comunes

Siguiente paso