Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment UIs
Payment scenarios
In-person payments
Other Stripe products

Accept a PayPal payment

Learn how to accept PayPal payment, a digital wallet popular with businesses in Europe.

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
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a PaymentIntent
Server-side

Stripe uses a payment object, called a PaymentIntent, to track and handle all the states of the payment until it’s completed. Create a PaymentIntent on your server, specifying the amount to collect and the currency. If you already have an integration using the Payment Intents API, add paypal to the list of payment method types for your PaymentIntent.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=paypal

Included in the returned PaymentIntent is a client secret, which is used to securely complete the payment process instead of passing the entire PaymentIntent object. Send the client secret back to the client so you can use it in later steps.

Include a custom description

By default, the order details on the PayPal users purchase activity page displays the order amount. You can change this by providing a custom description in the description property.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=eur \
  -d description="A sample description" \
  -d "payment_method_types[]"=paypal

Customize the preferred locale

By default, the PayPal authorization page is localized based on variables such as the merchant’s country. You can set this to your customer’s preferred locale using the preferred_locale property. The value must be a two-character lowercased language code, followed by a hyphen (-), followed by a two-character uppercased country code. For example, the value for a French-language user in Belgium would be fr-BE. See supported locales for more information.

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=paypal \
  -d "payment_method_options[paypal][preferred_locale]"=fr-BE

Statement descriptors with PayPal

The descriptor that appears on the buyer’s bank statement is set by PayPal, and by default is PAYPAL *YOUR_BUSINESS_NAME. If you set the statement_descriptor field when creating the PaymentIntent, its value is appended to the one set by PayPal, up to a total limit of 22 characters.

For example, if your business name in PayPal is BUSINESS and you set statement_descriptor to order_id_1234, buyers see PAYPAL *BUSINESS order on their bank account statement.

Submit the payment to Stripe
Client-side

When a customer clicks to pay with PayPal, use Stripe.js to submit the payment to Stripe. Stripe.js is the foundational JavaScript library for building payment flows. It automatically handles complexities like the redirect described below, and enables you to extend your integration to other payment methods. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js
// 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(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

To create a payment on the client side, pass the client secret of the PaymentIntent object that you created in Step 2. The client secret is different from your API keys that authenticate Stripe API requests. Handle this carefully because it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

Confirm PayPal payment

Call stripe.confirmPayPalPayment to redirect your customer to PayPal to complete the payment. Add a return_url to indicate where Stripe should redirect your customer to after they complete the payment.

client.js
// Redirects away from the client
const {error} = await stripe.confirmPayPalPayment(
  '{{PAYMENT_INTENT_CLIENT_SECRET}}',
  {
    return_url: 'https://example.com/checkout/complete',
  }
);

if (error) {
  // Inform the customer that there was an error.
}

If you settle your PayPal funds with PayPal, the balance transaction linked to the payment has an amount of zero regardless of the payment amount, because the transaction represents money moved into and out of your Stripe balance. However, for PayPal, funds settle in your PayPal balance, and no money goes to your Stripe balance. The balance transaction in this case also includes fees associated with it. Learn about other important details related to the settlement preference.

Handling the redirect

The following URL query parameters are provided when Stripe redirects the customer to the return_url.

ParameterDescription
payment_intentThe unique identifier for the PaymentIntent.
payment_intent_client_secretThe client secret of the PaymentIntent object.

You may also append your own query parameters when providing the return_url. They persist throughout the redirect process. The return_url should correspond to a page on your website that provides the status of the payment. You should verify the status of the PaymentIntent when rendering the return page. You can do so by using the retrievePaymentIntent function from Stripe.js and passing in the payment_intent_client_secret.

(async () => {
  const url = new URL(window.location);
  const clientSecret = url.searchParams.get('payment_intent_client_secret');

  const {paymentIntent, error} = await stripe.retrievePaymentIntent(clientSecret);
  if (error) {
    // Handle error
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment
  }
})();

You can find the payment owner’s name, email, payer ID, and transaction ID in the payment_method_details property.

FieldValue
payer_emailThe email address of the payer on their PayPal account.
payer_nameThe name of the payer on their PayPal account.
payer_idA unique ID of the payer’s PayPal account.
transaction_idA unique transaction ID generated by PayPal.
{
  "charges": {
    "data": [
      {
        "payment_method_details": {
          "paypal": {
            "payer_id": "H54KFE9XXVVYJ",
            "payer_email": "jenny@example.com",
            "payer_name": "Jenny Rosen",
            "transaction_id": "89W40396MK104212M"
          },
          "type": "paypal"
        },
        "id": "src_16xhynE8WzK49JbAs9M21jaR",
        "object": "source",
        "amount": 1099,
        "client_secret": "src_client_secret_UfwvW2WHpZ0s3QEn9g5x7waU",
        "created": 1445277809,
        "currency": "eur",
        "flow": "redirect",
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc