curl https://api.onepay.la/v1/subscriptions \
-X POST \
-H "Authorization: Bearer sk_test_xxx" \
-H "Content-Type: application/json" \
-H "x-idempotency: subscription-001" \
-d '{
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": null,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": true,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": true,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}'
const response = await fetch('https://api.onepay.la/v1/subscriptions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_test_xxx',
'Content-Type': 'application/json',
'x-idempotency': 'subscription-001'
},
body: JSON.stringify({
customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
name: 'Plan Premium Mensual',
description: '<p>Acceso completo a todas las funcionalidades</p>',
currency: 'COP',
amount_in_cents: 44900000,
reference_price_in_cents: '44900000',
cicle_frequency: 'monthly',
cicles: null,
start_date: '2025-03-01T00:00:00Z',
payment_mode: 'request',
suggest_auto_debit: true,
remember_to_pay_before: 3,
cancel_after_no_payment_before: 2,
trial: {
has_trial: true,
trial_days: 14,
start_trial_date: '2025-02-15T00:00:00Z'
},
metadata: {
salesforce_id: 'OP-554',
plan_type: 'premium'
}
})
});
const subscription = await response.json();
console.log(subscription.id);
import requests
from datetime import datetime
url = "https://api.onepay.la/v1/subscriptions"
headers = {
"Authorization": "Bearer sk_test_xxx",
"Content-Type": "application/json",
"x-idempotency": "subscription-001"
}
data = {
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": None,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": True,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": True,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}
response = requests.post(url, headers=headers, json=data)
subscription = response.json()
print(subscription["id"])
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.onepay.la/v1/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_xxx",
"Content-Type: application/json",
"x-idempotency: subscription-001"
],
CURLOPT_POSTFIELDS => json_encode([
"customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name" => "Plan Premium Mensual",
"description" => "<p>Acceso completo a todas las funcionalidades</p>",
"currency" => "COP",
"amount_in_cents" => 44900000,
"reference_price_in_cents" => "44900000",
"cicle_frequency" => "monthly",
"cicles" => null,
"start_date" => "2025-03-01T00:00:00Z",
"payment_mode" => "request",
"suggest_auto_debit" => true,
"remember_to_pay_before" => 3,
"cancel_after_no_payment_before" => 2,
"trial" => [
"has_trial" => true,
"trial_days" => 14,
"start_trial_date" => "2025-02-15T00:00:00Z"
],
"metadata" => [
"salesforce_id" => "OP-554",
"plan_type" => "premium"
]
])
]);
$response = curl_exec($ch);
$subscription = json_decode($response, true);
echo $subscription["id"];
curl_close($ch);
?>
{
"id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
"name": "OnePay Pro",
"status": "created",
"description": "<p>Plan mensual con onboarding asistido</p>",
"internal_id": "SaaSSpectre",
"plan_id": null,
"coupon_id": null,
"reference_price_in_cents": "44900000",
"currency": "COP",
"amount_in_cents": 44900000,
"cicle_frequency": "monthly",
"cicles": null,
"current_cicle": 0,
"allows": {
"cards": true,
"accounts": true,
"card_extra": false,
"realtime": false,
"pse": true,
"transfiya": true
},
"suggest_auto_debit": true,
"start_date": "2025-01-05T00:00:00.000000Z",
"end_date": null,
"payment_mode": "request",
"trial": {
"has_trial": false,
"start_trial_date": null,
"trial_days": 0
},
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"complex_payments": [],
"features": [],
"metadata": {
"salesforce_id": "OP-554"
},
"created_at": "2025-01-02T19:24:48.000000Z",
"updated_at": "2025-01-02T19:24:48.000000Z",
"customer": {
"id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"first_name": "Empresa",
"last_name": "SAS",
"email": "empresa@empresa.com",
"phone": "+573221234567",
"document": "1234567890",
"document_type": "RUT"
}
}
{
"message": "Hay errores de validación. (y 2 errores más)",
"code": 10001,
"code_name": "validation_error",
"errors": {
"customer_id": [
"El campo customer id es obligatorio."
],
"amount_in_cents": [
"El campo amount in cents es obligatorio."
],
"cicle_frequency": [
"Debes especificar una frecuencia válida."
]
}
}
{
"message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
"code": 10003,
"code_name": "idempotency_error"
}
Crear suscripción
Crea una suscripción recurrente asociada a un cliente.
POST
/
subscriptions
curl https://api.onepay.la/v1/subscriptions \
-X POST \
-H "Authorization: Bearer sk_test_xxx" \
-H "Content-Type: application/json" \
-H "x-idempotency: subscription-001" \
-d '{
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": null,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": true,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": true,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}'
const response = await fetch('https://api.onepay.la/v1/subscriptions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_test_xxx',
'Content-Type': 'application/json',
'x-idempotency': 'subscription-001'
},
body: JSON.stringify({
customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
name: 'Plan Premium Mensual',
description: '<p>Acceso completo a todas las funcionalidades</p>',
currency: 'COP',
amount_in_cents: 44900000,
reference_price_in_cents: '44900000',
cicle_frequency: 'monthly',
cicles: null,
start_date: '2025-03-01T00:00:00Z',
payment_mode: 'request',
suggest_auto_debit: true,
remember_to_pay_before: 3,
cancel_after_no_payment_before: 2,
trial: {
has_trial: true,
trial_days: 14,
start_trial_date: '2025-02-15T00:00:00Z'
},
metadata: {
salesforce_id: 'OP-554',
plan_type: 'premium'
}
})
});
const subscription = await response.json();
console.log(subscription.id);
import requests
from datetime import datetime
url = "https://api.onepay.la/v1/subscriptions"
headers = {
"Authorization": "Bearer sk_test_xxx",
"Content-Type": "application/json",
"x-idempotency": "subscription-001"
}
data = {
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": None,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": True,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": True,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}
response = requests.post(url, headers=headers, json=data)
subscription = response.json()
print(subscription["id"])
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.onepay.la/v1/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_xxx",
"Content-Type: application/json",
"x-idempotency: subscription-001"
],
CURLOPT_POSTFIELDS => json_encode([
"customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name" => "Plan Premium Mensual",
"description" => "<p>Acceso completo a todas las funcionalidades</p>",
"currency" => "COP",
"amount_in_cents" => 44900000,
"reference_price_in_cents" => "44900000",
"cicle_frequency" => "monthly",
"cicles" => null,
"start_date" => "2025-03-01T00:00:00Z",
"payment_mode" => "request",
"suggest_auto_debit" => true,
"remember_to_pay_before" => 3,
"cancel_after_no_payment_before" => 2,
"trial" => [
"has_trial" => true,
"trial_days" => 14,
"start_trial_date" => "2025-02-15T00:00:00Z"
],
"metadata" => [
"salesforce_id" => "OP-554",
"plan_type" => "premium"
]
])
]);
$response = curl_exec($ch);
$subscription = json_decode($response, true);
echo $subscription["id"];
curl_close($ch);
?>
{
"id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
"name": "OnePay Pro",
"status": "created",
"description": "<p>Plan mensual con onboarding asistido</p>",
"internal_id": "SaaSSpectre",
"plan_id": null,
"coupon_id": null,
"reference_price_in_cents": "44900000",
"currency": "COP",
"amount_in_cents": 44900000,
"cicle_frequency": "monthly",
"cicles": null,
"current_cicle": 0,
"allows": {
"cards": true,
"accounts": true,
"card_extra": false,
"realtime": false,
"pse": true,
"transfiya": true
},
"suggest_auto_debit": true,
"start_date": "2025-01-05T00:00:00.000000Z",
"end_date": null,
"payment_mode": "request",
"trial": {
"has_trial": false,
"start_trial_date": null,
"trial_days": 0
},
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"complex_payments": [],
"features": [],
"metadata": {
"salesforce_id": "OP-554"
},
"created_at": "2025-01-02T19:24:48.000000Z",
"updated_at": "2025-01-02T19:24:48.000000Z",
"customer": {
"id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"first_name": "Empresa",
"last_name": "SAS",
"email": "empresa@empresa.com",
"phone": "+573221234567",
"document": "1234567890",
"document_type": "RUT"
}
}
{
"message": "Hay errores de validación. (y 2 errores más)",
"code": 10001,
"code_name": "validation_error",
"errors": {
"customer_id": [
"El campo customer id es obligatorio."
],
"amount_in_cents": [
"El campo amount in cents es obligatorio."
],
"cicle_frequency": [
"Debes especificar una frecuencia válida."
]
}
}
{
"message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
"code": 10003,
"code_name": "idempotency_error"
}
Headers
string
required
Token único para garantizar la idempotencia de la petición
Body
Esta página describe un cuerpo que el endpoint ya no acepta. Hoy
POST /subscriptions crea la
suscripción a partir de un plan existente y exige plan_id (o price_id), customer_id,
payment_method_type y payment_method_id. Los campos de importe y periodicidad —
amount_in_cents, reference_price_in_cents, cicle_frequency, cicles, currency, name —
se definen ahora al crear el plan, no aquí; enviarlos a este endpoint
devuelve un 422 pidiendo plan_id.Estamos reescribiendo esta página. Mientras tanto, toma como referencia
crear planes y confirma el cuerpo con soporte antes de integrar.string
required
ID del cliente que asumirá los cobros. Crea primero el cliente.
string
required
Nombre público de la suscripción.
string
Descripción rica que se mostrará en correos y facturas.
string
default:"COP"
required
Moneda en formato ISO-4217. Actualmente soportamos
COP.number
required
Valor a cobrar en cada ciclo expresado en centavos.
string
Precio de referencia que se mostrará en UI. Puede diferir del
amount_in_cents cuando usas pagos complejos.string
required
Frecuencia:
daily, weekly, monthly, annual.number
Número máximo de ciclos. Usa
null para renovaciones indefinidas.date
Fecha en la que deseas iniciar los cobros. Si se omite se usa la fecha actual.
string
Identificador que usas en tus sistemas.
string
ID del plan preconfigurado que deseas usar. Ver cómo crear planes.
string
default:"request"
Define si se cobrará automáticamente (
auto_debit) o vía solicitudes (request).boolean
default:false
Si es
true, el checkout sugerirá activar débito automático.number
Días de anticipación para recordatorios de pago.
number
Número de ciclos consecutivos fallidos antes de cancelar la suscripción.
object
Pares clave/valor para enriquecer la suscripción.
object
array
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.curl https://api.onepay.la/v1/subscriptions \
-X POST \
-H "Authorization: Bearer sk_test_xxx" \
-H "Content-Type: application/json" \
-H "x-idempotency: subscription-001" \
-d '{
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": null,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": true,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": true,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}'
const response = await fetch('https://api.onepay.la/v1/subscriptions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_test_xxx',
'Content-Type': 'application/json',
'x-idempotency': 'subscription-001'
},
body: JSON.stringify({
customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
name: 'Plan Premium Mensual',
description: '<p>Acceso completo a todas las funcionalidades</p>',
currency: 'COP',
amount_in_cents: 44900000,
reference_price_in_cents: '44900000',
cicle_frequency: 'monthly',
cicles: null,
start_date: '2025-03-01T00:00:00Z',
payment_mode: 'request',
suggest_auto_debit: true,
remember_to_pay_before: 3,
cancel_after_no_payment_before: 2,
trial: {
has_trial: true,
trial_days: 14,
start_trial_date: '2025-02-15T00:00:00Z'
},
metadata: {
salesforce_id: 'OP-554',
plan_type: 'premium'
}
})
});
const subscription = await response.json();
console.log(subscription.id);
import requests
from datetime import datetime
url = "https://api.onepay.la/v1/subscriptions"
headers = {
"Authorization": "Bearer sk_test_xxx",
"Content-Type": "application/json",
"x-idempotency": "subscription-001"
}
data = {
"customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name": "Plan Premium Mensual",
"description": "<p>Acceso completo a todas las funcionalidades</p>",
"currency": "COP",
"amount_in_cents": 44900000,
"reference_price_in_cents": "44900000",
"cicle_frequency": "monthly",
"cicles": None,
"start_date": "2025-03-01T00:00:00Z",
"payment_mode": "request",
"suggest_auto_debit": True,
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"trial": {
"has_trial": True,
"trial_days": 14,
"start_trial_date": "2025-02-15T00:00:00Z"
},
"metadata": {
"salesforce_id": "OP-554",
"plan_type": "premium"
}
}
response = requests.post(url, headers=headers, json=data)
subscription = response.json()
print(subscription["id"])
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://api.onepay.la/v1/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_test_xxx",
"Content-Type: application/json",
"x-idempotency: subscription-001"
],
CURLOPT_POSTFIELDS => json_encode([
"customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"name" => "Plan Premium Mensual",
"description" => "<p>Acceso completo a todas las funcionalidades</p>",
"currency" => "COP",
"amount_in_cents" => 44900000,
"reference_price_in_cents" => "44900000",
"cicle_frequency" => "monthly",
"cicles" => null,
"start_date" => "2025-03-01T00:00:00Z",
"payment_mode" => "request",
"suggest_auto_debit" => true,
"remember_to_pay_before" => 3,
"cancel_after_no_payment_before" => 2,
"trial" => [
"has_trial" => true,
"trial_days" => 14,
"start_trial_date" => "2025-02-15T00:00:00Z"
],
"metadata" => [
"salesforce_id" => "OP-554",
"plan_type" => "premium"
]
])
]);
$response = curl_exec($ch);
$subscription = json_decode($response, true);
echo $subscription["id"];
curl_close($ch);
?>
Response
string
Identificador único de la suscripción (UUID).
string
Nombre comercial de la suscripción.
string
Estado actual (
active, unpaid, pass_due, canceled, finished, frozen).string
Descripción enriquecida (puede contener HTML).
string
Identificador interno que usas en tu sistema.
string
ID del plan asociado, si aplica.
string
ID del cupón aplicado.
string
Precio de referencia en centavos como string.
string
Moneda en formato ISO-4217 (ej.
COP).number
Valor base cobrado en cada ciclo.
string
Frecuencia de cobro:
weekly, monthly, annual, etc.number
Cantidad máxima de ciclos;
null para indefinido.number
Ciclo actual procesado.
object
Configuración de métodos de pago permitidos para la suscripción.
boolean
Indica si se sugiere activar débito automático durante el onboarding del cliente.
date
Fecha programada de inicio.
date
Fecha de finalización si aplica.
object
Información de periodo de prueba (
has_trial, trial_days, start_trial_date).string
Modo de cobro (
request, auto_debit, etc.).number
Días de anticipación para recordatorios de pago.
number
Número de ciclos fallidos antes de cancelar automáticamente.
array
Pagos con valores diferenciados por ciclo.
object
Atributos personalizados que acompañan la suscripción.
object
Resumen del cliente asociado.
object
Información del plan enlazado, cuando existe.
date
Fecha de creación de la suscripción.
date
Fecha de última actualización.
{
"id": "9f01f541-7d9c-4f62-88c1-0b0f2c2d4c31",
"name": "OnePay Pro",
"status": "created",
"description": "<p>Plan mensual con onboarding asistido</p>",
"internal_id": "SaaSSpectre",
"plan_id": null,
"coupon_id": null,
"reference_price_in_cents": "44900000",
"currency": "COP",
"amount_in_cents": 44900000,
"cicle_frequency": "monthly",
"cicles": null,
"current_cicle": 0,
"allows": {
"cards": true,
"accounts": true,
"card_extra": false,
"realtime": false,
"pse": true,
"transfiya": true
},
"suggest_auto_debit": true,
"start_date": "2025-01-05T00:00:00.000000Z",
"end_date": null,
"payment_mode": "request",
"trial": {
"has_trial": false,
"start_trial_date": null,
"trial_days": 0
},
"remember_to_pay_before": 3,
"cancel_after_no_payment_before": 2,
"complex_payments": [],
"features": [],
"metadata": {
"salesforce_id": "OP-554"
},
"created_at": "2025-01-02T19:24:48.000000Z",
"updated_at": "2025-01-02T19:24:48.000000Z",
"customer": {
"id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
"first_name": "Empresa",
"last_name": "SAS",
"email": "empresa@empresa.com",
"phone": "+573221234567",
"document": "1234567890",
"document_type": "RUT"
}
}
{
"message": "Hay errores de validación. (y 2 errores más)",
"code": 10001,
"code_name": "validation_error",
"errors": {
"customer_id": [
"El campo customer id es obligatorio."
],
"amount_in_cents": [
"El campo amount in cents es obligatorio."
],
"cicle_frequency": [
"Debes especificar una frecuencia válida."
]
}
}
{
"message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
"code": 10003,
"code_name": "idempotency_error"
}
Was this page helpful?
⌘I