Suscripciones en OrcaRail: cobro automático y multichain

25 de marzo de 2026: OrcaRail admite suscripciones recurrentes con el mismo modelo centrado en la API que los pagos únicos: creas una suscripción, nosotros seguimos los periodos de facturación y los pagadores completan cada ciclo, ya sea abriendo un enlace de pago o mediante cobro automático, en el que nos autorizan a cobrar stablecoins en cada periodo tras una única aprobación on-chain.

Por qué suscripciones en OrcaRail

Las suscripciones sirven para SaaS, membresías, igualas y cualquier producto que se facture en un intervalo fijo (día, semana, mes, año), con periodos de prueba, límites de ciclos y reglas de cancelación opcionales. Usas la misma autenticación de pagos que el resto de la plataforma y puedes reaccionar a los eventos del ciclo de vida con los webhooks de suscripción.

Dos formas de cobrar: enlaces de pago o cobro automático

• send_payment_link (por defecto): en cada ciclo de facturación, el pagador recibe un enlace de pago (por email y/o flujo alojado). Paga cuando abre el enlace: es lo habitual en un checkout cripto y se combina fácilmente con las rutas de Relay y la elección de wallet.
• auto_charge: el pagador preautoriza a la hot wallet de OrcaRail para cobrar el importe del periodo en cada renovación. Tras la configuración, las renovaciones no requieren que el pagador abra un enlace nuevo cada vez, siempre que el saldo y la autorización sigan siendo válidos.

Crea y configura el cobro con POST /api/v1/subscriptions; lista, actualiza, pausa y cancela con gestionar suscripciones. Los campos completos de la petición y los ejemplos están en esas guías.

Cobro automático: cómo lo gestionamos

1. El comercio crea una suscripción con collection_method: "auto_charge" y los campos habituales amount, interval, token_id, network_id y los datos de contacto del pagador.
2. El pagador abre la suscripción o la experiencia de pago del primer ciclo. Ve el alcance total de la aprobación (por ejemplo, la suma de los próximos cargos que le pides cubrir) y firma una autorización on-chain:
   • En cadenas EVM, es un approve(spender, amount) estándar de ERC-20 con nuestra hot wallet como spender.
   • En Solana, el paso equivalente es una delegación de token SPL de al menos el importe de un periodo a nuestra hot wallet de Solana.
3. El pagador llama al endpoint público POST /api/v1/subscriptions/:id/approve-auto-charge con el hash de la transacción del allowance (o de la delegación), payer_wallet_address, payer_network_id y payer_token_id. No hace falta la clave de API del comercio: el pagador demuestra su intención al haber firmado la transacción en la cadena.
4. OrcaRail verifica on-chain que el allowance o la delegación cubre al menos un ciclo de facturación para la hot wallet esperada antes de marcar el cobro automático como aprobado. Antes de cada cobro podemos volver a comprobar la autorización, para no confundir problemas transitorios de RPC con un allowance revocado.
5. En cada ciclo de facturación, el proceso de facturación intenta el cobro (en EVM, un flujo de tipo transferFrom del pagador a la liquidación; en Solana se usa el saldo delegado). Si sale bien, el periodo avanza; si falla repetidamente (por ejemplo, saldo insuficiente o aprobación revocada), la suscripción puede pasar a past_due y se avisa al pagador. Puedes escuchar webhooks como subscription.payment_link.payment_failed o subscription.past_due, como se describe en Cobro automático y webhooks.

Revocación y alternativa: si el pagador revoca on-chain, los cobros posteriores fallan. También puede completar POST .../revoke-auto-charge después de revocar para que registremos el estado y podamos cambiar el cobro a send_payment_link, con instrucciones por email para gestionar la suscripción y volver a pagar mediante enlaces. Los detalles están en Cobro automático y Gestionar suscripciones.

Seguridad y claridad: solo se usa para los cobros la wallet que completó la aprobación; mostramos totales y número de ciclos claros para que los pagadores sepan qué han autorizado. En planes muy largos o sin fin, considera limitar los importes aprobados y renovar la aprobación periódicamente, o quedarte con los enlaces de pago. Consulta Cobro automático.

Multichain: cómo encaja con las suscripciones

• Ancla del comercio: cada suscripción se crea con un network_id y un token_id que definen cómo se fija el precio y se liquida en términos de API: la red y el activo «base» de ese plan.
• Contexto del pagador en el cobro automático: el cobro automático guarda payer_network_id y payer_token_id, la red y el token donde el pagador realmente definió el allowance o la delegación. Pueden diferir de los campos principales de la suscripción cuando el pagador paga desde otra cadena o activo compatible, de forma coherente con cómo las cotizaciones y el checkout resuelven las rutas del lado del pagador.
• Cobertura alineada con Relay: las redes y monedas compatibles se mantienen alineadas con Relay; cuando Relay amplía cadenas y tokens, nuestro inventario le sigue. Resumimos ese modelo en Redes y monedas compatibles: con la tecnología de Relay.
• Adónde llegan los fondos: los comercios siguen configurando direcciones de retiro por tipo de cadena (y pueden anularlas por pago cuando se admite). Para la imagen completa de los retiros multichain y las varias direcciones por cadena, consulta OrcaRail es multichain: retiros y alineación con Relay.

Resumen

Tema	Comportamiento de OrcaRail
Cobro	send_payment_link en cada ciclo, o auto_charge con aprobación on-chain
Cobro automático	Approve ERC-20 en EVM o delegación SPL en Solana → API pública de aprobación → verificación on-chain → cobro por ciclo, con past_due y webhooks si falla
Revocación	Revocación on-chain + revoke-auto-charge opcional; puede volver a los enlaces de pago
Multichain	network_id / token_id de la suscripción; la aprobación del pagador guarda payer_network_id / payer_token_id; redes alineadas con Relay; retiros por tipo de cadena

Las suscripciones en OrcaRail combinan recursos REST de suscripción con autorización no custodial del pagador para el cobro automático y pagos multichain, sin renunciar a la experiencia de pago alojada ni a las APIs que ya usas para los pagos únicos.

---

App de OrcaRail · Documentación · Relay