Accept a PayPal payment

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.

Receive events and run business actions

There are a few options for receiving and running business actions.

Manually

Use the Stripe Dashboard to view all your Stripe payments, send email receipts, handle payouts, or retry failed payments.

• View your test payments in the Dashboard

Custom code

Build a webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

• Build a custom webhook

Prebuilt apps

Handle common business events, like automation or marketing and sales, by integrating a partner application.

Stripe.js helps you extend your integration to other payment methods. However, you can manually redirect your customers on your server.

1. Create and confirm a PaymentIntent of type paypal. By specifying payment_method_data, a PaymentMethod is created and immediately used with the PaymentIntent.

You must also provide the URL where your customer is redirected to after they complete their payment in the return_url field. You can provide your own query parameters in this URL. These parameters are included in the final URL upon completing the redirect flow.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=paypal \
  -d "payment_method_data[type]"=paypal \
  --data-urlencode return_url="https://example.com/checkout/complete" \
  -d confirm=true

1. Check that the PaymentIntent has a status of requires_action and the type for next_action is redirect_to_url.

{
  "status": "requires_action",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://hooks.stripe.com/...",
      "return_url": "https://example.com/checkout/complete"
    }
  },
  "id": "pi_1G1sgdKi6xqXeNtkldRRE6HT",
  "object": "payment_intent",
  ...
}

1. Redirect the customer to the URL provided in the next_action.redirect_to_url.url property. This code example is approximate—the redirect method might be different in your web framework.

if payment_intent.status == 'requires_action' && payment_intent.next_action.type == 'redirect_to_url'
  url = payment_intent.next_action.redirect_to_url.url
  redirect(url)
end

Your customer is redirected to the return_url when they complete the payment process. The payment_intent and payment_intent_client_secret URL query parameters are included along with any of your own query parameters. Stripe recommends setting up a webhook endpoint to programmatically confirm the status of a payment.

PayPal supports separate authorization and capture. If you’ve opted for settlement to Stripe, your authorizations are valid for 10 days. Stripe automatically reauthorizes the payment to extend the authorization period by another 10 days. This results in a total of 20 days. If the reauthorization doesn’t work, Stripe makes the payment expire right after 10 days. Listen to the charge.expired webhook to know when the authorization period ends.

If you’ve opted for settlement to PayPal, your authorizations remain valid for 3 days. Stripe tries to extend the authorization period by another 3 days. For an extended guaranteed authorization period of up to 10 days, referred to as honor period on PayPal, contact PayPal support.

Tell Stripe to authorize only

To indicate that you want separate authorization and capture, set capture_method to manual when creating the PaymentIntent. This parameter instructs Stripe to only authorize the amount on the customer’s PayPal account.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=eur \
  -d capture_method=manual \
  -d "payment_method_types[]"=paypal \
  -d "payment_method_data[type]"=paypal \
  -d confirm=true \
  --data-urlencode return_url="http://example.com"

Upon authorization success, Stripe sends a payment_intent.amount_capturable_updated event. Read our Events guide to learn more.

Capture the funds

After the authorization succeeds, the PaymentIntent status transitions to requires_capture. To capture the authorized funds, make a PaymentIntent capture request. The total authorized amount is captured by default—you can’t capture more than this, but you can capture less.

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount_to_capture=750

Optional Cancel the authorization

If you need to cancel an authorization, you can cancel the PaymentIntent.

By default, Stripe only allows synchronous payment methods on PayPal. This guarantees that you receive an immediate notification for the success or the failure of each payment. If you allow asynchronous payment methods, you might encounter delayed notifications for some payments. As a result, you must rely on webhook endpoints to receive notifications about the success or failure of certain payments.

To enable asynchronous payments on PayPal, contact Stripe support.

These are the common error codes and corresponding details while integrating with PayPal. If a PayPal API request returned the error, it includes a PayPal issue code and the associated Debug ID for the request. You can use the Debug ID when contacting PayPal support to get help with your issue.

To test a successful payment on your PayPal integration, use your test API keys and view the redirect page. This page shows you the options to Authorize or Fail the user authentication as test scenarios. When you select Authorize test payment, the PaymentIntent transitions from requires_action 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 then transitions from requires_action to requires_payment_method.

To simulate the most common integration and failure scenarios for PayPal payments, pass email values that match the patterns described in Test Scenarios when you create the PaymentIntent as part of the billing details. For example, when confirming the PaymentIntent server-side, a request simulating a transaction refused by PayPal would look like:

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=paypal \
  -d "payment_method_data[type]"=paypal \
  --data-urlencode "payment_method_data[billing_details][email]"="transaction_refused@example.com"

Test scenarios