Actualizar factura

curl https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a \
  -X PUT \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": false
  }'

const response = await fetch('https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'INV-12345678',
    amount: 75000,
    name: 'Internet plan - Actualizado',
    description: 'Plan 100MB - facturación octubre',
    email: 'juan@example.com',
    phone: '+573001234567',
    provider_id: '987654',
    due_date: '2026-10-31',
    timely_payment_date: '2026-10-25',
    notify: false
  })
});
const invoice = await response.json();
console.log(invoice.id); // ID de la factura actualizada

import requests

url = "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a"
headers = {
    "Authorization": "Bearer sk_test_xxx",
    "Content-Type": "application/json"
}
data = {
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": False
}

response = requests.put(url, headers=headers, json=data)
invoice = response.json()
print(invoice["id"])  # ID de la factura actualizada

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "reference" => "INV-12345678",
        "amount" => 75000,
        "name" => "Internet plan - Actualizado",
        "description" => "Plan 100MB - facturación octubre",
        "email" => "juan@example.com",
        "phone" => "+573001234567",
        "provider_id" => "987654",
        "due_date" => "2026-10-31",
        "timely_payment_date" => "2026-10-25",
        "notify" => false
    ])
]);

$response = curl_exec($ch);
$invoice = json_decode($response, true);

echo $invoice["id"]; // ID de la factura actualizada

curl_close($ch);
?>

{
  "id": "2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
  "name": "Internet plan - Actualizado",
  "description": "Factura de internet actualizada para octubre 2025",
  "provider": "biller",
  "provider_id": "987654",
  "reference": "INV-12345678",
  "status": "CREATED",
  "remarks": null,
  "due_date": "2026-10-31T00:00:00Z",
  "timely_payment_date": "2026-10-25T00:00:00Z",
  "created_at": "2025-10-20T15:06:00Z",
  "updated_at": "2025-10-20T15:06:00Z",
  "metadata": {
    "key": "value"
  },
  "payment": {
    "id": "new-payment-id",
    "title": "Internet plan - Actualizado",
    "description": "Internet plan - Actualizado",
    "currency": "COP",
    "amount": 75000,
    "amount_label": "75.000",
    "due_date": "2026-10-31T00:00:00Z",
    "timely_payment_date": "2026-10-25T00:00:00Z",
    "phone": "+573167591039",
    "external_id": "987654",
    "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
    "status": "pending",
    "is_test": false,
    "payment_link": "https://pay.onepay.test/p/new-payment-id",
    "redirect_url": null,
    "created_at": "2025-10-20T15:25:00Z"
  }
}

{
  "message":"La solicitud contiene errores de validación.",
  "code":10001,
  "code_name":"validation_error",
  "errors":{
    "reference":["El campo referencia es obligatorio."],
    "amount":["El monto debe ser al menos 5000."],
    "name":["El nombre debe tener al menos 5 caracteres."],
    "phone":["El teléfono debe estar en formato E.164."],
    "email":["El correo electrónico no es válido."]
  }
}

{
  "message": "La factura no existe o pertenece a otra compañía"
}

PUT

invoices

{invoice_id}

curl https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a \
  -X PUT \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": false
  }'

const response = await fetch('https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'INV-12345678',
    amount: 75000,
    name: 'Internet plan - Actualizado',
    description: 'Plan 100MB - facturación octubre',
    email: 'juan@example.com',
    phone: '+573001234567',
    provider_id: '987654',
    due_date: '2026-10-31',
    timely_payment_date: '2026-10-25',
    notify: false
  })
});
const invoice = await response.json();
console.log(invoice.id); // ID de la factura actualizada

import requests

url = "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a"
headers = {
    "Authorization": "Bearer sk_test_xxx",
    "Content-Type": "application/json"
}
data = {
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": False
}

response = requests.put(url, headers=headers, json=data)
invoice = response.json()
print(invoice["id"])  # ID de la factura actualizada

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "reference" => "INV-12345678",
        "amount" => 75000,
        "name" => "Internet plan - Actualizado",
        "description" => "Plan 100MB - facturación octubre",
        "email" => "juan@example.com",
        "phone" => "+573001234567",
        "provider_id" => "987654",
        "due_date" => "2026-10-31",
        "timely_payment_date" => "2026-10-25",
        "notify" => false
    ])
]);

$response = curl_exec($ch);
$invoice = json_decode($response, true);

echo $invoice["id"]; // ID de la factura actualizada

