Crear cobro

POST /payments

Crear cobro

cURL

curl --request POST \
  --url https://api.onepay.la/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "amount": 123,
  "title": "<string>",
  "currency": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "reference": "<string>",
  "tax": 123,
  "external_id": "<string>",
  "description": "<string>",
  "document_url": "<string>",
  "due_date": "<string>",
  "timely_payment_date": "<string>",
  "expiration_date": "<string>",
  "scheduled_date": "<string>",
  "metadata": [
    {}
  ],
  "template_id": 123,
  "redirect_url": "<string>",
  "splits": [
    {
      "splits[].customer_id": "<string>",
      "splits[].split_type": "<string>",
      "splits[].split_value": 123,
      "splits[].description": "<string>",
      "splits[].account_id": "<string>",
      "splits[].to_company_wallet": true,
      "splits[].scheduled_at": "<string>"
    }
  ],
  "partial_payment_config": {
    "min_amount_in_cents": 123,
    "max_amount_in_cents": 123,
    "max_payment_methods": 123,
    "timeout_hours": 123
  },
  "options": {
    "breb_key": true
  }
}
'

Cobro estándar

{
  "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "source": "Suscripción Premium",
  "currency": "COP",
  "amount": 1400000,
  "amount_label": "$ 1.400.000",
  "title": "Suscripción Premium",
  "description": null,
  "phone": "[phone]",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "due_date": null,
  "timely_payment_date": null,
  "document_link": null,
  "external_id": null,
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "status": "pending",
  "is_test": false,
  "created_at": "2025-03-05T22:36:24.000000Z",
  "paid_at": null,
  "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "redirect_url": "https://app.onepay.la/thanks",
  "provider_id": null,
  "metadata": { "salesforce_id": "OP-554" },
  "customer": null,
  "method": null,
  "splits": [],
  "company": null,
  "commission": null
}

Crea un nuevo pago en tu cuenta.

Headers

x-idempotency · string · required

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

Body

amount · 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).

title · string · required

Breve mensaje que se mostrará al usuario al realizar el pago

currency · string

Código de moneda ISO (COP, USD) por defecto COP

phone · string

Número de teléfono del cliente a enviar la solicitud de pago via whatsapp.

email · string

Campo opcional si quieres enviar una solicitud de pago via email

reference · string

Referencia de pago para que el usuario pueda interactuar con el portal de recaudo.

tax · number

Monto en la misma moneda con valor de impuestos, el valor predeterminado será del 19%

external_id · string

ID externo para relacionar el pago con un registro ya existente en tu sistema.

description · string

Descripción del pago

document_url · string

URL de un documento que se mostrará al usuario para que pueda realizar el pago.

due_date · 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.

timely_payment_date · 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.

expiration_date · 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.

scheduled_date · date

Fecha en la que el cobro será enviado al usuario. YYYY-MM-DD.

metadata · array

Metadatos adicionales del pago, como una lista de pares key / value (ambos texto): [{"key": "salesforce_id", "value": "OP-554"}]. En la respuesta los verás como objeto: {"salesforce_id": "OP-554"}.

Envíalo como lista de pares, no como objeto: {"salesforce_id": "OP-554"} en el request devuelve un error 422.

La llave template_id está reservada. Si la envías dentro de metadata recibirás un error 422: úsala como campo de primer nivel.

template_id · 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.

redirect_url · string

URL de redirección

splits · 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.

Show Campos de splits[]

splits[].customer_id · string · required

ID del cliente beneficiario del split. Ver clientes.

splits[].split_type · string · required

Tipo de distribución:

• percentage — Porcentaje entero del monto total (10 = 10%)
• fixed — Monto fijo en unidades mayores de la moneda (no en centavos)

Si el total de splits supera el 100% del monto o excede el monto total, la operación será rechazada.

splits[].split_value · integer · required

Valor del split según el tipo:

