Skip to main content

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

CanalCampo claveDescripción
WhatsAppphoneEl cliente recibe el link de pago directamente en su WhatsApp
EmailemailSe envía un correo electrónico con el link de pago
Link manualNingunoCopia el payment_link de la respuesta y compártelo como quieras
Link monto abiertoSin amountEl cliente ingresa el monto que desea pagar
Portal de recaudoreferenceEl 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

EstadoDescripción
pendingCreado, esperando que el cliente pague
in_progressEl pago está siendo procesado
approvedPago exitoso
declinedPago rechazado por el banco o procesador
cancelledCobro cancelado manualmente
expiredEl cobro expiró sin ser pagado
partially_paidEl cliente pagó un monto menor al requerido. Puede recibir pagos adicionales
partial_expiredEl cobro parcial expiró sin completarse
refundedPago devuelto al cliente
disputedEl cliente abrió una disputa o contracargo
issueIncidencia en el procesamiento — contacta soporte
scheduledPago 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étodoEndpointDescripción
POST/paymentsCrear cobro
GET/paymentsListar cobros
GET/payments/Detalle de un cobro
POST/payments//resendReenviar cobro al cliente
DELETE/payments/Eliminar cobro
GET/payments//intentsIntentos de pago del cobro