Saltar al contenido principal

Visión general de suscripciones

Las suscripciones de OrcaRail te permiten cobrar pagos cripto recurrentes a los pagadores. La API REST usa un recurso de suscripción convencional con campos en snake_case. OrcaRail añade auto_charge, en el que la hot wallet de OrcaRail cobra cada periodo de la wallet del pagador en EVM (allowance ERC-20 y transferFrom) o en Solana (delegación de token SPL). El cobro automático no funciona en Bitcoin.

¿Qué son las suscripciones?​

Una suscripción representa un acuerdo de pago recurrente entre tú (el comercio) y un pagador. En cada ciclo de facturación, puedes:

  • Enviar un enlace de pago: OrcaRail crea un PaymentLink para el periodo y (opcionalmente) se lo envía por email al pagador.
  • Cobro automático: el pagador aprueba una sola vez (allowance en EVM o delegación en Solana); OrcaRail cobra el importe del periodo en cada ciclo.

Las suscripciones admiten intervalos fijos (día, semana, mes, año), periodos de prueba opcionales y un ciclo de vida de estados conocido.

Campos habituales​

ConceptoOrcaRail
Cliente / pagadorpayer (ID de usuario o email)
Concepto / precioamount + currency + token_id + network_id (un solo concepto, nativo cripto)
Cobro automáticocollection_method: auto_charge (cobro mediante allowance en EVM o delegación en Solana)
Factura / pago por enlace en cada ciclocollection_method: send_payment_link (PaymentLink por ciclo, email opcional)
Último elemento pagablelatest_payment_link
Ciclo de vida de estadostrialing, active, past_due, canceled, paused, completed (adaptado a cripto)
Programación y metadatoscancel_at_period_end, trial_end, billing_cycle_anchor, metadata

Métodos de cobro​

En cada ciclo de facturación, OrcaRail crea un PaymentLink por el importe de la suscripción. Puedes enviárselo por email al pagador (por ejemplo, 1 día antes del vencimiento). El pagador abre el enlace y paga con su wallet como en cualquier pago único. Sin allowance ni cobro automático.

  • Úsalo cuando: quieras que el pagador apruebe explícitamente cada pago, o no necesites cobro automático.
  • Flujo: el cron de facturación crea el PaymentLink → email opcional → el pagador paga en la app de pago alojada.

auto_charge​

El pagador aprueba una vez para la red elegida: en EVM, un allowance ERC-20 por un total o por periodo; en Solana, una delegación SPL al camino de cobro de OrcaRail. En cada ciclo, el trabajo de facturación usa la hot wallet para cobrar el importe del periodo (transferFrom en EVM o transferencia en lote en Solana).

  • Úsalo cuando: quieras cobros recurrentes de verdad sin que el pagador tenga que abrir un enlace en cada periodo.
  • Flujo: el pagador aprueba en el primer ciclo o en la página de suscripción (consulta approval_spender_address en auto_charge) → en cada ciclo el trabajo de facturación cobra al pagador → si sale bien, el ciclo se marca como pagado; si falla, la suscripción puede pasar a past_due y se avisa al pagador.

Consulta Cobro automático para ver el flujo de aprobación, los pasos del pagador para aprobar o revocar y los detalles de la API.

Objeto de suscripción (forma de la respuesta)​

Las respuestas usan snake_case y siguen esta forma de suscripción:

{
  "id": "sub_550e8400e29b41d4a716446655440000",
  "object": "subscription",
  "status": "active",
  "collection_method": "send_payment_link",
  "amount": "10.00",
  "currency": "usd",
  "description": "Monthly Pro Plan",
  "token": { "id": "...", "symbol": "USDC", "name": "USD Coin" },
  "network": { "id": "...", "name": "Base", "chain_id": 8453 },
  "interval": "month",
  "interval_count": 1,
  "total_cycles": 12,
  "completed_cycles": 3,
  "billing_cycle_anchor": 1679609767,
  "current_period_start": "2025-03-01T00:00:00Z",
  "current_period_end": "2025-04-01T00:00:00Z",
  "start_date": "2025-01-01T00:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "trial_start": null,
  "trial_end": null,
  "auto_charge": null,
  "payer": { "id": "...", "email": "[email protected]" },
  "latest_payment_link": {
    "id": "...",
    "unique_slug": "...",
    "link": "...",
    "status": "completed"
  },
  "withdrawal_addresses": { "evm": "0x742d..." },
  "metadata": {},
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-03-15T00:00:00Z"
}

Cuando collection_method es auto_charge, el objeto auto_charge incluye la wallet del pagador y los ID de token y red, allowance_tx_hash opcional, approved_amount, approved_iterations, approval_spender_address (el spender o delegado que el pagador debe aprobar on-chain) y status. Consulta Cobro automático para los endpoints de aprobar, revocar y definir el método de cobro.

Ejemplo de forma una vez aprobado:

"auto_charge": {
  "payer_wallet_address": "0x...",
  "payer_network_id": "...",
  "payer_token_id": "...",
  "allowance_tx_hash": "0x...",
  "approved_amount": "120.00",
  "approved_iterations": 12,
  "approval_spender_address": "0x...",
  "status": "approved"
}

Ciclo de vida de estados​

EstadoDescripción
trialingEn periodo de prueba; no hace falta pagar hasta que termine
activeAl día; se crean enlaces de pago en cada ciclo o se ejecuta el cobro automático
past_dueEl pago de un ciclo falló o está vencido
canceledLa suscripción terminó (de inmediato o al final del periodo)
pausedEn pausa (por ejemplo, tras la prueba sin método de pago)
completedTodos los ciclos terminaron (se alcanzó total_cycles)

Flujo del ciclo de facturación​

Próximos pasos​