• Si split_type es percentage: porcentaje entero (5 = 5%, 100 = 100%)
• Si split_type es fixed: monto en la misma unidad que amount (unidades mayores, no centavos)

Versiones anteriores de esta página describían el porcentaje “en centésimas” (10000 = 100%). Era un error: la suma de los splits de tipo percentage no puede pasar de 100, así que esos valores se rechazan con un 422.

splits[].description · string

Descripción interna del split.

splits[].account_id · string

ID de la cuenta donde se recibirá el split. Si no se especifica, se usa la cuenta principal del cliente.

Para dividir hacia otra empresa que usa OnePay, registra su saldo como una cuenta y usa ese account_id. Ver la guía.

splits[].to_company_wallet · boolean · deprecated

Forma anterior de dividir hacia el saldo de otra empresa: true y el identificador del saldo ajeno en account_id, en cada cobro.

Obsoleto. Registra ese saldo como una cuenta del cliente y usa customer_id + account_id como en cualquier otro split. Cómo migrar. Ambas formas funcionan durante la transición.

splits[].scheduled_at · string

Fecha programada para realizar el split (YYYY-MM-DD HH:mm:ss). Si es null, se ejecuta de inmediato.

partial_payment_config · 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.

Show Propiedades

min_amount_in_cents · integer

Monto mínimo por pago parcial en centavos. Mínimo: 100 (equivale a $1).

max_amount_in_cents · integer

Monto máximo por pago parcial en centavos. Si no se envía, el máximo es el saldo restante.

max_payment_methods · integer

Número máximo de pagos parciales permitidos. Mínimo: 2, Máximo: 10. Por defecto: 3.

timeout_hours · integer

Horas antes de que expire la ventana de pago parcial después del primer abono. Mínimo: 1, Máximo: 720. Por defecto: 24.

options · object

Opciones de comportamiento del cobro.

Show Propiedades

breb_key · boolean · default: "false"

Si es true, el cobro nace con una llave Bre-B propia de 30 días y su código QR, para imprimirlos en la factura física o en el recibo. Si el cliente transfiere a esa llave, el pago queda asociado a este cobro automáticamente. La llave y el QR vienen en el campo breb_key de la respuesta. Ejemplo: "options": { "breb_key": true }.

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 permitidos

El 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.

Método	Campo requerido	Descripción
Cuenta bancaria (ACH)	account_id	Débito directo desde cuenta bancaria registrada
Tarjeta de crédito/débito	card_id	Cargo a tarjeta tokenizada

Solo uno de los dos (account_id o card_id) debe estar presente en la petición.

Ejemplos de uso

curl

curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: payment-123" \
  -d '{
    "amount": 1400000,
    "currency": "COP",
    "title": "Suscripción Premium",
    "reference": "INV-2045",
    "phone": "[phone]",
    "email": "[e-mail]",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
      "cards": true,
      "accounts": true,
      "pse": true
    },
    "metadata": [
      { "key": "salesforce_id", "value": "OP-554" }
    ]
  }'

JavaScript

import fetch from 'node-fetch';

const body = {
  amount: 1400000,
  currency: 'COP',
  title: 'Suscripción Premium',
  reference: 'INV-2045',
  phone: '[phone]',
  email: '[e-mail]',
  redirect_url: 'https://app.onepay.la/thanks',
  allows: {
    cards: true,
    accounts: true,
    pse: true
  },
  metadata: [
    { key: 'salesforce_id', value: 'OP-554' }
  ]
};

await fetch('https://api.onepay.la/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
    'x-idempotency': 'payment-123'
  },
  body: JSON.stringify(body)
});

Python

import requests

payload = {
    "amount": 1400000,
    "currency": "COP",
    "title": "Suscripción Premium",
    "reference": "INV-2045",
    "phone": "[phone]",
    "email": "[e-mail]",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
        "cards": True,
        "accounts": True,
        "pse": True
    },
    "metadata": [
        {"key": "salesforce_id", "value": "OP-554"}
    ]
}

