Saltar al contenido principal

Cobro automático

El cobro automático es el modelo de cobro recurrente de OrcaRail: el pagador concede a la hot wallet permiso para cobrar tokens en cada ciclo de facturación. Las redes compatibles con el cobro automático son EVM y Solana (Bitcoin no admite cobros de suscripción). En EVM, el pagador define un allowance ERC-20 y OrcaRail usa transferFrom en cada periodo. En Solana, el pagador delega la autoridad del token SPL; OrcaRail cobra mediante la hot wallet usando esa delegación.

:::note Suscripciones no custodiales

OrcaRail está pasando el cobro automático a un modelo totalmente no custodial: el spender del approve pasa de una hot wallet propiedad de OrcaRail a un contrato público SubscriptionHub (EVM) o a un programa Anchor subscription (Solana). El flujo del pagador de esta página (aprobar una vez y revocar cuando quiera) no cambia; solo cambia la dirección del spender. Consulta la visión general no custodial y Fase 2: suscripciones por allowance.

:::

Para pagadores: cómo aprobar y cómo revocar​

Esta sección es para las personas que pagan una suscripción (los clientes), no para los desarrolladores que integran la API.

Qué estás aceptando​

Con el cobro automático firmas una vez en tu wallet para que OrcaRail cobre el importe de la suscripción en cada periodo de facturación (por ejemplo, cada mes), hasta el límite que aprobaste. No tienes que abrir un enlace de pago cada vez, siempre que el allowance o la delegación sigan siendo válidos y tengas suficiente token en tu wallet.

Cómo aprobar el cobro automático​

  1. Abre el enlace que te envió el negocio (por email, en la web o en la app). Debería llevarte a la experiencia de pago o de suscripción alojada de OrcaRail.
  2. Conecta tu wallet en la red correcta y elige el token indicado (por ejemplo USDC).
  3. Lee el resumen: precio por periodo, cada cuánto se te cobra y el total o número de ciclos que cubre la aprobación.
  4. Al activar el cobro automático, tu wallet te pide que apruebes el permiso sobre el token. Confírmalo solo si estás de acuerdo con los importes y con el negocio.
  5. Cuando la transacción se confirme on-chain, verás un mensaje de éxito. OrcaRail registra entonces la aprobación; los periodos siguientes se cobran automáticamente hasta que la aprobación se agote, falle (por ejemplo, por saldo bajo) o la revoques.

Si algo falla, comprueba que estás en la red y el token correctos y vuelve a intentarlo, o paga ese periodo con un enlace de pago si el comercio lo ofrece.

Cómo revocar el cobro automático (detener los cobros)​

  1. Revoca on-chain para que el spender ya no pueda cobrar tus tokens:
    • EVM: envía una transacción que elimine el allowance, normalmente approve(spender, 0) en el contrato del token para la dirección spender de OrcaRail (las herramientas de «aprobaciones de tokens» o de revocación de tu wallet pueden ofrecerlo).
    • Solana: revoca la delegación de token SPL que concediste para esa suscripción.
  2. Completa el flujo del comercio si lo ofrece (por ejemplo «Gestionar suscripción» → desactivar el cobro automático). Así OrcaRail te pasa a enlaces de pago en cada periodo en lugar de cobros, y puede que recibas un email con los siguientes pasos.
  3. Si solo revocas on-chain y nunca avisas a OrcaRail, el siguiente cobro automático puede fallar y la suscripción puede quedar vencida hasta que pagues un enlace o corrijas la aprobación.

Los comercios y las apps personalizadas usan la revocación del cobro automático (API) después de la revocación on-chain.

Cómo funciona​

  1. El comercio crea una suscripción con collection_method: "auto_charge".
  2. El pagador abre el enlace de la suscripción o el enlace de pago del primer ciclo (o elige el cobro automático mediante definir el método de cobro cuando aplica).
  3. El pagador completa la aprobación on-chain: approve(spender, amount) en EVM a la dirección spender de OrcaRail, o la delegación SPL equivalente en Solana. Usa approval_spender_address del objeto auto_charge de la suscripción (cuando exista) como el spender/delegado que debe aprobar la wallet.
  4. El pagador envía la aprobación a OrcaRail: POST /api/v1/subscriptions/:id/approve-auto-charge con allowance_tx_hash, payer_wallet_address, payer_network_id, payer_token_id y, opcionalmente, approved_amount / approved_iterations.
  5. OrcaRail registra el allowance y marca auto_charge como aprobado. En cada ciclo de facturación, el trabajo de facturación usa la hot wallet para cobrar el importe del periodo. Si sale bien, el ciclo se marca como pagado y el periodo avanza; si falla, la suscripción puede pasar a past_due y se avisa al pagador.

Aprobar el cobro automático (pagador)​

POST /api/v1/subscriptions/:id/approve-auto-charge

Este endpoint es público (de cara al pagador). Sin clave de API del comercio; el pagador demuestra su intención al haber firmado la transacción de aprobación on-chain.