curl_close($ch);
?>

{
  "id": "2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
  "name": "Internet plan - Actualizado",
  "description": "Factura de internet actualizada para octubre 2025",
  "provider": "biller",
  "provider_id": "987654",
  "reference": "INV-12345678",
  "status": "CREATED",
  "remarks": null,
  "due_date": "2026-10-31T00:00:00Z",
  "timely_payment_date": "2026-10-25T00:00:00Z",
  "created_at": "2025-10-20T15:06:00Z",
  "updated_at": "2025-10-20T15:06:00Z",
  "metadata": {
    "key": "value"
  },
  "payment": {
    "id": "new-payment-id",
    "title": "Internet plan - Actualizado",
    "description": "Internet plan - Actualizado",
    "currency": "COP",
    "amount": 75000,
    "amount_label": "75.000",
    "due_date": "2026-10-31T00:00:00Z",
    "timely_payment_date": "2026-10-25T00:00:00Z",
    "phone": "+573167591039",
    "external_id": "987654",
    "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
    "status": "pending",
    "is_test": false,
    "payment_link": "https://pay.onepay.test/p/new-payment-id",
    "redirect_url": null,
    "created_at": "2025-10-20T15:25:00Z"
  }
}

{
  "message":"La solicitud contiene errores de validación.",
  "code":10001,
  "code_name":"validation_error",
  "errors":{
    "reference":["El campo referencia es obligatorio."],
    "amount":["El monto debe ser al menos 5000."],
    "name":["El nombre debe tener al menos 5 caracteres."],
    "phone":["El teléfono debe estar en formato E.164."],
    "email":["El correo electrónico no es válido."]
  }
}

{
  "message": "La factura no existe o pertenece a otra compañía"
}

Facturas con pagos parciales: Si la factura tiene un Payment en estado partially_paid, actualizarla cancelará ese Payment (y perderá todos los abonos registrados) y creará uno nuevo sin configuración de pagos parciales. Solo actualiza facturas parcialmente pagadas si estás seguro de que quieres reiniciar el proceso de cobro.Si el Payment ya está approved, la actualización solo modifica los metadatos de la factura sin cancelar ni reemplazar el Payment. En ese caso notify no tiene efecto: como no se genera un cobro nuevo, no hay nada que enviarle al cliente.

Path params

string

required

ID de la factura a actualizar. Crear factura.

Body

string

required

Referencia única de la factura dentro de tu compañía. Mínimo 5 y máximo 100 caracteres.

string

Identificador opcional que asocias a tu proveedor externo.

number

required

Monto de la factura en pesos (COP). Debe estar entre 5.000 y 100.000.000.

string

required

Nombre o concepto de la factura. Mínimo 5 y máximo 100 caracteres.

string

Descripción detallada de la factura. Se propaga al nuevo Payment generado. Mínimo 4 y máximo 2000 caracteres.

string

Número de teléfono del cliente en formato E.164. Opcional.

string

Correo electrónico del cliente. Opcional. Máximo 200 caracteres.

string

Fecha de vencimiento de la factura en formato YYYY-MM-DD (ej. 2026-10-31). Opcional. No bloquea el pago. Alimenta las reglas de cobranza ancladas al vencimiento (recordatorios de “por vencer”, “vence hoy” y mora). Si se omite o se envía null, se conserva el due_date actual de la factura. El valor se propaga al nuevo Payment generado durante la actualización.

string

Fecha de pago oportuno: último día para pagar sin recargo ni suspensión del servicio, en formato YYYY-MM-DD (ej. 2026-10-25). Opcional. Es informativa: no bloquea el pago ni expira el cobro, y es distinta del due_date — una factura puede tener las dos. Si se omite o se envía null, se conserva el timely_payment_date actual de la factura. El valor se propaga al nuevo Payment generado durante la actualización, y 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).

Si no envías due_date o timely_payment_date en la actualización, la factura conserva su fecha de vencimiento y su fecha de pago oportuno actuales. Solo se modifican cuando envías un valor explícito.

boolean

default:"true"

Controla si se le avisa al cliente sobre el cobro nuevo. Con false la factura se actualiza y el cobro se reemplaza igual, pero no se envía el mensaje de WhatsApp ni el correo al cliente. Por defecto (true u omitido) sí se envían.

