Skip to main content
POST
Crear cobro
Crea un nuevo pago en tu cuenta.

Headers

string
required
Token único para garantizar la idempotencia de la petición

Body

number
required
Monto a cobrar, en unidades mayores de la moneda (no en centavos). Enviar 1400000 con currency: "COP" cobra $1.400.000 COP.
No lo confundas con los campos de partial_payment_config, que sí van en centavos: los reconoces porque lo llevan en el nombre (min_amount_in_cents).
string
required
Breve mensaje que se mostrará al usuario al realizar el pago
string
Código de moneda ISO (COP, USD) por defecto COP
string
Número de teléfono del cliente a enviar la solicitud de pago via whatsapp.
string
Campo opcional si quieres enviar una solicitud de pago via email
string
Referencia de pago para que el usuario pueda interactuar con el portal de recaudo.
number
Monto en la misma moneda con valor de impuestos, el valor predeterminado será del 19%
string
ID externo para relacionar el pago con un registro ya existente en tu sistema.
string
Descripción del pago
string
URL de un documento que se mostrará al usuario para que pueda realizar el pago.
date
Fecha de pago oportuno, en formato YYYY-MM-DD HH:MM:SS.No bloquea el pago: pasada esta fecha el cobro se sigue pudiendo pagar. Su función es alimentar las reglas de cobranza (los recordatorios de “tu pago vence mañana” y de mora salen de acá). Es la misma fecha que el due_date de una factura, que se copia al cobro que la cobra.
date
Fecha de expiración del cobro, en formato YYYY-MM-DD HH:MM:SS.Sí bloquea el pago: al cumplirse, el cobro pasa a estado expired y deja de poder pagarse. Si no la envías se aplica la expiración por defecto configurada para tu empresa; si tu empresa no tiene una configurada, el cobro no expira.
Son dos fechas distintas y complementarias: due_date es hasta cuándo conviene pagar (blanda, dispara la cobranza) y expiration_date es hasta cuándo se puede pagar (dura, cierra el cobro). Podés enviar una, la otra o las dos.
date
Fecha en la que el cobro será enviado al usuario. YYYY-MM-DD.
object
Metadatos adicionales del pago en formato JSON
La llave template_id está reservada. Si la envías dentro de metadata recibirás un error 422: úsala como campo de primer nivel.
integer
Plantilla de WhatsApp con la que se enviará el cobro. Si no la envías, OnePay elige la plantilla según la configuración de tu canal.Obtén los valores válidos con GET /templates: solo sirven los id que traen selectable: true, es decir, plantillas aprobadas de categoría PAYMENT que pertenecen a tu empresa o son genéricas compartidas contigo.
Si la plantilla no existe, no está aprobada, no es de cobro o no está disponible para tu empresa, la petición falla con un error 422 y el cobro no se crea.
La plantilla queda fijada en el cobro: la verás en metadata.template_id de la respuesta y se usará también en los reenvíos. Si el cobro entra al motor de cobranzas, los recordatorios por etapa usan la plantilla configurada en la regla correspondiente.
string
URL de redirección
array
Los pagos divididos permiten distribuir automáticamente un único pago entre múltiples destinatarios según reglas preestablecidas, optimizando la gestión de fondos sin necesidad de cálculos manuales o costos adicionales.
object
Configuración para pagos parciales. Permite que un cobro sea pagado en múltiples transacciones.
Requiere que el feature Pagos Parciales esté habilitado en tu cuenta. Contacta a soporte para activarlo.
Métodos de pago permitidosEl método de pago disponible depende de la configuración de tu cuenta. Comunícate con el equipo de soporte para habilitar métodos adicionales.Solo uno de los dos (account_id o card_id) debe estar presente en la petición.

Ejemplos de uso

Response

string
Identificador único del pago
number
Monto del pago en pesos
string
Código de moneda ISO
string
Estado del pago:
  • pending - Pendiente
  • processing - Procesando
  • approved - Aprobado
  • declined - Rechazado
  • cancelled - Cancelado
  • expired - Expirado
  • partially_paid - Parcialmente pagado
  • partial_expired - Pago parcial expirado
string
ID del cliente que realizó el pago
string
Método de pago utilizado
string
Descripción del pago
object
Metadatos adicionales del pago
object
Información de pago parcial. Solo presente cuando partial_payment_config está configurado.
string
Fecha y hora de creación en formato ISO 8601

Ejemplo de respuesta