Empresas
Métodos de pago
Recaudo
Dispersiones
Webhooks
Fintech as a service
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
}
Crear cobro
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
Token único para garantizar la idempotencia de la petición
Body
Monto a cobrar cuando el cliente recibe el pago
Breve mensaje que se mostrará al usuario al realizar el pago
Código de moneda ISO (COP, USD) por defecto COP
Número de teléfono del cliente a enviar la solicitud de pago via whatsapp.
Campo opcional si quieres enviar una solicitud de pago via email
Referencia de pago para que el usuario pueda interactuar con el portal de recaudo.
Monto en la misma moneda con valor de impuestos, el valor predeterminado será del 19%
ID externo para relacionar el pago con un registro ya existente en tu sistema.
Descripción del pago
URL de un documento que se mostrará al usuario para que pueda realizar el pago.
Fecha de expiración del pago en formato YYYY-MM-DD HH:MM:SS
Fecha en la que el pago será enviado al usuario. YYYY-MM-DD.
Metadatos adicionales del pago en formato JSON
URL de redirección
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[]
Show Campos de splits[]
ID del cliente beneficiario del split. Ver clientes.
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.
Valor del split según el tipo:
- Si
split_typeespercentage: valor en centésimas (500= 5%,10000= 100%) - Si
split_typeesfixed: monto en centavos
Descripción interna del split.
ID de la cuenta bancaria donde se recibirá el split. Si no se especifica, se usa la cuenta principal del cliente.
Fecha programada para realizar el split (
YYYY-MM-DD HH:mm:ss). Si es null, se ejecuta de inmediato.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
Show Propiedades
Monto mínimo por pago parcial en centavos. Mínimo: 100 (equivale a $1).
Monto máximo por pago parcial en centavos. Si no se envía, el máximo es el saldo restante.
Número máximo de pagos parciales permitidos. Mínimo: 2, Máximo: 10. Por defecto: 3.
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.
Solo uno de los dos (
| 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 |
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
Identificador único del pago
Monto del pago en pesos
Código de moneda ISO
Estado del pago:
pending- Pendienteprocessing- Procesandoapproved- Aprobadodeclined- Rechazadocancelled- Canceladoexpired- Expiradopartially_paid- Parcialmente pagadopartial_expired- Pago parcial expirado
ID del cliente que realizó el pago
Método de pago utilizado
Descripción del pago
Metadatos adicionales del pago
Información de pago parcial. Solo presente cuando
partial_payment_config está configurado.Show Propiedades
Show Propiedades
Total pagado hasta el momento en centavos
Total pagado formateado (ej: “$50.000”)
Saldo restante por pagar en centavos
Saldo restante formateado
Porcentaje de progreso del pago (0 a 100)
Indica si el pago fue completado totalmente
Monto mínimo por pago parcial en centavos
Monto máximo por pago parcial en centavos
Número máximo de pagos parciales permitidos
Horas de expiración configuradas
Fecha de expiración del pago parcial (ISO 8601). Se establece después del primer abono.
Lista de cargos pagados
Show Propiedades del cargo
Show Propiedades del cargo
ID del cargo
Monto del cargo en centavos
Monto formateado
Tipo de método de pago (ej: “card”, “account”, “pse”)
Descripción del método de pago
Fecha de pago (ISO 8601)
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
}
Was this page helpful?
⌘I