Set up a subscription with PayPal
Learn how to create and charge for a subscription with PayPal.
Use this guide to set up a subscription using PayPal and Checkout.
A Checkout Session represents the details of a customer’s intent to purchase. Create a Checkout Session when a customer wants to start a subscription. After redirecting a customer to a Checkout Session, Stripe presents a payment form where they can complete their purchase. After they complete a purchase, Stripe redirects them back to your site.
Enable PayPal recurring payments
Stripe automatically enables recurring payments for most users when they activate PayPal payments in the Stripe Dashboard. However, due to PayPal’s policies and regional restrictions, you might need to manually enable PayPal recurring payments in the Dashboard.
Set up StripeServer-side
First, you need a Stripe account. Register now.
Use our official libraries for access to the Stripe API from your application:
Create recurring products and prices
Caution
The Prices API unifies how one-time purchases and subscriptions are modeled on Stripe. Existing integrations that don’t use the Prices API are still supported. However, some Checkout features only support Prices. See the migration guide to upgrade to the Prices API.
To use Checkout, you first need to create a Product and a Price. Different physical goods or levels of service must be represented by products. Each product’s pricing is represented by one or more prices.
For example, you can create a software product that has four prices: 10 USD/month, 100 USD/year, 9 eur/month, and 90 eur/year. This allows you to change and add prices without needing to change the details of your underlying products. You can either create a product and price through the API or through the Stripe Dashboard.
If your price is determined at checkout (for example, the customer sets a donation amount) or you prefer not to create prices upfront, you can create prices inline at Checkout Session creation.
Create a Checkout SessionClient-sideServer-side
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.
<html> <head> <title>Checkout</title> </head> <body> <form action="/create-checkout-session" method="POST"> <button type="submit">Checkout</button> </form> </body> </html>
Create a Checkout Session with the ID of an existing Price. Make sure that mode is set to subscription
and you pass at least one recurring price. You can add one-time prices in addition to recurring prices. After creating the Checkout Session, redirect your customer to the URL returned in the response.
When your customer successfully completes their payment, they’re redirected to the success_
, a page on your website that informs the customer that their payment was successful. Make the Session ID available on your success page by including the {CHECKOUT_
template variable in the success_
as in the above example.
When your customer clicks on your logo in a Checkout Session without completing a payment, Checkout redirects them back to your website by navigating to the cancel_
. Typically, this is the page on your website that the customer viewed prior to redirecting to Checkout.
Checkout Sessions expire 24 hours after creation by default.
Caution
Don’t rely on the redirect to the success_
alone for detecting payment initiation, as:
- Malicious users could directly access the
success_
without paying and gain access to your goods or services.url - Customers may not always reach the
success_
after a successful payment—they might close their browser tab before the redirect occurs.url
Confirm the payment is successful
Note
When a buyer successfully confirms a subscription on Stripe with PayPal, they receive a receipt from Stripe as well as from PayPal.
When your customer completes a payment, they’re redirected to the URL that you specified as the success_
. This is typically a page on your website that informs your customer that their payment was successful.
Use the Dashboard, a custom webhook, or a third-party plugin to handle post-payment events like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.
You can use plugins like Zapier to automate updating your purchase fulfillment systems with information from Stripe payments.
Some examples of automation supported by plugins include:
- Updating spreadsheets used for order tracking in response to successful payments
- Updating inventory management systems in response to successful payments
- Triggering notifications to internal customer service teams using email or chat applications
Test the integration
Test your PayPal integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The PaymentIntent will transition from requires_
to succeeded
.
To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click Fail test payment. The PaymentIntent will transition from requires_
to requires_
.
OptionalAdding a one-time setup feeServer-side
In addition to passing recurring prices, you can add one-time prices in subscription
mode. These are only on the initial invoice created by the subscription. This is useful for adding setup fees or other one-time fees associated with a subscription.
OptionalCreate prices and products inlineServer-side
In addition to passing in existing price IDs, you can also define your item price at Checkout session creation. First define a Product. Then create a Checkout session using the product ID, by passing it into price_data with the unit_
, currency
, and recurring
details:
If you also need to create products inline, you can do so with product_data:
OptionalExisting customersServer-side
If you have previously created a Customer object to represent a customer, use the customer argument to pass their Customer ID when creating a Checkout Session. This ensures that all objects created during the Session are associated with the correct Customer object.
When you pass a Customer ID, Stripe also uses the email stored on the Customer object to prefill the email field on the Checkout page. If the customer changes their email on the Checkout page, it will be updated on the Customer object after a successful payment.
OptionalPrefill customer dataServer-side
If you’ve already collected your customer’s email and want to prefill it in the Checkout Session for them, pass customer_email when creating a Checkout Session.
OptionalHandling trialsServer-side
You can use trial_end or trial_period_days on the Checkout session to specify the duration of the trial period. In this example we use trial_
to create a Checkout session for a subscription with a 30 days trial.
Checkout displays the following information automatically for subscriptions with trials:
- Trial period
- Frequency and amount of charges after trial expiration
For more information on compliance requirements, visit the Billing or support guide.
OptionalTax ratesServer-side
You can specify tax rates (Sales, VAT, GST, and others) in Checkout Sessions to apply taxes to subscriptions.
- Use fixed tax rates when you know the exact tax rate to charge your customers before they start the checkout process (for example, you only sell to customers in the UK and always charge 20% VAT).
- With the Prices API, you can use dynamic tax rates when you require more information from your customer (for example, their billing or shipping address) before determining the tax rate to charge. With dynamic tax rates, you create tax rates for different regions (for example, a 20% VAT tax rate for customers in the UK and a 7.25% sales tax rate for customers in California, US) and Stripe attempts to match your customer’s location to one of those tax rates.
You can use Stripe’s data exports to populate the periodic reports required for remittance. Visit Tax reporting and remittance for more information.
OptionalAdding couponsServer-side
You can apply coupons to subscriptions in a Checkout Session by setting discounts. This coupon overrides any coupon on the customer. If you’re creating a subscription with an existing customer, any coupon associated with the customer is applied to the subscription’s invoices.
Adding customer-facing promotion codes
You can also enable user-redeemable Promotion Codes using the allow_promotion_codes parameter in Checkout Sessions. When allow_
is enabled on a Checkout Session, Checkout includes a promotion code redemption box for your customers to use. Create your coupons and promotion codes through the Dashboard or API in order for your customers to redeem them in Checkout.