Introducción

¿Qué es un Cobro (Payment)?

Un cobro es una solicitud de pago que se envía al cliente. OnePay genera un link de pago único donde el cliente elige su método de pago preferido (tarjeta, PSE, Nequi, Daviplata, Bre-B, etc.).

Si necesitas debitar automáticamente un método de pago ya autorizado (sin intervención del cliente), usa Cargos (Charges) en su lugar.

¿Cuándo usar Cobros?

Facturas o pagos únicos donde el cliente elige cómo pagar
Cobros enviados por WhatsApp, email o link compartido
Pagos donde no tienes un método de pago registrado del cliente
Cobros con múltiples métodos de pago habilitados

Canales de envío

Canal	Campo clave	Descripción
WhatsApp	`phone`	El cliente recibe el link de pago directamente en su WhatsApp
Email	`email`	Se envía un correo electrónico con el link de pago
Link manual	Ninguno	Copia el `payment_link` de la respuesta y compártelo como quieras
Link monto abierto	Sin `amount`	El cliente ingresa el monto que desea pagar
Portal de recaudo	`reference`	El cliente busca su cobro por referencia en el portal

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

Ejemplo rápido

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

La respuesta incluye un payment_link que el cliente puede abrir para completar el pago.

Estados del cobro

Estado	Descripción
`pending`	Creado, esperando que el cliente pague
`in_progress`	El pago está siendo procesado
`approved`	Pago exitoso
`declined`	Pago rechazado por el banco o procesador
`cancelled`	Cobro cancelado manualmente
`expired`	El cobro expiró sin ser pagado
`partially_paid`	El cliente pagó un monto menor al requerido. Puede recibir pagos adicionales
`partial_expired`	El cobro parcial expiró sin completarse
`refunded`	Pago devuelto al cliente
`disputed`	El cliente abrió una disputa o contracargo
`issue`	Incidencia en el procesamiento — contacta soporte
`scheduled`	Pago programado para una fecha futura

Los cobros en estado partially_paid pueden seguir recibiendo pagos hasta completar el monto total o expirar. Suscríbete a los eventos payment.partially_paid y payment.partial_expired en tus webhooks para rastrear estos estados.

Configurar métodos de pago

Usa el campo allows para controlar qué métodos están disponibles en cada cobro:

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

Endpoints

Método	Endpoint	Descripción
`POST`	/payments	Crear cobro
`GET`	/payments	Listar cobros
`GET`	/payments/	Detalle de un cobro
`POST`	/payments//resend	Reenviar cobro al cliente
`DELETE`	/payments/	Eliminar cobro
`GET`	/payments//intents	Intentos de pago del cobro

API

Empresas

Métodos de pago

Recaudo

Balances

Webhooks

Fintech as a service

¿Qué es un Cobro (Payment)?

¿Cuándo usar Cobros?

Canales de envío

Ejemplo rápido

Estados del cobro

Configurar métodos de pago

Endpoints

​¿Qué es un Cobro (Payment)?

​¿Cuándo usar Cobros?

​Canales de envío

​Ejemplo rápido

​Estados del cobro

​Configurar métodos de pago

​Endpoints

¿Qué es un Cobro (Payment)?

¿Cuándo usar Cobros?

Canales de envío

Ejemplo rápido

Estados del cobro

Configurar métodos de pago

Endpoints