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. Se envía al crear el cobro (o en la fecha de scheduled_date, si la envías), salvo que mandes notify: false.
string
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).
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 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.
date
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.
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 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.
date
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.
object
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.
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. 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.
boolean
default:"true"
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.
Ahora el correo sí se envía. Antes, este endpoint guardaba el email del cobro pero no enviaba el correo. Con notify: true (o si lo omites), el cliente recibe la solicitud de pago por correo cuando envías email (con la excepción de los cobros programados que describe la última nota). Si ya mandabas email en tus cobros y no quieres que el cliente reciba ese correo, envía notify: false.El correo sale por una cola, no en el mismo instante de la petición, y solo se envía si tu empresa tiene habilitado el envío de correos, si el cliente no desactivó las notificaciones y si la dirección es entregable.
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}, o PUT /payments/{payment_id} con resend: 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í.
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.
object
Opciones de comportamiento del cobro.
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.
options.breb_key solo se acepta en cobros en COP, sin partial_payment_config y con Bre-B habilitado en los métodos de pago del cobro. En cualquier otro caso la petición falla con un error 422 sobre options.breb_key y el cobro no se crea.
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

Crear un cobro sin avisar al cliente

Con notify: 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.
Recuerda lo que notify: false no silencia: webhooks, recordatorios de cobranza y reenvíos manuales (ver las notas de notify arriba).

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 | null
Fecha de vencimiento del cobro (ISO 8601). No bloquea el pago.
string | null
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.
string
Descripción del pago
object
Metadatos adicionales del pago
object
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.
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