notify: false deja al cliente con el link anterior: actualizar una factura cancela el cobro anterior y crea uno nuevo con un link de pago distinto. Si silencias el aviso, el cliente se queda con el link viejo, que ya quedó cancelado y no se puede pagar.Para avisarle más tarde, usa el payment.id que devuelve la respuesta contra Reenviar cobro (POST /v1/payments/{payment_id}).

El envío puede diferirse. Con notify: true (o si lo omites), el mensaje solo sale dentro de la ventana de contacto de Colombia: lunes a viernes de 7:00 a.m. a 7:00 p.m. y sábados de 8:00 a.m. a 3:00 p.m. (hora de Bogotá). Domingos y festivos colombianos no se contacta.Si la actualización cae fuera de esa ventana, el mensaje se programa automáticamente para la siguiente ventana válida: no es una falla ni requiere reintento de tu parte. Es el comportamiento propio de los cobros originados en facturas; el reenvío manual de un cobro con Reenviar cobro sí sale de inmediato.

curl https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a \
  -X PUT \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": false
  }'

const response = await fetch('https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer sk_test_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'INV-12345678',
    amount: 75000,
    name: 'Internet plan - Actualizado',
    description: 'Plan 100MB - facturación octubre',
    email: 'juan@example.com',
    phone: '+573001234567',
    provider_id: '987654',
    due_date: '2026-10-31',
    timely_payment_date: '2026-10-25',
    notify: false
  })
});
const invoice = await response.json();
console.log(invoice.id); // ID de la factura actualizada

import requests

url = "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a"
headers = {
    "Authorization": "Bearer sk_test_xxx",
    "Content-Type": "application/json"
}
data = {
    "reference": "INV-12345678",
    "amount": 75000,
    "name": "Internet plan - Actualizado",
    "description": "Plan 100MB - facturación octubre",
    "email": "juan@example.com",
    "phone": "+573001234567",
    "provider_id": "987654",
    "due_date": "2026-10-31",
    "timely_payment_date": "2026-10-25",
    "notify": False
}

response = requests.put(url, headers=headers, json=data)
invoice = response.json()
print(invoice["id"])  # ID de la factura actualizada

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_test_xxx",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "reference" => "INV-12345678",
        "amount" => 75000,
        "name" => "Internet plan - Actualizado",
        "description" => "Plan 100MB - facturación octubre",
        "email" => "juan@example.com",
        "phone" => "+573001234567",
        "provider_id" => "987654",
        "due_date" => "2026-10-31",
        "timely_payment_date" => "2026-10-25",
        "notify" => false
    ])
]);

$response = curl_exec($ch);
$invoice = json_decode($response, true);

echo $invoice["id"]; // ID de la factura actualizada

curl_close($ch);
?>

Response

{
  "id": "2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
  "name": "Internet plan - Actualizado",
  "description": "Factura de internet actualizada para octubre 2025",
  "provider": "biller",
  "provider_id": "987654",
  "reference": "INV-12345678",
  "status": "CREATED",
  "remarks": null,
  "due_date": "2026-10-31T00:00:00Z",
  "timely_payment_date": "2026-10-25T00:00:00Z",
  "created_at": "2025-10-20T15:06:00Z",
  "updated_at": "2025-10-20T15:06:00Z",
  "metadata": {
    "key": "value"
  },
  "payment": {
    "id": "new-payment-id",
    "title": "Internet plan - Actualizado",
    "description": "Internet plan - Actualizado",
    "currency": "COP",
    "amount": 75000,
    "amount_label": "75.000",
    "due_date": "2026-10-31T00:00:00Z",
    "timely_payment_date": "2026-10-25T00:00:00Z",
    "phone": "+573167591039",
    "external_id": "987654",
    "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
    "status": "pending",
    "is_test": false,
    "payment_link": "https://pay.onepay.test/p/new-payment-id",
    "redirect_url": null,
    "created_at": "2025-10-20T15:25:00Z"
  }
}

{
  "message":"La solicitud contiene errores de validación.",
  "code":10001,
  "code_name":"validation_error",
  "errors":{
    "reference":["El campo referencia es obligatorio."],
    "amount":["El monto debe ser al menos 5000."],
    "name":["El nombre debe tener al menos 5 caracteres."],
    "phone":["El teléfono debe estar en formato E.164."],
    "email":["El correo electrónico no es válido."]
  }
}

{
  "message": "La factura no existe o pertenece a otra compañía"
}

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Path params

Body

Response

​Path params

​Body

​Response

Path params

Body

Response