# Configurar una suscripción con PayPal Obtén información sobre cómo crear y cobrar una suscripción con PayPal. # Página alojada en Stripe > This is a Página alojada en Stripe for when payments-ui-type is stripe-hosted. View the full page at https://docs.stripe.com/billing/subscriptions/paypal?payments-ui-type=stripe-hosted. Echa un vistazo al [ejemplo en GitHub](https://github.com/stripe-samples/checkout-single-subscription) o explora la [demostración](https://checkout.stripe.dev/checkout). Usa esta guía para configurar una *suscripción* (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) mediante [PayPal](https://docs.stripe.com/payments/paypal.md) y *Checkout* (A low-code payment integration that creates a customizable form for collecting payments. You can embed Checkout directly in your website, redirect customers to a Stripe-hosted payment page, or create a customized checkout page with Stripe Elements). Una [sesión de Checkout](https://docs.stripe.com/api/checkout/sessions.md) representa los datos de la intención de compra de un cliente. Crea una sesión de Checkout cuando un cliente quiera iniciar una suscripción. Después de redirigir a un cliente a una sesión de Checkout, Stripe le presentará un formulario de pago en el que podrá completar su compra. Una vez completada, Stripe lo redirigirá a tu sitio. > #### Cómo habilitar pagos recurrentes de PayPal > > Stripe habilita automáticamente pagos recurrentes para la mayoría de los usuarios cuando [activan los pagos de PayPal](https://docs.stripe.com/payments/paypal/activate.md) en el Dashboard de Stripe. Sin embargo, debido a las políticas y restricciones regionales de PayPal, es posible que tengas que [habilitar](https://docs.stripe.com/payments/paypal/set-up-future-payments.md#enable-recurring-payments) manualmente los pagos recurrentes en el Dashboard. ## Configura Stripe [Lado del servidor] Primero, necesitas una cuenta de Stripe. [Inscríbete ahora](https://dashboard.stripe.com/register). Usa nuestras bibliotecas oficiales para acceder a la API de Stripe desde tu aplicación: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## Crear productos y precios recurrentes > La API Prices unifica el modo en que se modelan las compras únicas y las suscripciones en Stripe. Se siguen [admitiendo](https://support.stripe.com/questions/prices-api-and-existing-checkout-integrations) las integraciones existentes que no usan la API Prices. Sin embargo, algunas funcionalidades de Checkout solo admiten Prices. Consulta la [guía de migración](https://docs.stripe.com/payments/checkout/migrating-prices.md) para actualizar a la API Prices. Para usar Checkout, primero debes crear un *producto* (Products represent what your business sells—whether that's a good or a service) y un *precio* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions). Los diferentes bienes físicos o niveles de servicio deben representarse mediante productos. El valor de cada producto está representado por uno o varios precios. Puedes crear, por ejemplo, un *producto* que tenga cuatro *precios*: USD 10/mes, USD 100/año, EUR 9/mes y EUR 90/año. Esto te permite cambiar y agregar precios sin necesidad de cambiar los detalles del producto subyacente. Puedes crear un producto y precio [con la API](https://docs.stripe.com/api/prices.md) o a través del [Dashboard de Stripe](https://dashboard.stripe.com/products). Si tu precio se determina en el momento de la compra (por ejemplo, el cliente establece un importe de donación), o si prefieres no crear precios de manera anticipada, puedes crear [precios alineados](https://docs.stripe.com/billing/subscriptions/paypal.md#creating-prices-inline) al momento de crear la sesión de Checkout. #### Dashboard Antes de empezar a configurar productos, asegúrate de que estás en un entorno de prueba. Luego, define los bienes y servicios que planeas vender. Para crear un nuevo producto y precio: - Vaya a la sección [Productos](https://dashboard.stripe.com/products) en el Dashboard - Haz click en **Agregar producto** - Selecciona “Recurrente” al establecer el precio - Configura el plan de precios Puedes definir múltiples planes de precios con diferentes parámetros para cada producto recurrente. Cada precio tiene un ID generado que puedes usar como referencia durante el proceso de finalización de compra. > Los productos creados en un entorno de prueba pueden copiarse al modo activo para que no tengas que volver a crearlos. En la vista detallada de Productos del Dashboard, haz clic en **Copiar a modo activo** en la esquina superior derecha. Solo puedes hacerlo una vez por cada producto creado en un entorno de prueba. Las siguientes actualizaciones del producto de prueba no se reflejan en el producto real. #### API Para crear un [producto](https://docs.stripe.com/api/products.md) básico a través de la API, solo se requiere el campo `name`. Los atributos `name`, `description` e `images` que indiques aparecerán ante el cliente en Checkout. ```curl curl https://api.stripe.com/v1/products \ -u "<>:" \ -d "name=Blue banana" ``` A continuación, crea un [Precio](https://docs.stripe.com/api/prices.md) para definir cuánto cobrar por tu producto y con qué frecuencia. Esto incluye cuánto cuesta el producto, qué moneda usar y su intervalo de facturación. #### curl ```bash curl https://api.stripe.com/v1/prices \ -u <>: \ -d "product"="{{ PRODUCT_ID }}" \ -d "unit_amount"=1000 \ -d "currency"="eur" \ -d "recurring[interval]=month" ``` El ID del precio es la forma en que te refieres al producto cuando comienzas el proceso de pago con Checkout. ## Crea una sesión de Checkout [Lado del cliente] [Lado del servidor] Agrega un botón de pago en tu sitio web que llame a un punto de conexión del lado del servidor para crear una sesión de Checkout. ```html Checkout
``` ### Parámetros de la sesión de Checkout Consulta [sesión de Checkout](https://docs.stripe.com/api/checkout/sessions/create.md) para obtener una lista completa de los parámetros que puedes usar. Crea una sesión de Checkout con la ID de un [precio](https://docs.stripe.com/api/prices.md) existente. Asegúrate de que el modo esté configurado en `subscription` y de especificar al menos un precio recurrente. Puedes agregar precios únicos además de los precios recurrentes. Después de crear la sesión de Checkout, redirige a tu cliente a la [URL](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-url) devuelta en la respuesta. #### cURL ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` Cuando el cliente completa correctamente su pago, se lo redirige a `success_url`, una página de tu sitio web que le informa que su pago se realizó correctamente. Haz que el ID de sesión esté disponible en la página de éxito incluyendo la variable de la plantilla `{CHECKOUT_SESSION_ID}` en el `success_url` como en el ejemplo anterior. Las Checkout Sessions vencen 24 horas después de su creación de forma predeterminada. > No te bases solo en el redireccionamiento a la `success_url` para detectar el inicio del pago, por la siguiente razón: > > - Algunos usuarios maliciosos podrían acceder directamente a la `success_url` y tener acceso a los bienes o servicios sin pagar. - Después de que un pago se efectúe correctamente, los clientes pueden cerrar la pestaña de su navegador antes de ser redirigidos a la `success_url`. ## Confirmar que el pago se efectuó correctamente > Cuando un comprador confirma correctamente una suscripción en Stripe usando PayPal, se le envía un recibo de parte de Stripe y PayPal. Cuando tu cliente completa correctamente el pago, se lo redirige a la URL que especificaste como `success_url`. Por lo general, esta es una página de tu sitio web que le informa al cliente que su pago se efectuó correctamente. Usa el Dashboard, un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) personalizado o un plugin de un tercero para administrar los eventos posteriores al pago, como enviar un correo electrónico para confirmar el pedido al cliente, registrar la venta en una base de datos o iniciar el flujo de envío. #### Dashboard Los pagos efectuados correctamente aparecen en la [lista de pagos](https://dashboard.stripe.com/payments) del Dashboard. Al hacer clic en un pago, se te dirigirá a la página de información del pago. La sección **Resumen de la compra** contiene información de facturación y la lista de artículos comprados, que puedes usar para completar el pedido manualmente. ![Resumen de Checkout](https://b.stripecdn.com/docs-statics-srv/assets/source.16d3029596357c80a8efdbbfe106108a.png) > Stripe puede ayudar a que te mantengas actualizado respecto de los pagos entrantes mediante notificaciones por correo electrónico cada vez que un cliente efectúa un pago correctamente. Usa el Dashboard para [configurar notificaciones de correo electrónico](https://dashboard.stripe.com/settings/user). #### Webhooks [Configurar webhooks](https://docs.stripe.com/webhooks.md) para gestionar mediante programación los eventos posteriores al pago. La forma más rápida de desarrollar y probar webhooks a nivel local es con la [CLI de Stripe](https://docs.stripe.com/stripe-cli.md). Una vez que la tengas instalada, puedes reenviar eventos a tu servidor: ```bash stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) ``` Con un punto de conexión de webhook, se redirigirá a tu cliente a la `success_url` cuando [hayas confirmado que recibiste el evento](https://docs.stripe.com/webhooks.md#acknowledge-events-immediately). En escenarios donde tu punto de conexión está fuera de servicio o el evento no es reconocido correctamente, se redirigirá a tu cliente a la `success_url` 10 segundos después de un pago realizado correctamente. El siguiente ejemplo de punto de conexión muestra cómo confirmar y gestionar eventos. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. Stripe.api_key = '<>' # You can find your endpoint's secret in your webhook settings endpoint_secret = 'whsec_...' # Using Sinatra post '/webhook' do payload = request.body.read event = nil # Verify webhook signature and extract the event # See https://stripe.com/docs/webhooks#verify-events for more information. sig_header = request.env['HTTP_STRIPE_SIGNATURE'] begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature status 400 return end # Handle the checkout.session.completed event if event['type'] == 'checkout.session.completed' session = event['data']['object'] # Fulfill the purchase... handle_checkout_session(session) end status 200 end ``` Puedes usar plugins como [Zapier](https://stripe.com/works-with/zapier) para automatizar la actualización de tus sistemas de cumplimiento de pedidos con información de los pagos de Stripe. Veamos algunos ejemplos de automatización que se basan en plugins: - Cómo actualizar planillas utilizadas para el seguimiento de pedidos en respuesta a los pagos efectuados correctamente - Cómo actualizar los sistemas de gestión de inventario en respuesta a los pagos efectuados correctamente - Cómo activar las notificaciones a los equipos internos de servicio al cliente que usen correo electrónico o aplicaciones de chat ## Prueba la integración Prueba tu integración con PayPal con tus [claves de API de prueba](https://docs.stripe.com/keys.md#test-live-modes) al visualizar la página de redireccionamiento. Puedes probar el caso de pago exitoso al autenticar el pago en la página de redireccionamiento. El PaymentIntent pasará de `requires_action` a `succeeded`. Para probar el caso en el que falla la autenticación del usuario, usa tus claves de API de prueba y visualiza la página de redireccionamiento. En la página de redireccionamiento, haz click en **Error en el pago de prueba**. El Paymentintent hará la transición de `requires_action` a `requires_payment_method`. ## Optional: Cómo agregar un costo de instalación único [Lado del servidor] Además de especificar los precios recurrentes, puedes agregar precios únicos en modo `subscription`. Estos solo se incluyen en la *factura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) inicial creada por la suscripción. Esta función resulta útil para agregar costos de instalación u otros costos únicos asociados a una suscripción. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[0][price]"="{{RECURRING_PRICE_ID}}" \ -d "line_items[0][quantity]"=1 \ -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \ -d "line_items[1][quantity]"=1 \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" ``` ## Optional: Crear precios y productos alineados [Lado del servidor] Además de especificar los ID de los precios existentes, también puedes definir tus partidas al crear la sesión de Checkout. Primero, define un [producto](https://docs.stripe.com/api/products.md). Luego, crea una sesión de Checkout usando el ID del producto especificándolo como [price_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data) con los datos `unit_amount`, `currency` y `recurring`: #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \-d line_items[0][price_data][unit_amount]=5000 \ -d line_items[0][price_data][currency]=eur\ -d line_items[0][price_data][product]="{{PRODUCT_ID}}" \ -d line_items[0][price_data][recurring][interval]=month \ -d line_items[0][quantity]=1 \ -d mode=subscription \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` Si también tienes que crear productos alineados, puedes hacerlo con [product_data](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-price_data-product_data): #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \-d "line_items[][price_data][currency]"=eur\ -d "line_items[][price_data][product_data][name]"=T-shirt \ -d "line_items[][price_data][unit_amount]"=2000 \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` ## Optional: Clientes existentes [Lado del servidor] Si has creado antes un objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) para representar a un cliente, usa el argumento [cliente](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer) para especificar el ID de cliente al crear una sesión de confirmación de compra. Esto garantiza que todos los objetos creados durante la sesión estén asociados con el objeto Customer correcto. Cuando especificas un ID de cliente, Stripe también toma el correo electrónico almacenado en el objeto Customer para rellenar automáticamente el campo de correo electrónico en la página de Checkout. Si el cliente cambia el correo electrónico en la página de Checkout, se actualizará en el objeto Customer después de la efectivización de un pago. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" ``` ## Optional: Rellenar automáticamente los datos de los clientes [Lado del servidor] Si ya tienes el correo electrónico del cliente y quieres completarlo automáticamente en la sesión de Checkout, especifica [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) cuando crees una sesión de Checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \-d customer_email="customer@example.com" \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` ## Optional: Cómo gestionar los períodos de prueba [Lado del servidor] Puedes usar [trial_end](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-trial_end) o [trial_period_days](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-trial_period_days) en la sesión de Checkout para especificar la duración del período de prueba. En este ejemplo, usamos `trial_period_days` para crear una sesión de Checkout para una suscripción con una prueba de 30 días. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "subscription_data[trial_period_days]"=30 \ -d mode=subscription \ -d success_url="https://example.com/success?session_id={CHECKOUT_SESSION_ID}" \ ``` Checkout muestra la siguiente información de forma automática para las suscripciones con períodos de prueba: - Período de prueba - Frecuencia e importe de los cargos después de vencida la prueba Para obtener más información sobre los requisitos de cumplimiento de la normativa, consulta los [Requisitos de gestión del cumplimiento](https://docs.stripe.com/billing/subscriptions/trials/manage-trial-compliance.md) o las guías de [soporte](https://support.stripe.com/questions/2020-visa-trial-subscription-requirement-changes-guide). ## Optional: Tasas de impuestos [Lado del servidor] Puedes especificar [tasas impositivas](https://docs.stripe.com/billing/taxes/tax-rates.md) (impuesto sobre las ventas, IVA, GST, etc.) en las sesiones de Checkout para aplicar impuestos a las *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). - Usa tasas impositivas fijas si conoces la tasa impositiva exacta que debes cobrar al cliente antes de que inicie al proceso de finalización de compra (por ejemplo, si solo vendes a clientes del Reino Unido y siempre cobras un 20 % de IVA). - Con la API *Prices* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions), puedes usar tasas impositivas dinámicas si necesitas más información del cliente (por ejemplo, su dirección de envío o de facturación) antes de determinar qué tasa cobrar. Si usas tasas impositivas dinámicas, creas tasas por región (por ejemplo, un 20 % de IVA para clientes en el Reino Unido un impuesto del 7.25 % sobre las ventas para clientes de California, en Estados Unidos) y Stripe intentará asignar una de esas tasas según la ubicación del cliente. #### Tasas impositivas fijas Configura [subscription_data.default_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-default_tax_rates) para aplicar una tasa impositiva predeterminada a una suscripción creada con Checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "subscription_data[default_tax_rates][]"="{{TAX_RATE_ID}}" \ -d mode=subscription \ -d success_url="https://example.com/success" \ ``` También puedes especificar [line_items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-tax_rates) o [subscription_data.items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-items-tax_rates) para aplicar tasas impositivas a planes o partidas de factura específicos. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "line_items[][tax_rates][0]"="{{TAX_RATE_ID}}" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` #### Tasas impositivas dinámicas Especifica una matriz de [tasas impositivas](https://docs.stripe.com/api/tax_rates/object.md) en [line_items.dynamic_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates). Cada tasa impositiva debe incluir un `country` [admitido](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates) y, en el caso de EE. UU., un `state`. Esta lista asocia las tasas impositivas con la [dirección de envío](https://docs.stripe.com/payments/collect-addresses.md), la dirección de facturación o el país del cliente. La dirección de envío tiene prioridad sobre la dirección de facturación para determinar la tasa impositiva que se debe cobrar. Si no recopilas la dirección de envío o de facturación, se utiliza el país del cliente (y el código postal, cuando corresponda) para determinar la tasa impositiva. Si no has definido una tasa impositiva que coincida con el país o con la dirección de envío o de facturación del cliente, no se aplica ninguna tasa. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "line_items[][dynamic_tax_rates][]"="{{FIRST_TAX_RATE_ID}}" \ -d "line_items[][dynamic_tax_rates][]"="{{SECOND_TAX_RATE_ID}}" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` > [subscription_data.default_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-subscription_data-default_tax_rates) y [line_items.tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-tax_rates) no pueden combinarse con [line_items.dynamic_tax_rates](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-line_items-dynamic_tax_rates). Puedes utilizar las exportaciones de datos de Stripe para completar los informes periódicos necesarios para la remesa de impuestos. Para obtener más información, visita [Declaración y remesa de impuestos](https://docs.stripe.com/billing/taxes/tax-rates.md#remittance). ## Optional: Cómo agregar cupones [Lado del servidor] Puedes aplicar [cupones](https://docs.stripe.com/billing/subscriptions/coupons.md) a las suscripciones en una sesión de Checkout estableciendo [descuentos](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-discounts). Este cupón anula otros cupones del cliente. Si estás creando una suscripción para un [cliente existente](https://docs.stripe.com/billing/subscriptions/paypal.md#handling-existing-customers), los cupones asociados con el cliente se aplican a las *facturas* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) de la suscripción. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"=paypal \ -d "line_items[][price]"="{{PRICE_ID}}" \ -d "line_items[][quantity]"=1 \-d "discounts[][coupon]"="{{COUPON_ID}}" \ -d "mode"="subscription" \ -d success_url="https://example.com/success" \ ``` ### Cómo agregar códigos de promoción que ve el cliente También puedes habilitar [códigos de promoción](https://docs.stripe.com/billing/subscriptions/coupons.md#promotion-codes) que el cliente puede canjear usando el parámetro [allow_promotion_codes](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-allow_promotion_codes) en las sesiones de Checkout. Cuando se habilita `allow_promotion_codes` en una sesión, Checkout incluye una casilla de canje de códigos de promoción para que tus clientes los utilicen. Crea tus [cupones](https://docs.stripe.com/billing/subscriptions/coupons.md) y códigos de promoción a través del Dashboard o la API para que tus clientes los canjeen en Checkout. #### curl ```bash curl https://api.stripe.com/v1/checkout/sessions \ -u <>: \ -d "payment_method_types[]"="paypal" \ -d "line_items[0][price_data][unit_amount]"=2000 \ -d "line_items[0][price_data][currency]"="eur" \ -d "line_items[0][price_data][product]={{PRODUCT_ID}}" \ -d "line_items[0][price_data][recurring][interval]=month" \ -d "line_items[0][quantity]"=1 \-d "allow_promotion_codes"="true" \ -d "mode"="subscription" \ -d "success_url"="https://example.com/success" \ ``` ## See also - [Personaliza tu integración](https://docs.stripe.com/payments/checkout/customization.md) - [Administrar suscripciones con el portal de clientes](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md?payment-ui=checkout&ui=stripe-hosted) # API Direct > This is a API Direct for when payments-ui-type is direct-api. View the full page at https://docs.stripe.com/billing/subscriptions/paypal?payments-ui-type=direct-api. Usa esta guía para configurar una *suscripción* (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) con [PayPal](https://docs.stripe.com/payments/paypal.md) como método de pago. ## Before you begin - Para aceptar suscripciones de PayPal en Stripe, debes [habilitar pagos recurrentes de PayPal en el Dashboard](https://docs.stripe.com/payments/paypal/set-up-future-payments.md?platform=web#enable-recurring-payments). - Esta funcionalidad solo está disponible para ubicaciones específicas de empresas. [Revisa las empresas para confirmar si cumplen los requisitos](https://docs.stripe.com/payments/paypal.md). ## Crear un producto y un precio [Dashboard] Los [Productos](https://docs.stripe.com/api/products.md) representan el artículo o servicio que vendes. Los [Precios](https://docs.stripe.com/api/prices.md) definen cuánto cobras un producto y con qué frecuencia. Esto incluye el costo del producto, la moneda aceptada y si se trata de un cargo único o recurrente. Si tienes pocos productos y precios, puedes crearlos y gestionarlos en el Dashboard. La guía toma como ejemplo una foto de archivo de un servicio por el que se cobra a los clientes una suscripción mensual de 15 EUR. Para modelar la suscripción: 1. Ve a la página de [Productos](https://dashboard.stripe.com/products?active=true) y haz clic en **Crear producto**. 1. Ingresa el **Nombre** del producto. De forma opcional, puedes agregar una **Descripción** y subir una imagen del producto. 1. Selecciona un **Código de impuesto del producto**. Obtén más información sobre [códigos de impuestos de productos](https://docs.stripe.com/tax/tax-codes.md). 1. Selecciona **Recurrente**. Luego ingresa **15** para el precio y selecciona **EUR** como la moneda. 1. Elige si deseas **Incluir impuestos en el precio**. Puedes usar el valor predeterminado de tu [configuración de impuestos](https://dashboard.stripe.com/test/settings/tax) o establecer el valor manualmente. En este ejemplo, selecciona **Automático**. 1. Selecciona **Mensual** para el **período de facturación**. 1. Haz clic en **Más opciones de tarifas**. Luego selecciona **Tarifa fija** como el modelo de tarifas para este ejemplo. Obtén más información sobre [tarifa fija](https://docs.stripe.com/products-prices/pricing-models.md#flat-rate) y otros [modelos de precios](https://docs.stripe.com/products-prices/pricing-models.md). 1. Agrega una **Descripción del precio** interna y una [Clave de búsqueda](https://docs.stripe.com/products-prices/manage-prices.md#lookup-keys) para organizar, consultar y actualizar precios específicos en el futuro. 1. Haz clic en **Siguiente**. Luego haz clic en **Agregar producto**. Después de crear el producto y el precio, registra el ID del precio para usarlo en pasos sucesivos. La página de tarifas te muestra el ID, que será similar a esto: `price_G0FvDp6vZvdwRZ`. ## Crear o recuperar un objeto Customer antes de la configuración [Lado del servidor] Para reutilizar un método de pago de PayPal para futuros pagos, adjúntalo a un *Cliente* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments). Crea el objeto Customer cuando tu cliente crea una cuenta en tu empresa. Al asociar el ID del objeto Customer a tu propia representación interna de un cliente, podrás recuperar y usar los datos del método de pago guardado más adelante. Si tu cliente no ha creado una cuenta, puedes crear un objeto Customer ahora y asociarlo a tu propia representación interna de la cuenta del cliente más adelante. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Crear un SetupIntent [Lado del servidor] Un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) es un objeto que representa tu intención y hace un seguimiento de los pasos para configurar el método de pago del cliente para futuros pagos. Crea un [SetupIntent](https://docs.stripe.com/api/setup_intents.md) en tu servidor con [payment_method_types](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_types) establecido en `paypal` y especifica el [id](https://docs.stripe.com/api/customers/object.md#customer_object-id) del objeto *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments): ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=paypal" \ -d "payment_method_data[type]=paypal" ``` El objeto Setupintent contiene una [client_secret](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-client_secret), una clave única que debes pasar a Stripe en el lado del cliente para redirigir a tu comprador a PayPal y autorizar la orden. ## Redirigir a tu cliente [Lado del cliente] Cuando un cliente intente configurar su cuenta de PayPal para pagos futuros, te recomendamos usar [Stripe.js](https://docs.stripe.com/js.md) para confirmar el SetupIntent. Stripe.js es nuestra biblioteca principal de JavaScript para crear flujos de pago. Automáticamente gestionará las complejidades, como los redireccionamientos descritos a continuación, y te permite extender tu integración con facilidad a otros métodos de pago en el futuro. Incluye el script de Stripe.js en tu página de pago agregándolo al encabezado de tu archivo HTML. ```html Checkout ``` Crea una instancia de Stripe.js con el siguiente JavaScript en tu página de pago. ```javascript // Set your publishable key. Remember to change this to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>', {} ); ``` Para confirmar la configuración del lado del cliente, especifica el secreto de cliente del objeto SetupIntent que creaste en el paso 3. El secreto de cliente es diferente de las claves API que autentican las solicitudes de la API de Stripe. Debe administrarse con cuidado porque sirve para completar el cargo. No lo registres, no lo insertes en direcciones URL ni lo expongas a nadie excepto al cliente. ### Confirmar la configuración de PayPal Para autorizarte para que puedas usar su cuenta de PayPal para pagos futuros, tu cliente será redirigido a la página del acuerdo de facturación de PayPal, que deberá aprobar antes de ser redirigido nuevamente a tu sitio web. Usa [stripe.confirmPayPalSetup](https://docs.stripe.com/js/setup_intents/confirm_paypal_setup) para gestionar el redireccionamiento desde tu página y completar la configuración. Agrega una `return_url` a esta función para indicar a dónde Stripe debe redirigir al usuario después de que apruebe el acuerdo de facturación en el sitio web de PayPal. ```javascript // Redirects away from the client const {error} = await stripe.confirmPayPalSetup( '{{SETUP_INTENT_CLIENT_SECRET}}', { return_url: 'https://example.com/setup/complete', mandate_data: { customer_acceptance: { type: 'online', online: { infer_from_client: true } } }, } ); if (error) { // Inform the customer that there was an error. } ``` Puedes encontrar el ID del pagador del método de pago y el ID del acuerdo de facturación en la [orden](https://docs.stripe.com/api/mandates/.md) resultante en la propiedad [payment_method_details](https://docs.stripe.com/api/mandates/object.md#mandate_object-payment_method_details-paypal). También puedes encontrar el correo electrónico y el ID de pagador del comprador en la propiedad [PayPal](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-paypal) en [PaymentMethod](https://docs.stripe.com/api/payment_methods.md). | Campo | Valor | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `payer_email` | La dirección de correo electrónico del pagador en su cuenta de PayPal. | | `payer_id` | Un ID único de la cuenta de Paypal del pagador. | | `billing_agreement_id` | El ID del Acuerdo de Facturación de PayPal (BAID). Es un ID generado por PayPal que representa el mandato entre el negocio y el cliente. | ## Supervisar webhooks [Lado del servidor] Utiliza un método como los [webhooks](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks) para confirmar que el cliente autorizó correctamente el acuerdo de facturación, en lugar de depender de que tu cliente regrese a la página de estado del pago. Cuando un cliente autoriza correctamente el acuerdo de facturación, el SetupIntent emite el evento de *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) [setup_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.succeeded). Si un cliente no autoriza correctamente el acuerdo de facturación, el SetupIntent emitirá el evento de webhook [setup_intent.setup_failed](https://docs.stripe.com/api/events/types.md#event_types-setup_intent.setup_failed) y volverá al estado `requires_payment_method`. Cuando un cliente revoca el acuerdo de facturación de su cuenta de PayPal, se emite el [mandate.updated](https://docs.stripe.com/api/events/types.md#event_types-mandate.updated). ## Crear la suscripción [Lado del servidor] Crea una [suscripción](https://docs.stripe.com/api/subscriptions.md) con el precio y el cliente: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer=cus_Gk0uVzT2M4xOKD \ -d default_payment_method=pm_1F0c9v2eZvKYlo2CJDeTrB4n \ -d "items[0][price]=price_F52b2UdntfQsfR" \ -d "expand[0]=latest_invoice.confirmation_secret" \ -d off_session=true ``` Cuando se crea una suscripción, se le cobra al cliente automáticamente porque se establece el [método de pago predeterminado](https://docs.stripe.com/api/customers/create.md#create_customer-invoice_settings-default_payment_method). Una vez efectuado el pago, el estado de la suscripción en el [Dashboard de Stripe](https://dashboard.stripe.com/test/subscriptions) cambia a **Activa**. El precio creado previamente determina las facturaciones sucesivas. ## Gestionar el estado de la suscripción [Lado del cliente] Si el pago inicial se efectúa correctamente, el estado de la suscripción será `active` y no será necesario hacer nada más. Si los pagos fallan, el estado cambia al **estado de suscripción** definido en tu [configuración de cobro automático](https://docs.stripe.com/invoicing/automatic-collection.md). Debes notificar al cliente si falla el pago y [cobrarle con un método de pago distinto](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method). ## Actualizar una suscripción [Lado del servidor] Cuando actualices una suscripción, debes especificar `off_session=true`. De lo contrario, cualquier nuevo pago requerirá una redirección del usuario a PayPal para su confirmación. Por ejemplo, si deseas cambiar la cantidad de un artículo incluido en la suscripción, puedes usar: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer=cus_Gk0uVzT2M4xOKD \ -d default_payment_method=pm_1F0c9v2eZvKYlo2CJDeTrB4n \ -d "items[0][price]=price_F52b2UdntfQsfR" \ -d "items[0][quantity]=2" \ -d off_session=true ``` ## Prueba la integración Prueba tu integración con PayPal con tus [claves de API de prueba](https://docs.stripe.com/keys.md#test-live-modes) al visualizar la página de redireccionamiento. Puedes probar el caso de pago exitoso al autenticar el pago en la página de redireccionamiento. El PaymentIntent pasará de `requires_action` a `succeeded`. Para probar el caso en el que falla la autenticación del usuario, usa tus claves de API de prueba y visualiza la página de redireccionamiento. En la página de redireccionamiento, haz click en **Error en el pago de prueba**. El Paymentintent hará la transición de `requires_action` a `requires_payment_method`. ## Optional: Establecer el período de facturación Al crear una suscripción, automáticamente se define el ciclo de facturación de forma predeterminada. Por ejemplo, si un cliente se suscribe a un plan mensual el 7 de septiembre, se le facturará el día 7 de cada mes posterior. Algunas empresas prefieren configurar el ciclo de facturación de forma manual, así pueden cobrarles a sus clientes en la misma fecha cada ciclo. El argumento [billing cycle anchor](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_cycle_anchor) te permite hacer esto. ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d billing_cycle_anchor=1611008505 ``` Si se configura el ciclo de facturación manualmente, se le cobra al cliente de forma automática un importe prorrateado por el tiempo que pasó entre la creación de la suscripción y la delimitación del ciclo de facturación. Si no quieres cobrarles ese período a los clientes, puedes establecer el argumento [proration_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-proration_behavior) en `none`. También puedes combinar la delimitación del ciclo de facturación con [períodos de prueba](https://docs.stripe.com/billing/subscriptions/paypal.md#trial-periods) para brindarles a los usuarios acceso gratis a tu producto y después cobrarles un importe prorrateado. ## Optional: Suscripciones de prueba Las pruebas gratuitas le dan a los clientes acceso gratis a tu producto por un determinado tiempo. Usar períodos de prueba gratuitos no es lo mismo que establecer [proration_behavior](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-proration_behavior) en `none` porque puedes personalizar cuánto tiempo durará el período gratuito. Para definir este período, debes especificar una marca de tiempo de [finalización de la prueba](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_end). ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` También puedes combinar un [delimitador del ciclo de facturación](https://docs.stripe.com/billing/subscriptions/paypal.md#billing-cycle) con una prueba gratuita. Por ejemplo, es 15 de septiembre y quieres darle a tu cliente acceso a una prueba gratuita durante siete días y después comenzar el ciclo normal de facturación el 1 de octubre. Puedes establecer que la prueba gratuita finalice el 22 de septiembre y el ciclo de facturación en 1 de octubre. Esta opción le brinda al cliente una prueba gratuita por siete días y después se le cobrará un importe prorrateado por el tiempo transcurrido entre que finaliza la prueba gratuita y el 1 de octubre. El 1 de octubre le cobrarás el importe normal de la suscripción por el primer ciclo completo de facturación. ## Optional: Eliminar una cuenta de PayPal guardada Puedes usar la API [detach](https://docs.stripe.com/api/payment_methods/detach.md) para eliminar la cuenta de PayPal guardada de un cliente como método de pago. Cuando desasocies un método de pago de PayPal, se revoca la [orden](https://docs.stripe.com/api/mandates.md) y también se llama a la API de PayPal para cancelar el acuerdo de facturación de PayPal asociado. ```curl curl -X POST https://api.stripe.com/v1/payment_methods/{{PAYMENT_METHOD_ID}}/detach \ -u "<>:" ```