Saltar al contenido principal
Los pagos recurrentes usan transacciones iniciadas por el cliente (CIT) y transacciones iniciadas por el comercio (MIT). El flujo general es:
  1. Crea una sesión de checkout con el objeto recurring_payment.
  2. Realiza una CIT para autorizar y guardar en el vault el método de pago del cliente.
  3. Luego usa el vaulted_token devuelto para los cobros MIT posteriores.

Crear la sesión de checkout para pagos recurrentes

Antes de crear la transacción, debes crear la sesión de checkout con el objeto recurring_payment completo en tu solicitud de sesión de checkout: Prueba gratuita: cuando ofrezcas un período de prueba gratuito, define el amount.value raíz como 0 e incluye el objeto trial_billing como se muestra en el ejemplo siguiente. El cobro recurrente real se define en regular_billing, que informa al cliente del monto que se le facturará cuando termine la prueba.

Transacción iniciada por el cliente (CIT)

La CIT es la transacción inicial en la que el cliente autoriza los pagos recurrentes, por ejemplo, cuando se suscribe a un servicio mensual. Esta transacción requiere la interacción del cliente y genera un token para las futuras transacciones MIT. El siguiente ejemplo muestra una solicitud CIT completa:
Los parámetros clave de una CIT son:
  • vault_on_success: true: este parámetro indica que se trata de la configuración de un pago recurrente y genera el token para las futuras transacciones MIT
  • customer_payer.id: obligatorio junto con vault_on_success. Debe hacer referencia a un cliente existente (créalo primero con Create Customer). Sin él, el pago igualmente es exitoso, pero no se guarda nada en el vault: la respuesta trae un vaulted_token vacío y ningún error
  • detail.wallet.stored_credentials.usage: "FIRST": indica que esta es la transacción inicial de una serie recurrente
  • verify: cuando es true, habilita un flujo de verificación de tarjeta a través de la wallet (por ejemplo, una autorización de cero dólares) en lugar de un cobro de pago regular.
Define verify: true en los flujos de prueba gratuita donde amount es 0. Omite el campo en las CIT pagas estándar.
No coloques stored_credentials bajo detail.card en la CIT. No se valida en un pago con wallet, y el flujo de Apple Pay de dos pasos no lo traslada al método de pago guardado, lo que deja el registro sin indicadores de credenciales almacenadas y sin network_transaction_id.
El vaulted_token solo se devuelve en la respuesta del pago de la CIT. Los instrumentos de wallet guardados en el vault se excluyen intencionalmente de Retrieve Enrolled Payment Methods, así que no dependas de la lista de métodos de pago del cliente para volver a encontrar el token: guárdalo (junto con los metadatos de visualización que necesites) cuando la CIT sea exitosa. Un token almacenado aún puede resolverse individualmente con Retrieve Enrolled Payment Method by ID. Consulta Stored Credentials.

Transacción iniciada por el comercio (MIT)

Las transacciones MIT se procesan automáticamente en los ciclos de facturación posteriores usando el token generado durante la CIT. El siguiente ejemplo muestra una solicitud MIT completa:
Los parámetros clave de una MIT son:
  • vaulted_token: el token devuelto en la respuesta de la CIT; se usa para cobrar al cliente en los ciclos de facturación posteriores sin requerir una nueva autorización
  • type: "CARD": el instrumento guardado en el vault es un registro de tarjeta. También se acepta "APPLE_PAY" junto con un vaulted_token
  • detail.card.stored_credentials.usage: "USED": indica que esta es una transacción posterior de una serie recurrente
  • workflow: "DIRECT": un cobro de servidor a servidor; no se necesitan sesión de checkout ni payment_token
Monitorea el estado del pago mediante webhooks para gestionar casos límite y enviar notificaciones al cliente.

URL de gestión de suscripciones

Para los pagos recurrentes con el SDK, debes proporcionar una URL de gestión de suscripciones donde los clientes puedan administrar y cancelar su suscripción. Inclúyela en tus comunicaciones con el cliente.