Crear cobro
POST
Crear cobro
Crea un nuevo pago en tu cuenta.
Recuerda lo que
Headers
Body
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).Número de teléfono del cliente a enviar la solicitud de pago via whatsapp. Se envía al crear el cobro (o en la fecha de
scheduled_date, si la envías), salvo que mandes notify: false.Correo del cliente. Si lo envías, el cliente recibe la solicitud de pago por correo al crear el cobro, igual que el WhatsApp de
phone. Hoy los cobros programados (scheduled_date) no envían correo; mira la nota de cobros programados en notify. Para crear el cobro sin enviar el correo, manda notify: false (ver el campo notify más abajo).Fecha de vencimiento del cobro, 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 ancladas al vencimiento (los
recordatorios de “por vencer”, “vence hoy” 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.Fecha de pago oportuno, en formato
YYYY-MM-DD (también acepta fecha y hora):
el último día para
pagar sin recargo ni suspensión del servicio.Es informativa: no bloquea el pago ni expira el cobro. Es distinta de
due_date — un recibo puede tener las dos. Las reglas de cobranza pueden anclar
recordatorios a esta fecha (disparadores “antes”, “el día” y “después” del pago
oportuno, configurables en el portal). Es la misma fecha que el
timely_payment_date de una factura, que se copia al cobro que la cobra.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 tres fechas distintas y complementarias:
due_date es cuándo vence el
documento (blanda, ancla los recordatorios de vencimiento y mora),
timely_payment_date es hasta cuándo se puede pagar sin recargo (blanda,
informativa, ancla los recordatorios de pago oportuno) y expiration_date es
hasta cuándo se puede pagar (dura, cierra el cobro). Puedes enviar una,
varias o las tres.Fecha en la que el cobro será enviado al usuario.
YYYY-MM-DD.Con notify: false, en esa fecha el cobro se activa y queda pagable, pero no se envía. Mira la nota sobre cobros programados en notify.Metadatos adicionales del pago, como un objeto de llaves y valores de texto:
{"salesforce_id": "OP-554"}.También se acepta como lista de pares key / value: [{"key": "salesforce_id", "value": "OP-554"}]. En la respuesta siempre lo verás como objeto.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.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. Puedes cambiarla, junto con los valores de sus marcadores, al reenviar el cobro. Si el cobro entra al motor de cobranzas, los recordatorios por etapa usan la plantilla configurada en la regla correspondiente.Controla si el cliente recibe el aviso del cobro al crearlo. Con
true (o si lo omites) se envía WhatsApp si viene phone y correo si viene email. Con false el cobro se crea igual y la respuesta es idéntica, pero no sale ni WhatsApp ni correo, aunque envíes phone y email. El link de pago funciona y el cliente puede pagar.Acepta true o false y también 1, 0, "1" y "0". Cualquier otro valor —por ejemplo la cadena "false" o "maybe"— devuelve un error 422 sobre el campo notify.Úsalo cuando tu sistema entrega el link de pago por otro canal: impresión, tu propia app u otro proveedor de mensajería. Si después quieres avisarle al cliente, reenvía el cobro.notify: false solo silencia el aviso al crear el cobro. No silencia:- Los webhooks a tu sistema: salen igual, así que tu integración se entera de todo sin ningún cambio.
- Los recordatorios de las reglas de cobranza de tu empresa (por vencimiento, mora, etc.): siguen su curso. Lo que sí se omite es el aviso inmediato que una regla «al crear el cobro» enviaría cuando nace el cobro.
- El reenvío manual:
POST /payments/{payment_id}, oPUT /payments/{payment_id}conresend: true, envía normalmente. - El link de pago: funciona y el cliente puede pagar, lo hayas avisado o no.
Cobros programados (
scheduled_date). Con notify: false, en la fecha programada el cobro se activa y queda pagable, pero tampoco se envía.Con notify: true, hoy un cobro programado con email no recibe correo: por ahora ningún cobro programado lo envía. El WhatsApp sí sale en la fecha programada. Es el comportamiento actual y puede cambiar, así que no construyas tu integración asumiendo que seguirá siendo así.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.
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.
Cómo funciona la llave Bre-B del cobro (
options.breb_key)- Es una llave aleatoria de 6 caracteres (por ejemplo
@K7QM3P) y vence a los 30 días. - Exige el monto exacto del cobro, y el QR ya trae ese monto cargado. Es de un solo uso.
- Mientras la llave está vigente, el cliente puede pagar el cobro por cualquier otro medio (PSE, tarjeta, WhatsApp, link de pago).
- Si el cobro se paga por otro medio, se cancela, expira o se elimina, la llave se da de baja.
- Si cambias el monto del cobro con
PUT /payments/{id}, la llave anterior se da de baja y se emite una nueva, con otro alias y otro QR. La factura impresa con la llave anterior deja de servir. - La llave no se renueva sola al vencer.
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
- curl
- JavaScript
- Python
Crear un cobro sin avisar al cliente
Connotify: false el cobro se crea y devuelve su payment_link, pero no sale WhatsApp ni correo aunque envíes phone y email. Útil cuando tu sistema entrega el link por otro canal.
- curl
- JavaScript
- Python
notify: false no silencia: webhooks, recordatorios de cobranza y reenvíos manuales (ver las notas de notify arriba).
Response
Estado del pago:
pending- Pendienteprocessing- Procesandoapproved- Aprobadodeclined- Rechazadocancelled- Canceladoexpired- Expiradopartially_paid- Parcialmente pagadopartial_expired- Pago parcial expirado
Fecha de pago oportuno (ISO 8601): último día para pagar sin recargo ni
suspensión. Informativa: no bloquea el pago ni expira el cobro.
Llave Bre-B del cobro para imprimir en la factura. Solo presente cuando el cobro se creó con
options.breb_key: true y la llave está vigente: emitida, sin vencer y con el cobro abierto.Si la llave no se pudo emitir al crear el cobro, el cobro se crea igual sin
breb_key y OnePay
reintenta la emisión. Consulta el cobro con GET /payments/{id} para
obtenerla.En modo de prueba (
sk_test_) la llave no se registra en Bre-B. Recibes un alias y una imagen
de QR de referencia para probar tu integración, pero no se pueden pagar.Ejemplo de respuesta
Crear cobro