# Crear suscripciones con Stripe Billing Con Connect, puedes crear suscripciones para tus clientes o para cuentas conectadas. Para obtener más información sobre *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients), consulta el [resumen](https://docs.stripe.com/connect.md). Basamos las transacciones de *suscripciones* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) en las [tarifas de Stripe Billing](https://stripe.com/billing/pricing). Las empresas de marketplace y Software como Servicio (SaaS) usan Stripe Connect para gestionar los pagos entre ellas, los clientes y las cuentas conectadas. Puedes usar Connect para gestionar pagos o *transferencias* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit), y Stripe Billing para respaldar tu modelo de ingresos recurrentes. ## Casos de uso Puedes crear [suscripciones](https://docs.stripe.com/billing/subscriptions/overview.md) para cuentas conectadas, que admiten varios métodos para cobrar pagos. Puedes crear suscripciones para los clientes de tu cuenta conectada mediante cargos directos o a un destino, para que tus clientes finales realicen transacciones directamente con tu plataforma y cobren a tus cuentas conectadas una tarifa por usar tu plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) Los siguientes casos de uso detallan cómo usar Stripe Billing para crear suscripciones de clientes finales a cuentas conectadas, además de cómo facturar a cada uno. | Caso de uso | Descripción | | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Crea suscripciones desde clientes finales hasta cuentas conectadas](https://docs.stripe.com/connect/subscriptions.md#customer-connected-account) | Crea suscripciones para clientes finales a tus cuentas conectadas, lo que admite varios métodos para cobrar pagos. En este ejemplo, los [Precios](https://docs.stripe.com/api/prices.md) residen en la cuenta conectada. | | [Crear suscripciones para facturar a los clientes finales de una plataforma](https://docs.stripe.com/connect/subscriptions.md#customer-platform) | Marketplaces puede ofrecer directamente suscripciones de membresía sin involucrar tu cuenta conectada. En este ejemplo, los [Precios](https://docs.stripe.com/api/prices.md) residen en la plataforma. | | [Crea suscripciones para facturar a cuentas conectadas](https://docs.stripe.com/connect/subscriptions.md#connected-account-platform) | Las plataformas pueden crear suscripciones para sus cuentas conectadas. En este ejemplo, los [Precios](https://docs.stripe.com/api/prices.md) residen en la plataforma. | ### Restricciones El uso de suscripciones con Connect tiene estas restricciones: - Tu plataforma no puede actualizar ni cancelar una suscripción no creada por ella. - Tu plataforma no puede agregar una `application_fee_amount` a una factura no creada por ella ni tampoco a una factura que contenga ítems de factura no creados por ella. - Solo las cuentas conectadas con acceso al Dashboard completo de Stripe pueden gestionar las suscripciones de sus clientes. Para otras cuentas conectadas, la plataforma debe administrar las suscripciones de sus clientes. - Las suscripciones no se cancelan de forma automática cuando te desconectas de la plataforma; debes hacerlo manualmente. Puedes usar [webhooks para controlar la actividad de las cuentas conectadas](https://docs.stripe.com/connect/webhooks.md). ## Crea suscripciones desde el cliente final a la cuenta conectada Si estás diseñando una plataforma, puedes crear suscripciones para los clientes de tus cuentas conectadas. Tienes la opción de cobrar una comisión por cada pago en tu plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) En este ejemplo, se diseña una plataforma de una editorial en línea que permite que los clientes se suscriban a sus autores favoritos y paguen una cuota mensual para recibir publicaciones de blogs exclusivas de cada autor. ## Before you begin Antes de poder crear suscripciones para tus clientes o cuentas conectadas, debes hacer lo siguiente: 1. Crea una [cuenta conectada](https://docs.stripe.com/connect/accounts.md) para cada persona que reciba dinero en tu plataforma. En nuestro ejemplo de publicación en línea, una cuenta conectada representa a un autor. 1. Crear un modelo de precios. Para este ejemplo, creamos un de tarifa plana [modelo de tarifas](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) para cobrar a los clientes una tarifa de forma recurrente, pero también se admiten tarifas por usuario y por uso. 1. Crea un [cliente con el método de pago previsto](https://docs.stripe.com/billing/customer.md#manage-customers) por cada persona que se suscriba a una cuenta conectada. En nuestro ejemplo de la editorial en línea, puedes crear un cliente por cada lector que se suscriba a un autor. ### Elige entre cargos Direct y cargos a un Destino Para dividir el pago de un cliente entre la cuenta conectada y tu plataforma, puedes usar tanto cargos Direct como cargos a un Destino. Con los cargos directos, los clientes no sabrán de la existencia de tu plataforma porque en la descripción de cargo en el extracto bancario no aparecerá el nombre de tu plataforma, sino el nombre del autor. En nuestro ejemplo de la editorial en línea, los lectores interactúan directamente con los autores. Se recomiendan los cargos directos para las cuentas conectadas con acceso al Dashboard completo de Stripe, que incluye las cuentas Standard. Si quieres que tu plataforma sea la responsable de las comisiones de Stripe, los rembolsos y los contracargos, usa cargos a un Destino. En nuestro ejemplo de la editorial en línea, los clientes se suscriben a tu plataforma de publicación, en lugar de a autores específicos. Se recomiendan los cargos de destino para las cuentas conectadas con acceso al panel de Express o las cuentas conectadas sin acceso al Dashboard alojado en Stripe, que incluye las cuentas Express y Custom. Para obtener más información sobre los diferentes tipos de cargos de Connect, consulta [Tipos de cargos](https://docs.stripe.com/connect/charges.md#types). ### Usa cargos Direct para crear una suscripción Para crear una suscripción con [Cargos](https://docs.stripe.com/api/charges/object.md) asociados a la cuenta conectada, [crea una suscripción](https://docs.stripe.com/api.md#create_subscription) mientras [estás autenticado como la cuenta conectada](https://docs.stripe.com/connect/authentication.md#stripe-account-header). Asegúrate de definir el cliente con un método de pago predeterminado y el [Precio](https://docs.stripe.com/api/prices.md) en la cuenta conectada. Para usar un cliente sin un método de pago predeterminado, establece `payment_behavior: "default_incomplete"`. Más información sobre el [comportamiento de pago](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). Expande `latest_invoice.confirmation_secret` para incluir el Payment Element, que necesitas para confirmar el pago. Obtén más información sobre [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). Para ver un ejemplo de cómo implementar el flujo de creación de la suscripción y de pago, de principio a fin, en tu aplicación, consulta la guía de [integración de suscripciones](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md). ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" ``` ### Usa cargos a un Destino para crear una suscripción Para crear una suscripción con [Cargos](https://docs.stripe.com/api/charges/object.md) asociados a la plataforma y crear automáticamente transferencias a una cuenta conectada, haz una llamada para [crear la suscripción](https://docs.stripe.com/api.md#create_subscription) y especifica el ID de la cuenta conectada como el `transfer_data[destination]` [value](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-transfer_data). Expande `latest_invoice.confirmation_secret` para incluir el Payment Element, que necesitas para confirmar el pago. Obtén más información sobre [Payment Elements](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-page). Tienes la opción de especificar [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). Obtén más información sobre cómo [cobrar comisiones](https://docs.stripe.com/connect/subscriptions.md#collect-fees). ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` ### Pasos adicionales antes de crear una suscripción Para crear un cargo a un destino, define el cliente y el precio en la cuenta de la plataforma. Debes haber creado una cuenta conectada en la plataforma. El cliente debe existir dentro de la cuenta de plataforma. Cuando se utilizan cargos a un destino, la plataforma es el *comerciante registrado* (The legal entity responsible for facilitating the sale of products to a customer that handles any applicable regulations and liabilities, including sales taxes. In a Connect integration, it can be the platform or a connected account). ## Crea suscripciones para cobrar a los clientes finales de una plataforma Puedes usar Stripe Billing para crear suscripciones con el fin de que tus clientes finales realicen transacciones directo con tu plataforma sin tener que involucrar a las cuentas conectadas. (See full diagram at https://docs.stripe.com/connect/subscriptions) En este ejemplo, se diseña un marketplace que permite que los clientes realicen pedidos a restaurantes. El marketplace les ofrece a los clientes una suscripción mensual prémium que no cobra comisiones de envío. Los clientes que se suscriben al plan prémium pagan directo en el marketplace y no se suscriben a ningún servicio de entregas ni restaurante en particular. ## Before you begin Antes de crear suscripciones para tus clientes, debes hacer lo siguiente: 1. Crear un modelo de precios. Para este ejemplo, creamos un de tarifa plana [modelo de tarifas](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) para cobrar a los clientes una tarifa de forma recurrente, pero también se admiten tarifas por usuario y por uso. 1. Crea un registro de [cliente](https://docs.stripe.com/billing/customer.md#manage-customers) para cada cliente que quieras facturar. También puedes crear una [cuenta conectada](https://docs.stripe.com/connect/accounts.md) para cada usuario que reciba dinero de tu plataforma. En nuestro ejemplo de entrega a domicilio por pedido, una cuenta conectada es un restaurante o un servicio de entrega. Sin embargo, este paso no es necesario para que los clientes se suscriban directamente a tu plataforma. ### Crear una suscripción Para crear una suscripción en la que tu plataforma reciba los fondos, sin que el dinero vaya a las cuentas conectadas, sigue la [guía de suscripciones](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) y crea una suscripción con Stripe Billing. ### Crear cargos y envíos de fondos separados Si luego quieres transferir manualmente una parte de los fondos que recibe tu plataforma a tus cuentas conectadas, usa [cargos y envíos de fondos separados](https://docs.stripe.com/connect/separate-charges-and-transfers.md) para transferir fondos a una cuenta conectada (o más). En nuestro ejemplo de entregas de restaurante por pedido, puedes usar cargos y envíos de fondo separados para transferir una comisión de afiliado a un repartidor o a un restaurante que refiere al cliente a suscribirse al servicio de entregas prémium. ## Crea suscripciones para cobrar a las cuentas conectadas Puedes usar Stripe Billing para crear suscripciones con el fin de cobrarles a tus cuentas conectadas una comisión por usar tu plataforma. (See full diagram at https://docs.stripe.com/connect/subscriptions) En este ejemplo, se diseña una plataforma de software de gestión de gimnasios que permite que estos establecimientos paguen una cuota mensual por el uso del programa, que les permite gestionar la programación y asignación de las clases. La cuota de la suscripción la paga la empresa (en este caso, el gimnasio), no los clientes. El software de gestión de gimnasios también facilita los pagos únicos del cliente al gimnasio por cada clase en la que se anota. La suscripción mensual se da entre la cuenta conectada y la plataforma, por lo que el cliente no está involucrado en la transacción. En el diagrama anterior, el gimnasio es la cuenta conectada y la persona que va al gimnasio es el cliente final. ## Before you begin Antes de crear suscripciones para tus cuentas conectadas, debes hacer lo siguiente: 1. Crear un modelo de precios. Para este ejemplo, creamos un de tarifa plana [modelo de tarifas](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) para cobrar a los clientes una tarifa de forma recurrente, pero también se admiten tarifas por usuario y por uso. 1. Crea un cliente en la plataforma con el método de pago previsto para cada cuenta conectada que quieras facturar. En el ejemplo del software de gestión de gimnasios, creas un cliente para cada empresa de gimnasios: ### Crear un objeto Customer que represente la cuenta conectada Para crear una suscripción para que la cuenta conectada pague una comisión recurrente a la plataforma, debes crear un “[Customer](https://docs.stripe.com/api/customers/create.md) Object” para representar a la cuenta conectada. El objeto Account permite que la cuenta conectada cobre pagos de sus clientes, pero la plataforma no puede usarlo para cobrar pagos recurrentes de la cuenta conectada. Crea un solo cliente para representar a la entidad de cada empresa en lugar de crear un cliente para representar a cada titular, gerente u operador de la empresa. ### Crear una suscripción para la cuenta conectada Para crear una suscripción en la que tu plataforma reciba los fondos de tus cuentas conectadas, sigue la [Guía de suscripciones](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md) para crear una suscripción con Stripe Billing. Especifica el “Customer Object” que representa a la cuenta conectada en el parámetro `cliente`. ## Habilita la integración para recibir notificaciones de eventos Stripe crea notificaciones de eventos cuando se producen cambios en tu cuenta, por ejemplo, cuando un pago recurrente se realiza correctamente o cuando falla una transferencia. Para recibir estas notificaciones y usarlas a fin de automatizar tu integración, configura un punto de conexión de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). Por ejemplo, puedes dar acceso a tu servicio cuando recibas el evento `invoice.paid`. ### Notificaciones de eventos para integraciones de Connect y suscripciones Estas son las notificaciones de eventos que suelen usar las integraciones de Connect. | Evento | tipo data.object | Descripción | | ---------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account.application.deauthorized` | `application` | Ocurre cuando una cuenta conectada se desconecta de tu plataforma. Puedes usarlo para activar la limpieza en tu servidor. Disponible para cuentas conectadas con acceso al Dashboard de Stripe, que incluye [cuentas Standard](https://docs.stripe.com/connect/standard-accounts.md). | | `account.external_account.updated` | AUna cuenta externa, como `card` o `bank_account` | Tiene lugar cuando [se actualiza una cuenta bancaria o tarjeta de débito asociada a una cuenta conectada](https://docs.stripe.com/connect/payouts-bank-accounts.md), lo que puede influir en las transferencias a cuentas bancarias. Disponible para las cuentas conectadas que tu plataforma controla, que incluye cuentas Custom y Express, y cuentas Standard con [controles de plataforma](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) habilitados. | | `account.updated` | `account` | Te permite monitorear los cambios en los requisitos de la cuenta conectada y los cambios de estado. Disponible para todas las cuentas conectadas. | | `balance.available` | `balance` | Se produce cuando se actualiza tu saldo de Stripe. Por ejemplo, cuando los [fondos que agregaste desde tu cuenta bancaria](https://docs.stripe.com/connect/top-ups.md) están disponibles para transferir a tu cuenta conectada. | | `payment_intent.succeeded` | `payment_intent` | Tiene lugar cuando un intento de pago se convierte en un cargo efectuado correctamente. Disponible para todos los pagos, incluidos los cargos a un [destino](https://docs.stripe.com/connect/destination-charges.md) y [Direct](https://docs.stripe.com/connect/direct-charges.md). | | `payout.failed` | `payout` | Tiene lugar cuando [falla una transferencia](https://docs.stripe.com/connect/payouts-connected-accounts.md#webhooks). Cuando una transferencia falla, se deshabilita la cuenta externa involucrada y no se pueden procesar transferencias automáticas ni manuales hasta que no se actualiza la cuenta externa. | | `person.updated` | `person` | Ocurre cuando se actualiza una `Person` asociada con `Account`. Si [usas la API Persons para gestionar los requisitos](https://docs.stripe.com/connect/handling-api-verification.md#verification-process), recibe notificaciones de este evento para monitorear los cambios en los requisitos y los cambios de estado para particulares. Disponible para las cuentas conectadas que tu plataforma controla, que incluye cuentas Custom y Express, y cuentas Standard con [controles de plataforma](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) habilitados. | Estas son las notificaciones de eventos que suelen usar las integraciones de suscripciones. > La API Accounts v2 está en GA para los usuarios de Connect y en versión preliminar pública para otros usuarios de Stripe. > > Regardless of whether you use [Accounts v2](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) objects or [Customer](https://docs.stripe.com/api/customers.md) objects to represent your customers, use the `customer.subscription` events to track subscription events. | Evento | Descripción | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `v2.core.account.created` | Se envía cuando se crea correctamente una [Account v2](https://docs.stripe.com/api/v2/core/accounts/object.md). | | `customer.created` | Se envía cuando se crea correctamente un objeto [Customer](https://docs.stripe.com/api/customers/object.md). | | `customer.subscription.created` | Se envía cuando se crea la suscripción. El `status` de la suscripción puede ser `incomplete` si se necesita la autenticación del cliente para completar el pago o si se establece `payment_behavior` en [default_incomplete](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). | | `customer.subscription.deleted` | Se envía cuando se termina la suscripción de un cliente. | | `customer.subscription.paused` | Se envía cuando el `estado` de una suscripción cambia a `pausado`. Por ejemplo, cuando [configuras](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) una suscripción en pausa cuando finaliza una [prueba sin cargo sin un método de pago](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md#create-free-trials-without-payment). La facturación no se producirá hasta que se [reanude la suscripción (/API/suscriptions/resume). No enviamos este evento si [suspendes el cobro de pagos](https://docs.stripe.com/billing/subscriptions/pause-payment.md) porque se siguen creando facturas durante ese período. | | `customer.subscription.resumed` | Se envía cuando reanudas una suscripción en estado `suspendido`. Esto no se aplica cuando [despausas el cobro de pagos](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing). | | `customer.subscription.trial_will_end` | Se envía tres días antes de que [finalice el período de prueba](https://docs.stripe.com/billing/subscriptions/trials.md). Si el periodo de prueba es menor de tres días, este evento se activa. | | `customer.subscription.updated` | Se envía cuando se inicia o [cambia](https://docs.stripe.com/billing/subscriptions/change.md) una suscripción. Por ejemplo, este evento se activa cuando se renueva una suscripción, se agrega un cupón, se aplica un descuento, se agrega una partida de factura o se cambia de plan. | | `entitlements.active_entitlement_summary.updated` | Se envía cuando se actualizan los derechos activos de un cliente. Cuando recibas este evento, puedes proporcionar o anular el acceso a las funciones de tu producto. Lee más sobre [integración con derechos](https://docs.stripe.com/billing/entitlements.md). | | `invoice.created` | Se envía cuando se crea una factura para una suscripción renovada o una nueva. Si Stripe no recibe una respuesta correcta al evento `invoice.created`, la finalización de todas las facturas con [cobro automático](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) se retrasará hasta 72 horas. Obtén más información sobre [cómo finalizar facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Para responder a la notificación, envía una solicitud a la API [Finalize an invoice](https://docs.stripe.com/api/invoices/finalize.md). | | `invoice.finalized` | Se envía cuando una factura se finaliza correctamente y está lista para pagarse. - Puedes enviar la factura al cliente. Consulta la [finalización de la factura](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) para obtener más información. - Según tu configuración, cobramos automáticamente al método de pago predeterminado o intentamos el cobro. Consulta los [correos electrónicos posteriores a la finalización](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails) para obtener más información. | | `invoice.finalization_failed` | No se pudo finalizar la factura. Obtén más información sobre [cómo gestionar los errores en la finalización de facturas](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures) y la [finalización de facturas](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Inspecciona el [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) de la factura para determinar la causa del error. - Si usas Stripe Tax, marca el campo [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) del objeto `Factura`. - Si `automatic_tax[status]=requires_location_inputs`, la factura no puede finalizarse y los pagos no se pueden cobrar. Notifica al cliente y cobra la [ubicación del cliente](https://docs.stripe.com/tax/customer-locations.md) requerida. - Si `automatic_tax[status]=failed`, reintenta la solicitud más tarde. | | `invoice.paid` | Se envía cuando la factura se paga correctamente. Puedes brindar acceso a tu producto cuando recibas este evento y el `status` de la suscripción sea `active`. | | `invoice.payment_action_required` | Se envía cuando la factura requiere la autenticación del cliente. Aprende a gestionar la suscripción cuando la factura [requiere intervención](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action). | | `invoice.payment_failed` | Falló el pago de una factura. El estado del PaymentIntent cambia a `requires_action`, mientras que el de la suscripción sigue siendo `incomplete` *only* en la primera factura de la suscripción. Si falla un pago, puedes tomar varias medidas: - Notifica al cliente. - Realiza la [configuración de la suscripción](https://dashboard.stripe.com/settings/billing/automatic) en el Dashboard para habilitar [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) y otras funcionalidades de recuperación de ingresos. - Si estás usando PaymentIntents, recopila la nueva información de pago y [confirma el PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md). - Actualiza el [método de pago predeterminado](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) en la suscripción. | | `invoice.upcoming` | Se envía unos días antes de la renovación de la suscripción. La cantidad de días se basa en el número establecido en **Próximos eventos de renovación** en el [Dashboard](https://dashboard.stripe.com/settings/billing/automatic). Para las suscripciones existentes, el cambio del número de días entrará en vigencia en el siguiente período de facturación. De ser necesario, aún puedes agregar [más partidas de factura](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items). | | `invoice.updated` | Se envía tanto cuando un pago falla como cuando se efectúa correctamente. Si sucede esto último, el atributo `paid` se establece en `true` y el `status` será `paid`. Si el pago falla, `paid` se establece en `false` y el `status` permanecerá `open`. Los pagos fallidos también activan el evento `invoice.payment_failed`. | | `payment_intent.created` | Se envía cuando se crea una [PaymentIntent](https://docs.stripe.com/api/payment_intents.md). | | `payment_intent.succeeded` | Se envía cuando un PaymentIntent ha completado correctamente un pago. | | `subscription_schedule.aborted` | Se envía cuando se cancela un calendario de suscripciones porque el retraso en el pago canceló la suscripción relacionada. | | `subscription_schedule.canceled` | Se envía cuando se cancela un calendario de suscripciones, lo que también cancela las suscripciones asociadas activas. | | `subscription_schedule.completed` | Se envía cuando se completan todas las [fases](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-phases) de un calendario de suscripciones. | | `subscription_schedule.created` | Se envía cuando se crea un nuevo calendario de suscripciones. | | `subscription_schedule.expiring` | Se envía siete días antes de que expire el calendario de suscripción. | | `subscription_schedule.released` | Se envía cuando se [lanza](https://docs.stripe.com/api/subscription_schedules/release.md) un calendario de suscripción, o cuando se pausa y desvincula dicho calendario de la suscripción. La suscripción permanece. | | `subscription_schedule.updated` | Se envía cuando se actualiza un calendario de suscripciones. | - [Crear un punto de conexión de webhooks](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) - [Escuchar eventos con la CLI de Stripe](https://docs.stripe.com/webhooks.md#local-listener) - [Webhooks de Connect](https://docs.stripe.com/connect/webhooks.md) - [Webhooks de suscripciones](https://docs.stripe.com/billing/subscriptions/webhooks.md) ## Prueba la integración Después de crear tu suscripción, prueba exhaustivamente tu integración antes de exponerla a los clientes o usarla para cualquier actividad en vivo. Obtén más información sobre [cómo probar Stripe Billing](https://docs.stripe.com/billing/testing.md). ## Opciones adicionales Después de crear tu suscripción, puedes especificar un [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent), configurar el *portal de clientes* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details), cobrarle a tu cliente usando el parámetro `on_behalf_of` y monitorear las suscripciones con webhooks, además de otras opciones. ### Cobrar comisiones sobre suscripciones Una vez por período de facturación, Stripe toma este porcentaje del importe final de la factura (que incluye ítems de factura agrupados, descuentos o ajustes de saldo de la cuenta) como comisión para la plataforma. Hacemos esta deducción antes de cobrar cualquier comisión de Stripe. Al crear o actualizar una suscripción, tienes la opción de especificar [application_fee_percent](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-application_fee_percent). Debe ser un número con decimales no negativo entre 0 y 100, con dos decimales como máximo. Este ejemplo muestra `application_fee_percent` para suscripciones que usan cargos Direct en cuentas conectadas: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 ``` Este ejemplo muestra `application_fee_percent` para suscripciones que usan cargos a un Destino: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" ``` ### Cómo calcular el porcentaje de comisión de la aplicación Para ver cómo calculamos `application_fee_percent`, analiza este escenario: - Una suscripción cuesta 30 USD por ciclo de facturación - Hay un ítem de factura por 10 USD en la próxima factura - Se aplica un cupón del 50 % - `application_fee_percent` es 10 En este caso, la comisión total de la aplicación es 2 USD: (30 USD + 10 USD) * 50% * 10%. ### Comisiones porcentuales y comisiones fijas Las comisiones de la aplicación sobre suscripciones normalmente son un porcentaje, porque el importe facturado por suscripciones suele variar. No puedes definir la comisión recurrente de la suscripción como un importe fijo. Sin embargo, puedes cobrar una `application_fee_amount` fija sobre una factura, como se explica en la [siguiente sección](https://docs.stripe.com/connect/subscriptions.md#subscription-invoices). El parámetro `application_fee_percent` no se aplica a las facturas creadas fuera del período de facturación de la suscripción. Por ejemplo, no se aplica a los ítems de facturas de prorrateo que se facturan de inmediato. En estos casos, directamente debes definir un `application_fee_amount` en la factura por el importe que quieres cobrar. ### Trabajar con facturas creadas por suscripciones En cada ciclo, las suscripciones crean facturas y las facturas crean cargos. Para obtener más información sobre los ciclos de suscripción, conoce el [ciclo vital de la suscripción](https://docs.stripe.com/billing/subscriptions/overview.md#subscription-lifecycle). Para cobrar una tarifa fija o dinámica que se pueda calcular automáticamente con `application_fee_percent`, agrega un `application_fee_amount` directamente en cada factura creada por la suscripción. Este ejemplo muestra un `application_fee_amount` para una factura con un cargo Direct en la cuenta conectada: #### curl ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` Este ejemplo muestra un `application_fee_amount` para una factura con un cargo a un Destino: #### curl ```bash curl https://api.stripe.com/v1/invoices/{INVOICE_ID} \ -u <>: \ -d application_fee_amount=100 \ -d "transfer_data[destination]"="{{CONNECTED_STRIPE_ACCOUNT_ID}}" ``` Para cobrar automáticamente un `application_fee_amount`, crea un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) que escuche el evento `invoice.created`. También puedes hacerlo manualmente creando una factura para ítems de factura pendientes y definiendo una comisión de la aplicación en ella. `application_fee_amount` definido directamente en una factura anula cualquier importe de la comisión de la aplicación calculado con `application_fee_percent`, y tiene como límite el importe del cargo final de la factura. ### Usar cupones Después de crear las suscripciones, puedes agregar cupones a las suscripciones. Los [cupones](https://docs.stripe.com/api/coupons.md) son objetos para el comerciante que puedes usar para controlar descuentos sobre [suscripciones](https://docs.stripe.com/billing/subscriptions/overview.md) o [facturas](https://docs.stripe.com/api/invoices.md). Los [códigos de promoción](https://docs.stripe.com/api/promotion_codes.md) son códigos para el cliente que se crean sobre los cupones y que pueden compartirse directamente con los clientes. Aprende a [crear códigos para el cliente](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes). ### Usar períodos de prueba Puedes iniciar la de un cliente [suscripción](https://docs.stripe.com/billing/subscriptions/overview.md) con un período de prueba gratuito especificando un argumento `trial_end` al [crear la suscripción](https://docs.stripe.com/api.md#create_subscription): ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` El parámetro `trial_end` requiere una marca de tiempo que indique el momento exacto en el que termina la prueba. Al crear una suscripción, alternativamente puedes usar el argumento [trial_period_days](https://docs.stripe.com/api.md#create_subscription-trial_period_days), que debe ser un número entero que represente la cantidad de días que dura la prueba a partir de ese momento. Al crear una suscripción con un período de prueba, no exigimos que el cliente especifique un método de pago. Aun así creamos una [factura](https://docs.stripe.com/api/invoices.md) inmediata, pero por 0 USD. Tres días antes de que termine el período de prueba, se envía el evento `customer.subscription.trial_will_end` a tu [punto de conexión de webhooks](https://docs.stripe.com/billing/subscriptions/webhooks.md). Después de ver la notificación, toma cualquier medida necesaria, como informarle al cliente que se le empezará a facturar en breve. Cuando finaliza la prueba, comienza un nuevo ciclo de facturación para el cliente. Una vez terminada la prueba, Stripe genera una factura y envía una notificación del evento `invoice.created`. Aproximadamente una hora después, Stripe intentará cobrar esa factura. Para finalizar una prueba antes de tiempo, haz una llamada API para [actualizar la update subscription](https://docs.stripe.com/api.md#update_subscription) estableciendo el valor `trial_end` en una nueva marca de tiempo o **ahora** para que finalice de inmediato: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -d trial_end=now ``` Aprende a [retrasar pagos en suscripciones activas con períodos de prueba](https://docs.stripe.com/billing/subscriptions/trials.md). ### Configurar el portal de clientes El portal del cliente permite que tus clientes administren [suscripciones](https://docs.stripe.com/billing/subscriptions/overview.md) y [facturas](https://docs.stripe.com/api/invoices.md). Si eres un usuario de Billing, el portal permite que tus clientes administren sus suscripciones (actualizarlas, cancelarlas, pausarlas, etc.). Los usuarios que solo utilizan la facturación pueden usar el portal para pagar una factura, agregar un método de pago y mucho más. Obtén más información sobre cómo [integrar el portal del cliente](https://docs.stripe.com/customer-management.md). ### Controlar las suscripciones con webhooks Enviamos notificaciones a tu aplicación usando [webhooks](https://docs.stripe.com/webhooks.md). Los webhooks son especialmente importantes para las [suscripciones](https://docs.stripe.com/billing/subscriptions/overview.md), donde la mayor parte de la actividad se produce de forma asincrónica. Para usar webhooks con tus suscripciones: 1. Crear un punto de conexión de webhooks en tu aplicación. 1. Agrega lógica para gestionar eventos de Stripe. En el caso de las suscripciones, esto incluye los pagos fallidos y los cambios en los estados de las suscripciones (como pasar del período de prueba al estado activo). 1. Prueba tu punto de conexión de webhooks para confirmar que funciona como debería. Aprende a usar webhooks para [recibir notificaciones de la actividad de las suscripciones](https://docs.stripe.com/billing/subscriptions/webhooks.md). ### Determinar que la cuenta conectada sea el comerciante a cargo del cobro con on_behalf_of Puedes crear o actualizar una suscripción con el parámetro `on_behalf_of` para los siguientes propósitos: - Determinar que la cuenta conectada sea el comerciante a cargo del cobro. - Usar la imagen de marca de una cuenta conectada en recursos alojados (recibos por correo electrónico, facturas y el porta de clientes). Lee la siguiente documentación a fin de conocer los requisitos para usar `on_behalf_of` y obtén más información sobre cómo afecta los pagos de las suscripciones: - Para saber sobre envíos de fondos automáticos a la cuenta conectada, consulta la información relacionada con el parámetro `on_behalf_of` en [Cobrar en nombre de una cuenta conectada](https://docs.stripe.com/connect/charges.md#on_behalf_of). - Para saber cómo transferir pagos manualmente, consulta la sección sobre Disponibilidad de transferencias en [Cómo crear cargos y transferencias separados](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant). - Para obtener una lista de las funcionalidades de cuenta necesarias para procesar métodos de pago, consulta [Funcionalidades para métodos de pago](https://docs.stripe.com/connect/account-capabilities.md#payment-methods). - Para obtener una lista de opciones de marca que se deben habilitar en la cuenta conectada, consulta los detalles `settings.branding` en los [documentos de referencia de la API](https://docs.stripe.com/api/accounts/object.md#account_object-settings-branding) En este ejemplo se muestra `on_behalf_of` para una suscripción nueva que usa cargos y envíos de fondos separados: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` En este ejemplo se muestra cómo usar `on_behalf_of` con un cargo a un Destino y una comisión de la aplicación: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "on_behalf_of={{CONNECTEDACCOUNT_ID}}" \ -d application_fee_percent=10 \ -d "transfer_data[destination]={{CONNECTEDACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" ``` ### Conoce el comportamiento de desconexión Cuando una cuenta conectada se desconecta de una plataforma, las suscripciones no se cancelan automáticamente. Sin embargo, algunos aspectos del cobro de pagos pueden seguir activos o no, en función del tipo de cargo usado. ### Cargos Direct Después de la desconexión, las suscripciones continúan ejecutándose en la cuenta conectada. Si la suscripción se creó con un `application_fee_percent`, la plataforma sigue cobrando la comisión de la aplicación después de la desconexión. Elimina el `application_fee_percent` de la suscripción antes de que una cuenta conectada se desconecte de tu plataforma. Después de la desconexión, una cuenta conectada puede borrar el parámetro `application_fee_percent` de las suscripciones existentes a través de la API. ### Cargos a un Destino o cargos y envíos de fondos separados Después de la desconexión, las suscripciones existentes creadas como cargos a un Destino o cargos y envíos de fondos separados continúan generando facturas, pero no pueden transferir fondos a una cuenta conectada. Antes de desconectarte, debes ayudar a las cuentas conectadas con las migraciones de las suscripciones o cancelar las suscripciones asociadas. ### Cargos a un destino con on_behalf_of Cuando una cuenta conectada se desconecta de una plataforma, las suscripciones `on_behalf_of` no le cobrarán al cliente las facturas definidas como `charge_automatically`. Stripe seguirá generando facturas de suscripciones en cada ciclo, pero quedarán en borrador con `auto_advance` establecido en `false`. Para seguir cobrando los pagos, debes reconectarte con la cuenta desconectada o quitar expresamente estos campos de la factura y reintentar el pago de esas facturas. ### Integra el cálculo y cobro de impuestos Primero debes determinar qué entidad está obligada a pagar impuestos. La entidad responsable de los impuestos puede ser tu cuenta conectada o la plataforma, en función de tu modelo de negocio. Para obtener más información, consulta [Stripe Tax con Connect](https://docs.stripe.com/tax/connect.md). ## See also - [Cómo crear facturas](https://docs.stripe.com/invoicing/connect.md) - [Cómo crear cargos](https://docs.stripe.com/connect/charges.md) - [Comparte clientes entre cuentas](https://docs.stripe.com/connect/cloning-customers-across-accounts.md) - [Varias monedas](https://docs.stripe.com/connect/currencies.md)