Set up future PayPal payments
Learn how to save PayPal details and charge your customers later.
Set up future PayPal payments to save customer payment details for subscriptions, delayed charges, and streamlined future purchases. Learn how to enable and use recurring payments with PayPal through Stripe.
Enable 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, some users might need to enable recurring payments manually. This includes users that set up their accounts before we introduced automatic enablement. To manually enable recurring payments:
- Go to your Payment methods settings.
- Click PayPal > Enable in the Recurring payments section.
After you enable recurring payments, it appears as pending in the Dashboard. It usually takes up to five business days to get access.
When you’re granted access, recurring payments are available in your PayPal settings. In testing environments, recurring payments are enabled by default.
Checkout
Direct API
Mobile
Use Stripe Checkout to collect PayPal payment details in advance, and determine the final amount or payment date later. Use it to:
- Save payment methods to a wallet to streamline future purchases
- Collect surcharges after fulfilling a service
- Start a free trial for a subscription
Set up Stripe Server-side
First, you need a Stripe account. Register now.
Use our official libraries for access to the Stripe API from your application:
Command Line
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
Create or retrieve a customer before setup Server-side
To reuse a PayPal payment method for future payments, attach it to an object that represents your customer.
Use the Accounts v2 API to represent customers
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.
To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.
For most use cases, we recommend modelling your customers as customer-configured Account objects instead of using Customer objects.
Create a customer-configured Account or Customer when your customer creates an account with your business or when saving a payment method. Associate the object’s ID with your own internal representation of a customer.
Create a new customer or retrieve an existing one to associate with this payment.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Create a Checkout Session Client-side Server-side
Before you can accept PayPal payments, your customer must authorise you to use their PayPal account for future payments through Stripe Checkout.
Add a checkout button to your website that calls a server-side endpoint to create a Checkout Session.
index.html
<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 in setup mode to collect the required information. After creating the Checkout Session, redirect your customer to the URL returned in the response.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
When your customer provides their payment method details, they’re redirected to the success_url, a page on your website that informs them that their payment method was saved successfully. Make the Session ID available on your success page by including the {the related setting} template variable in the success_url as in the above example.
Caution
Don’t rely on the redirect to the success_url alone for detecting payment initiation, because:
- Malicious users could directly access the success _ url without paying and gain access to your goods or services.
- After a successful payment, customers might close their browser tab before they’re redirected to the success _ url .
Retrieve the payment method Server-side
After a customer submits their payment details, retrieve the PaymentMethod object. A PaymentMethod stores the customer’s PayPal account information for future payments. You can retrieve the PaymentMethod synchronously using the success_url or asynchronously using webhooks.
The decision to retrieve the PaymentMethod synchronously or asynchronously depends on your tolerance for dropoff, as customers might not always reach the success_url after a successful payment (for example, it’s possible for them to close their browser tab before the redirect occurs). Using webhooks prevents your integration from experiencing this form of dropoff.
Handle checkout.session.completed webhooks, which contain a Session object. To learn more, see setting up webhooks. The following example is a checkout.session.completed response.
{
"id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
"object": "event",
"api_version": "2019-03-14",
"created": 1561420781,
"data": {
"object": {
"id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
"object": "checkout.session",
"billing_address_collection": null,
"client_reference_id": null,
"customer": null,
"customer_email": null,
"display_items": [],
"mode": "setup",
"setup_intent": "seti_1EzVO3HssDVaQm2PJjXHmLlM",
"submit_type": null,
"subscription": null,
"success_url": "https://example.com/success"
}
},
"livemode": false,
"pending_webhooks": 1,
"request": {
"id": null,
"idempotency_key": null
},
"type": "checkout.session.completed"
}
Note the value of the setup_intent key, which is the ID for the SetupIntent created with the Checkout Session. A SetupIntent is an object used to set up the customer PayPal account information for future payments. Retrieve the SetupIntent object with the ID. The returned object contains the payment_method ID.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Handle post-setup events Server-side
Use a method such as webhooks to confirm the billing agreement was authorised successfully by your customer, instead of relying on your customer to return to the payment status page. When a customer successfully authorises the billing agreement, the SetupIntent emits the setup_intent.succeeded webhook event. If a customer doesn’t successfully authorise the billing agreement, the SetupIntent will emit the setup_intent.setup_failed webhook event and returns to a status of requires_payment_method. When a customer revokes the billing agreement from their PayPal account, the mandate.updated is emitted.
Test the integration
Test your PayPal integration with your test API keys by viewing the redirect page. You can test a successful payment by authenticating the payment on the redirect page. The PaymentIntent will transition from requires_action to succeeded.
To test authentication failure, use your test API keys and view the redirect page. On the redirect page, click Fail test payment. The PaymentIntent will transition from requires_action to requires_payment_method.
Use the payment method for future payments Server-side
When you’re ready to charge your customer off-session, use the customer and ‘ ‘PaymentMethod’ ’ IDs to create a PaymentIntent.
To find a paypal instrument to charge, list the PaymentMethods associated with your customer.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
When you have the customer and PaymentMethod IDs, create a PaymentIntent with the amount and currency of the payment. Set the following parameters to make the ‘ ‘off-session payment’ ’:
- Set off_session to true to indicate that the customer isn’t in your checkout flow during this payment attempt. This causes the PaymentIntent to throw an error if authentication is required.
- Set the value of the PaymentIntent’s confirm property to true , which causes confirmation to occur immediately when the PaymentIntent is created.
- Set payment_method to the ID of the PaymentMethod .
- Set customer or customer_account to the customer ID.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
User-initiated payment method cancellation Server-side
A customer can cancel the subscription (Billing Agreement) through their PayPal account. When they do so, Stripe emits a mandate.updated webhook. All subsequent PaymentIntents using the saved Payment Method will fail until you change to a Payment Method with active mandates. When payments fail for Subscriptions, the status changes to the Subscription status configured in your automatic collection settings. Notify the customer of failure and charge them with a different payment method.