Crear cobro - OnePay Documentación

Crear cobro

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>",
  "expiration_date": "<string>",
  "schedule_at": "<string>",
  "metadata": {},
  "redirect_url": "<string>",
  "splits": [
    {
      "splits[].customer_id": "<string>",
      "splits[].split_type": "<string>",
      "splits[].split_value": 123,
      "splits[].description": "<string>",
      "splits[].account_id": "<string>",
      "splits[].scheduled_at": "<string>"
    }
  ],
  "partial_payment_config": {
    "min_amount_in_cents": 123,
    "max_amount_in_cents": 123,
    "max_payment_methods": 123,
    "timeout_hours": 123
  }
}
'

{
  "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": "+573201112233",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "due_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
}

POST

payments

Crear cobro

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>",
  "expiration_date": "<string>",
  "schedule_at": "<string>",
  "metadata": {},
  "redirect_url": "<string>",
  "splits": [
    {
      "splits[].customer_id": "<string>",
      "splits[].split_type": "<string>",
      "splits[].split_value": 123,
      "splits[].description": "<string>",
      "splits[].account_id": "<string>",
      "splits[].scheduled_at": "<string>"
    }
  ],
  "partial_payment_config": {
    "min_amount_in_cents": 123,
    "max_amount_in_cents": 123,
    "max_payment_methods": 123,
    "timeout_hours": 123
  }
}
'

{
  "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": "+573201112233",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "due_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 cuando el cliente recibe el pago

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.

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.

expiration_date

date

Fecha de expiración del pago en formato YYYY-MM-DD HH:MM:SS

schedule_at

date

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

metadata

object

Metadatos adicionales del pago en formato JSON

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 del monto total (en centésimas: 1000 = 10%)
fixed — Monto fijo 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: valor en centésimas (500 = 5%, 10000 = 100%)
Si split_type es fixed: monto en centavos

splits[].description

string

Descripción interna del split.

splits[].account_id

string

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

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.

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.

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
JavaScript
Python

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

import fetch from 'node-fetch';

const body = {
  amount: 1400000,
  currency: 'COP',
  title: 'Suscripción Premium',
  reference: 'INV-2045',
  phone: '+573201112233',
  email: 'customer@example.com',
  redirect_url: 'https://app.onepay.la/thanks',
  allows: {
    cards: true,
    accounts: true,
    pse: true
  },
  metadata: {
    salesforce_id: 'OP-554'
  }
};

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

import requests

payload = {
    "amount": 1400000,
    "currency": "COP",
    "title": "Suscripción Premium",
    "reference": "INV-2045",
    "phone": "+573201112233",
    "email": "customer@example.com",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
        "cards": True,
        "accounts": True,
        "pse": True
    },
    "metadata": {
        "salesforce_id": "OP-554"
    }
}

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

Response

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

description

string

Descripción del pago

metadata

object

Metadatos adicionales del pago

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

{
  "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": "+573201112233",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "due_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
}

Ver cobro

Reenviar cobro

​Headers

​Body

​Ejemplos de uso

​Response

​Ejemplo de respuesta

Headers

Body

Ejemplos de uso

Response

Ejemplo de respuesta