Crear una suscripción

Crea una suscripción para empezar a cobrar pagos recurrentes a un pagador.

Endpoint

POST /api/v1/subscriptions

Autenticación

Requiere la autenticación de pagos: token Bearer (JWT) o clave de API (Basic).

Cuerpo de la petición (snake_case)

El cuerpo de la petición usa snake_case:

Parámetro	Tipo	Obligatorio	Descripción
description	string	Sí	Descripción de la suscripción (por ejemplo «Plan Pro mensual»)
amount	string	Sí	Importe por periodo de facturación (por ejemplo "10.00")
currency	string	Sí	Código ISO de moneda de tres letras (por ejemplo usd)
token_id	string	Sí	ID del token que se recibe (por ejemplo USDC)
network_id	string	Sí	ID de la red de recepción
interval	string	Sí	Intervalo de facturación: day, week, month, year
interval_count	number	No	Número de intervalos por periodo (por defecto 1)
collection_method	string	No	send_payment_link (por defecto) o auto_charge
total_cycles	number	No	Total de ciclos de facturación; omítelo o usa null para ilimitados
billing_cycle_anchor	string	No	Marca de tiempo ISO del inicio del primer periodo
cancel_at	string	No	Marca de tiempo ISO en la que cancelar
cancel_at_period_end	boolean	No	Si es true, cancela al final del periodo actual
days_until_due	number	No	Días tras el fin del periodo antes de considerarlo vencido
trial_end	string	No	Marca de tiempo ISO del fin de la prueba (o "now" para omitirla)
trial_period_days	number	No	Número de días de prueba desde la creación
payer_user_id	string	No	ID de usuario del pagador registrado
payer_email	string	No	Email del pagador para notificaciones y enlaces de pago
withdrawal_addresses	object	No	Claves: tipo de cadena (por ejemplo evm), valor: dirección
metadata	object	No	Metadatos clave-valor

Respuesta

Devuelve el objeto de suscripción completo (consulta la visión general) con status, current_period_start, current_period_end y (en send_payment_link) el enlace de pago del primer ciclo cuando aplica.

Ejemplos

cURL

curl -X POST https://api.orcarail.com/api/v1/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly Pro Plan",
    "amount": "10.00",
    "currency": "usd",
    "token_id": "uuid-for-usdc",
    "network_id": "uuid-for-base",
    "interval": "month",
    "interval_count": 1,
    "collection_method": "send_payment_link",
    "total_cycles": 12,
    "payer_email": "[email protected]"
  }'

JavaScript (fetch)

const response = await fetch('https://api.orcarail.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Monthly Pro Plan',
    amount: '10.00',
    currency: 'usd',
    token_id: tokenId,
    network_id: networkId,
    interval: 'month',
    interval_count: 1,
    collection_method: 'send_payment_link',
    total_cycles: 12,
    payer_email: '[email protected]',
    metadata: { plan_id: 'pro_monthly' },
  }),
})

const subscription = await response.json()
console.log('Subscription ID:', subscription.id)
console.log('Current period end:', subscription.current_period_end)

Con periodo de prueba

{
  "description": "Pro Plan with trial",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

Cobro automático

{
  "description": "Yearly Pro (auto-charge)",
  "amount": "100.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "year",
  "collection_method": "auto_charge",
  "total_cycles": 1,
  "payer_email": "[email protected]"
}

Con auto_charge, el pagador debe aprobar después el allowance ERC-20 (consulta Cobro automático).

Próximos pasos

• Gestionar suscripciones: actualiza, cancela, reanuda y lista
• Cobro automático: flujo de aprobación del allowance
• Webhooks de suscripción: reacciona a los eventos de suscripción