response = requests.post(
    "https://api.onepay.la/v1/payments",
    headers={
        "Authorization": "Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi",
        "x-idempotency": "payment-123"
    },
    json=payload,
    timeout=15
)
response.raise_for_status()
print(response.json())

Response

id · string

Identificador único del pago

amount · number

Monto del pago en pesos

currency · string

Código de moneda ISO

status · 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

customer_id · string

ID del cliente que realizó el pago

payment_method · string

Método de pago utilizado

due_date · string | null

Fecha de vencimiento del cobro (ISO 8601). No bloquea el pago.

timely_payment_date · 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.

description · string

Descripción del pago

metadata · object

Metadatos adicionales del pago

breb_key · 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.

Show Propiedades

breb_key.alias · string

Llave a la que el cliente transfiere, con el @ incluido (ej: @K7QM3P).

breb_key.expires_at · string

Fecha de vencimiento de la llave (ISO 8601), 30 días después de emitida.

breb_key.qr · object | null

Código QR de la llave con el monto del cobro. Es null si el QR todavía no se pudo generar; en ese caso OnePay lo reintenta y la llave sigue sirviendo para pagar.

Show Propiedades del QR

qr.image · string

Imagen PNG como data URI (data:image/png;base64,...), lista para un <img src>.

qr.string · string

Contenido del QR (payload EMV), por si prefieres generar la imagen tú mismo.

qr.id · string

Identificador del QR.

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.

partial_payment · object

Información de pago parcial. Solo presente cuando partial_payment_config está configurado.

Show Propiedades

partial_payment.total_paid_in_cents · integer

Total pagado hasta el momento en centavos

partial_payment.total_paid_label · string

Total pagado formateado (ej: “$50.000”)

partial_payment.remaining_amount_in_cents · integer

Saldo restante por pagar en centavos

partial_payment.remaining_label · string

Saldo restante formateado

partial_payment.progress_percentage · number

Porcentaje de progreso del pago (0 a 100)

partial_payment.is_fully_paid · boolean

Indica si el pago fue completado totalmente

partial_payment.min_amount_in_cents · integer

Monto mínimo por pago parcial en centavos

partial_payment.max_amount_in_cents · integer

Monto máximo por pago parcial en centavos

partial_payment.max_payment_methods · integer

Número máximo de pagos parciales permitidos

partial_payment.timeout_hours · integer

Horas de expiración configuradas

partial_payment.partial_expires_at · string

Fecha de expiración del pago parcial (ISO 8601). Se establece después del primer abono.

partial_payment.charges · array

Lista de cargos pagados

Show Propiedades del cargo

charges[].id · string

ID del cargo

charges[].amount_in_cents · integer

Monto del cargo en centavos

charges[].amount_label · string

Monto formateado

charges[].payment_method_type · string

Tipo de método de pago (ej: “card”, “account”, “pse”)

charges[].payment_method · string

Descripción del método de pago

charges[].paid_at · string

Fecha de pago (ISO 8601)

created_at · string

Fecha y hora de creación en formato ISO 8601

Ejemplo de respuesta

Cobro estándar

{
  "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "source": "Suscripción Premium",
  "currency": "COP",
  "amount": 1400000,
  "amount_label": "$ 1.400.000",
  "title": "Suscripción Premium",
  "description": null,
  "phone": "[phone]",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "due_date": null,
  "timely_payment_date": null,
  "document_link": null,
  "external_id": null,
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "status": "pending",
  "is_test": false,
  "created_at": "2025-03-05T22:36:24.000000Z",
  "paid_at": null,
  "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "redirect_url": "https://app.onepay.la/thanks",
  "provider_id": null,
  "metadata": { "salesforce_id": "OP-554" },
  "customer": null,
  "method": null,
  "splits": [],
  "company": null,
  "commission": null
}