Cuerpo de la petición​

ParámetroTipoObligatorioDescripción
payer_wallet_addressstringSíDirección de la wallet del pagador (EVM o Solana, según la red)
payer_network_idstring (UUID)SíID de la red en la que se definió el allowance o la delegación
payer_token_idstring (UUID)SíID del token (por ejemplo USDC)
allowance_tx_hashstringSíHash de la transacción de aprobación (approve en EVM o configuración SPL en Solana, según corresponda)
approved_amountstringNoImporte total aprobado (por ejemplo "120.00" para doce cobros mensuales)
approved_iterationsintegerNoNúmero de ciclos de facturación que cubre ese total (por ejemplo 12). Si se definen approved_amount y approved_iterations, OrcaRail puede deducir el importe de cobro por periodo.

Flujo en la app de pago​

  1. Muestra el resumen de la suscripción: descripción, importe por periodo, intervalo, total de ciclos e importe total que se aprueba.
  2. Lee approval_spender_address del auto_charge de la suscripción (o del payload de la suscripción) para que la wallet apruebe al spender/delegado correcto.
  3. «Aprobar» hace que la wallet firme la aprobación propia de la cadena (por ejemplo, wagmi/viem en EVM).
  4. Al confirmarse, llama a POST .../approve-auto-charge con el hash de la transacción y los datos de pagador, red y token (y, opcionalmente, approved_amount / approved_iterations).
  5. Si sale bien, muestra: «Cobro automático aprobado. Se te cobrará [importe] [intervalo] automáticamente».

Revocar el cobro automático (pagador)​

Tras revocar on-chain (EVM: approve(spender, 0); Solana: revocar la delegación SPL), el pagador puede confirmarlo a OrcaRail:

POST /api/v1/subscriptions/:id/revoke-auto-charge

Este endpoint es público (de cara al pagador), igual que el de aprobar.

Cuerpo de la petición​

ParámetroTipoObligatorioDescripción
payer_wallet_addressstringSíWallet que tenía el allowance o la delegación
revocation_tx_hashstringSíHash de la transacción de revocación on-chain

Si sale bien, OrcaRail cambia la suscripción a send_payment_link y envía al pagador un email con enlaces para gestionar las suscripciones y abrir la última página de pago.

Definir el método de cobro (pagador)​

Los pagadores pueden elegir cómo pagan (enlace de pago en cada ciclo o cobro automático) desde el flujo alojado:

POST /api/v1/subscriptions/:id/set-collection-method

Público (de cara al pagador). Sin clave de API del comercio.

Cuerpo de la petición​

ParámetroTipoObligatorioDescripción
collection_methodstringSísend_payment_link o auto_charge
payer_wallet_idstring (UUID)Con auto_chargeID de la wallet verificada del pagador que se usa para los cobros
payer_network_idstring (UUID)NoRed elegida por el pagador para el cobro automático; si se omite, se usa la red de la suscripción
payer_token_idstring (UUID)NoToken elegido por el pagador para el cobro automático; si se omite, se usa el token de la suscripción

Devuelve el objeto de suscripción completo (la misma forma que al obtenerla).

Objeto auto_charge de la suscripción​

Cuando collection_method es auto_charge, la respuesta de la suscripción incluye:

{
  "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"
  }
}
  • approval_spender_address: dirección (EVM) o identificador equivalente que el pagador debe aprobar como spender/delegado para los cobros en esa red.
  • approved_iterations: si se define junto con approved_amount, indica cuántos ciclos cubre esa aprobación global.

status puede ser: pending, approved, revoked, failed. Si el pagador revoca on-chain, puedes ver revoked; si un cobro falla repetidamente, failed o la suscripción en past_due.

Gestión de fallos​

  • El cobro falla (por ejemplo, saldo insuficiente o allowance/delegación revocados): la suscripción puede pasar a past_due y el pagador recibe un email (por ejemplo, la notificación de fallo del cobro automático). Puedes escuchar los webhooks subscription.payment_link.payment_failed o subscription.past_due.
  • El pagador revoca on-chain sin llamar a la API: los cobros siguientes fallarán; la suscripción puede pasar a past_due hasta que pidas al pagador que vuelva a aprobar o cambie el método de cobro.
  • El pagador confirma la revocación mediante la API (Revocar el cobro automático): OrcaRail cambia la suscripción a send_payment_link y envía un email al pagador.

Seguridad y experiencia de usuario​

  • Solo se puede cobrar a la wallet que completó la aprobación; el backend verifica el allowance o la delegación on-chain.
  • Muestra con claridad el importe total aprobado y el número de cobros para que el pagador sepa qué está aprobando.
  • En suscripciones muy largas o ilimitadas, considera limitar el importe aprobado (por ejemplo, 12 meses) y pedir una nueva aprobación más adelante, o usa send_payment_link en su lugar.

Próximos pasos​