App Switch: JavaScript SDK one-time payments

Overview

App Switch helps PayPal customers start a transaction in a browser or app and complete it in the PayPal app, streamlining checkout with strong multi-factor authentication. The buyer can use biometrics or a passkey to log in instead of entering their password.

The buyer experience falls back to the web flow in cases where App Switch isn't available.

Eligibility

Now available in the United States. We will roll out this feature to the EU and other markets as well.
Available for one-time payment flows only.
Must be integrated using either an Orders v2 or Payment Method Tokens v3 REST API integration on the server side.
App Switch doesn't support Continue flows.

App Switch does not work with the following JavaScript SDK features:

actions.restart(): Instead, see how to handle declines after approval to manage INSTRUMENT_DECLINED responses.
onShippingChange, onShippingAddressChange, onShippingOptionsChange: Instead, use server-side shipping callbacks.

Buyer flow

Buyer,is,directed,to,the,PayPal,app,to,complete,the,transaction.

The buyer selects the PayPal button from another app or website.
The PayPal app opens and uses biometrics or a passkey to log the buyer in.
The buyer reviews purchase details and completes the transaction in the PayPal app.
The buyer is returned to the app or website where they selected the PayPal button.

Integrate server-side

Enable App Switch when you make a Create order API request by including following 2 parameters in the payment_source.paypal.experience_context:

return_url: This URL tells App Switch where to send the buyer after completing checkout on the PayPal app. Set the URL to the page where the buyer selected the PayPal button.
cancel_url: This URL tells App Switch where to send the buyer when the buyer cancels or doesn't complete the transaction on the PayPal app. Set the URL to the page where the buyer selected the PayPal button.

To ensure the buyer is redirected back to the same browser window and tab, the return_url and cancel_url must:

Be the same.
Match the URL of the page where the buyer selected the PayPal button.

To ensure buyer session can be fully re-established in your integration, the return_url and cancel_url must:

Contain a unique identifier for the buyer's session to identify the buyer when they return from App Switch.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H 'Content-Type: application/json' \
-H 'PayPal-Request-Id: YOUR_PAYPAL_REQUEST_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{
  "intent": "CAPTURE",
  "payment_source": {
    "paypal": {
      "email_address": "[email protected]",
        "experience_context": {
          "user_action": "PAY_NOW",
          "return_url": "https://example.com/merchant_app_universal_link",
          "cancel_url": "https://example.com/merchant_app_universal_link"
        }
    }
  },
  "purchase_units": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "64.00"
        }
    }
]
}

Integrate

Update the following 2 payment flow steps to integrate App Switch with a website or app:

Use the server-side create Order API request to configure App Switch.
Use the client-side JavaScript v5 SDK to enable App Switch and add support for the resume flow.

Note: Running the Javascript JS SDK in an iframe will block App Switch capabilities.

Integrate client-side

You'll need to make 2 changes to integrate client-side:

Add the App Switch flag to the PayPal button setup.
Determine whether the buyer is returning from App Switch. If so, run buttons.resume() before rendering the button.

The PayPal SDK can then handle expected user flows plus edge cases for a buyer returning to a website to complete payment. The SDK uses the onApprove, onCancel and onError callbacks to communicate the result of the app switch.

The client-side Buttons component has an option for App Switch: appSwitchWhenAvailable: true.

Use this flag to control whether you want to use App Switch for eligible transactions. You can dynamically control this flag on the client side rather than the server side. Possible reasons include:

Experimentation: You want to perform A/B testing.
Performance issues: It's tougher to make a server-side change than a client-side change.
URLs: Return or cancel URLs aren't configured correctly.
Use cases: You can change the flag value based on the use case, such as not requiring a shipping callback for digital goods.

const buttons = paypal.Buttons({
  // Sets up the transaction when a payment button is selected
  appSwitchWhenAvailable: true, // Need an indicator to trigger App Switch
  createOrder: createOrderCallback, // Call API to create order
  onApprove: onApproveCallback,
  onError: function(error) {
    // Do something with the error from the SDK
  },
});

Resume flow

The resume flow solves for some edge cases by helping a buyer resume a transaction completed in a different window or browser tab. However, this resume flow can lead to additional issues:

If a merchant relies on a client-side state, that state can be lost in a new browser or tab. For example, if a buyer starts a transaction in one tab where they're authenticated but moves a new browser, they won't remain authenticated. Include essential state information in the redirect URL to ensure the buyer can complete the transaction in a new browser.
If a buyer is redirected to a new browser tab, the original tab remains open. The buyer can close the original tab after completing the transaction. If the buyer doesn't close the tab, the tab remains open in a loading state until it times out.
The resume flow won't work with client-side action calls. Replace client-side actions.* with server-side calls.
Client-side callbacks such as onApprove() and onCancel() will continue to work.

// If you support App Switch, the buyer may end up in a new tab depending on the browser
// To trigger flow completion, execute the following code after re-instantiating buttons:
if (buttons.hasReturned()) {
  buttons.resume();
} else {
  buttons.render("#paypal-button-container");
}

Handle declines after approval

The onApprove callback triggers after the buyer is approved in the merchant app. At this stage, the merchant initiates a call to capture the payment or save the payment method to the vault. An INSTRUMENT_DECLINED response may occur during this call. Take the following steps to handle this scenario:

Display a clear error message informing the buyer to restart checkout.
Re-render the PayPal button for the buyer to select and restart checkout.
Ensure you use the same OrderID as the previous failed Instrument Declined flow so we can disable the failed funding instrument in the retry Checkout flow.

Do not use actions.restart() to handle this error in the App Switch flow. Calling it will have no effect.

Test App Switch

App Switch supports PayPal customers who have the PayPal app installed to complete their transactions in the PayPal app, streamlining checkout with strong multi-factor authentication. This feature can be tested in both the PayPal production app and sandbox environments. To test App Switch, make sure your integration is:

App Switch eligible.
You have completed the PayPal App Switch integration.

Test your integration using PayPal's sandbox

PayPal's sandbox helps users in and outside the United States test the App Switch consumer experience. Availability in the EU and other countries is coming soon.

Who is this solution intended for?

This solution is available for your development team internationally.

App Switch Compatibility

Review the following table to see how App Switch works in different environments. Use this information to check if things are working during testing and spot any situations where you might need to set up fallback handling.

Platform, Browser, Mode, Availability, Notes
Platform	Browser	Mode	Notes
iOS	Safari	Default browser
iOS	Safari	Private
iOS	Safari	Not default	App Switch redirects to the default browser
iOS	Chrome	Default browser	App Switch redirects to a new tab in the same browser
Android	Chrome	Default browser
Android	Chrome	Incognito	Fallback experience
Android	Chrome	Not default	App Switch redirects in the default browser
Android	Firefox/other	Default	App Switch redirects to a new tab in the same browser

Best Practices

Non-default browser behavior If the buyer initiates checkout from a non-default browser, the return from App Switch may open in the buyer's default browser. Use the return URL to restore buyer session and repaint the checkout page to avoid errors.
Not eligible for iframe integrations App Switch is not supported in iframes. If your checkout page is embedded in an iframe, do not integrate App Switch.

Avoiding double capture in PayPal orders

Without proper checks, you might accidentally capture (collect payment for) the same order multiple times due to:

Network issues causing retries
User refreshing the page during checkout
System glitches triggering the same callback twice

You can avoid accidentally charging customers twice for the same order by checking the order before capturing. Follow this three-step process:

First, the customer approves the payment, triggering the onApprove callback.
Then, check the order's current status by sending a GET request to PayPal's Orders v2 API: curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN-ID.
Finally, make a decision based on the order status:
- If order.status === "COMPLETED", PayPal has already captured the order, so you can stop processing.
- Only proceed with the capture request if the status is not COMPLETED.

This code sample shows the flow from SDK callback, checking the order status, and conditional capturing:

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN_ID \
  -H 'Authorization: Bearer ACCESS-TOKEN'

if (order.status==="COMPLETED") {
## Order has already been captured! Don't capture again

return;
}
else {

## if status is not completed (captured), capture the order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN_ID/capture \
  -H 'Content-Type: application/json' \
  -H 'PayPal-Request-Id: REQUEST-ID' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{}'

}

Note the use of the PayPal-Request-Id header in the capture request. This provides additional idempotency protection, ensuring PayPal won't process the same capture request multiple times even if you send it repeatedly.

Why this works

This approach prevents double charges by:

Always checking the current state of the order before attempting to capture.
Only capturing when necessary, preventing duplicate API calls.
Providing a clean way to handle edge cases like browser refreshes or timeouts.

By implementing this pattern, you will only charge customers once, even if the system triggers their payment callback multiple times.

Use cases that can be tested

Scenario, Expected behavior
Scenario	Expected behavior
User starts from a Native Default browser such as Safari on an iOS device or Chrome on an Android device (Happy Path).	The user is switched to the PayPal app, and after completing the checkout flow, the user is switched to the same merchant browser tab they initially used.
User starts from a Non-Native default browser such as Chrome on iOS or Firefox on Android.	The user is App switched to the PayPal app, and after completing the checkout flow, the user is switched back to the user's default browser.
Post App Switch changes the payment method on the pay sheet and completes the flow.	Completing checkout flow with the successful creation of BA token or payment token.
Post Login cancel the operation on the pay sheet screen in the PayPal App.	The user is switched back to the merchant browser upon canceling out of the checkout flow.
Add a new card.	When users select Add Card, they will be prompted to log in again. After logging in, the new card form will be displayed. After the new card is added, the user can proceed with checkout.

Preconditions

Long-lived session or remember me flow
Face ID or Biometric

Log in to your PayPal app. On the home screen, select the avatar icon.
On the Personal account screen, select the Login and security option.
The Login and security screen should show the face ID or fingerprint and Extend your login sessions options disabled.
Select the toggle icon to enable each login method.

Test on iOS

Download TestFlight from the App Store.
Open Join the PayPal - Pay, Send, Save beta on your device.
Select View in TestFlight and select Open.
Select Install or choose Update for an existing build. This build will become unavailable after 90 days.

If you have the production version of the PayPal app installed, you will get a prompt stating that you already have the app installed. Select Install to replace it with the TestFlight build.

Test on Android

Open the Firebase App Distribution site to join the tester program.
Enter your email address to receive an invite.
To confirm your access, open the invite email on a device.
Select Get Started on your device after opening the invite email.
Check the consent box to agree to Firebase testing and select Accept Invitation. You now have access to the tester portal.
Select Download next to the latest build in the list.
After the download is complete, open the build. You can also find the file in your device notifications or in your downloads folder in the Files app.
Select Install when prompted to download the PayPal app.
If you see Update instead of Install, the PayPal app is already installed on your device. Select Cancel and uninstall the PayPal app before proceeding.
Select Open to access the PayPal app.
Log in using the email address provided in the invite. Your device now has the sandbox version of the PayPal app.

Select the Download App Tester button to ensure you receive notifications when new versions of the sandbox app are available.

After you complete the integration, contact your PayPal support team to enable App Switch for production traffic.

Overview

The buyer experience falls back to the web flow in cases where App Switch isn't available.

Eligibility

Now available in the United States. We will roll out this feature to the EU and other markets as well.
Available for one-time payment flows only.
Must be integrated using either an Orders v2 or Payment Method Tokens v3 REST API integration on the server side.
App Switch doesn't support Continue flows.

App Switch does not work with the following JavaScript SDK features:

actions.restart(): Instead, see how to handle declines after approval to manage INSTRUMENT_DECLINED responses.
onShippingChange, onShippingAddressChange, onShippingOptionsChange: Instead, use server-side shipping callbacks.

Buyer flow

The buyer selects the PayPal button from another app or website.
The PayPal app opens and uses biometrics or a passkey to log the buyer in.
The buyer reviews purchase details and completes the transaction in the PayPal app.
The buyer is returned to the app or website where they selected the PayPal button.

Integrate server-side

Enable App Switch when you make a Create order API request by including following 2 parameters in the payment_source.paypal.experience_context:

return_url: This URL tells App Switch where to send the buyer after completing checkout on the PayPal app. Set the URL to the page where the buyer selected the PayPal button.
cancel_url: This URL tells App Switch where to send the buyer when the buyer cancels or doesn't complete the transaction on the PayPal app. Set the URL to the page where the buyer selected the PayPal button.

To ensure the buyer is redirected back to the same browser window and tab, the return_url and cancel_url must:

Be the same.
Match the URL of the page where the buyer selected the PayPal button.

To ensure buyer session can be fully re-established in your integration, the return_url and cancel_url must:

Contain a unique identifier for the buyer's session to identify the buyer when they return from App Switch.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H 'Content-Type: application/json' \
-H 'PayPal-Request-Id: YOUR_PAYPAL_REQUEST_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{
  "intent": "CAPTURE",
  "payment_source": {
    "paypal": {
      "email_address": "[email protected]",
        "experience_context": {
          "user_action": "PAY_NOW",
          "return_url": "https://example.com/merchant_app_universal_link",
          "cancel_url": "https://example.com/merchant_app_universal_link"
        }
    }
  },
  "purchase_units": [
      {
        "amount": {
          "currency_code": "USD",
          "value": "64.00"
        }
    }
]
}

Integrate

Update the following 2 payment flow steps to integrate App Switch with a website or app:

Use the server-side create Order API request to configure App Switch.
Use the client-side JavaScript v5 SDK to enable App Switch and add support for the resume flow.

Note: Running the Javascript JS SDK in an iframe will block App Switch capabilities.

Integrate client-side

You'll need to make 2 changes to integrate client-side:

Add the App Switch flag to the PayPal button setup.
Determine whether the buyer is returning from App Switch. If so, run buttons.resume() before rendering the button.

The client-side Buttons component has an option for App Switch: appSwitchWhenAvailable: true.

Use this flag to control whether you want to use App Switch for eligible transactions. You can dynamically control this flag on the client side rather than the server side. Possible reasons include:

Experimentation: You want to perform A/B testing.
Performance issues: It's tougher to make a server-side change than a client-side change.
URLs: Return or cancel URLs aren't configured correctly.
Use cases: You can change the flag value based on the use case, such as not requiring a shipping callback for digital goods.

const buttons = paypal.Buttons({
  // Sets up the transaction when a payment button is selected
  appSwitchWhenAvailable: true, // Need an indicator to trigger App Switch
  createOrder: createOrderCallback, // Call API to create order
  onApprove: onApproveCallback,
  onError: function(error) {
    // Do something with the error from the SDK
  },
});

Resume flow

The resume flow solves for some edge cases by helping a buyer resume a transaction completed in a different window or browser tab. However, this resume flow can lead to additional issues:

If a merchant relies on a client-side state, that state can be lost in a new browser or tab. For example, if a buyer starts a transaction in one tab where they're authenticated but moves a new browser, they won't remain authenticated. Include essential state information in the redirect URL to ensure the buyer can complete the transaction in a new browser.
If a buyer is redirected to a new browser tab, the original tab remains open. The buyer can close the original tab after completing the transaction. If the buyer doesn't close the tab, the tab remains open in a loading state until it times out.
The resume flow won't work with client-side action calls. Replace client-side actions.* with server-side calls.
Client-side callbacks such as onApprove() and onCancel() will continue to work.

// If you support App Switch, the buyer may end up in a new tab depending on the browser
// To trigger flow completion, execute the following code after re-instantiating buttons:
if (buttons.hasReturned()) {
  buttons.resume();
} else {
  buttons.render("#paypal-button-container");
}

Handle declines after approval

Display a clear error message informing the buyer to restart checkout.
Re-render the PayPal button for the buyer to select and restart checkout.
Ensure you use the same OrderID as the previous failed Instrument Declined flow so we can disable the failed funding instrument in the retry Checkout flow.

Do not use actions.restart() to handle this error in the App Switch flow. Calling it will have no effect.

Test App Switch

App Switch eligible.
You have completed the PayPal App Switch integration.

Test your integration using PayPal's sandbox

PayPal's sandbox helps users in and outside the United States test the App Switch consumer experience. Availability in the EU and other countries is coming soon.

Who is this solution intended for?

This solution is available for your development team internationally.

App Switch Compatibility

Platform, Browser, Mode, Availability, Notes
Platform	Browser	Mode	Notes
iOS	Safari	Default browser
iOS	Safari	Private
iOS	Safari	Not default	App Switch redirects to the default browser
iOS	Chrome	Default browser	App Switch redirects to a new tab in the same browser
Android	Chrome	Default browser
Android	Chrome	Incognito	Fallback experience
Android	Chrome	Not default	App Switch redirects in the default browser
Android	Firefox/other	Default	App Switch redirects to a new tab in the same browser

Best Practices

Non-default browser behavior If the buyer initiates checkout from a non-default browser, the return from App Switch may open in the buyer's default browser. Use the return URL to restore buyer session and repaint the checkout page to avoid errors.
Not eligible for iframe integrations App Switch is not supported in iframes. If your checkout page is embedded in an iframe, do not integrate App Switch.

Avoiding double capture in PayPal orders

Without proper checks, you might accidentally capture (collect payment for) the same order multiple times due to:

Network issues causing retries
User refreshing the page during checkout
System glitches triggering the same callback twice

You can avoid accidentally charging customers twice for the same order by checking the order before capturing. Follow this three-step process:

First, the customer approves the payment, triggering the onApprove callback.
Then, check the order's current status by sending a GET request to PayPal's Orders v2 API: curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN-ID.
Finally, make a decision based on the order status:
- If order.status === "COMPLETED", PayPal has already captured the order, so you can stop processing.
- Only proceed with the capture request if the status is not COMPLETED.

This code sample shows the flow from SDK callback, checking the order status, and conditional capturing:

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN_ID \
  -H 'Authorization: Bearer ACCESS-TOKEN'

if (order.status==="COMPLETED") {
## Order has already been captured! Don't capture again

return;
}
else {

## if status is not completed (captured), capture the order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/TOKEN_ID/capture \
  -H 'Content-Type: application/json' \
  -H 'PayPal-Request-Id: REQUEST-ID' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{}'

}

Why this works

This approach prevents double charges by:

Always checking the current state of the order before attempting to capture.
Only capturing when necessary, preventing duplicate API calls.
Providing a clean way to handle edge cases like browser refreshes or timeouts.

By implementing this pattern, you will only charge customers once, even if the system triggers their payment callback multiple times.

Use cases that can be tested

Scenario, Expected behavior
Scenario	Expected behavior
User starts from a Native Default browser such as Safari on an iOS device or Chrome on an Android device (Happy Path).	The user is switched to the PayPal app, and after completing the checkout flow, the user is switched to the same merchant browser tab they initially used.
User starts from a Non-Native default browser such as Chrome on iOS or Firefox on Android.	The user is App switched to the PayPal app, and after completing the checkout flow, the user is switched back to the user's default browser.
Post App Switch changes the payment method on the pay sheet and completes the flow.	Completing checkout flow with the successful creation of BA token or payment token.
Post Login cancel the operation on the pay sheet screen in the PayPal App.	The user is switched back to the merchant browser upon canceling out of the checkout flow.
Add a new card.	When users select Add Card, they will be prompted to log in again. After logging in, the new card form will be displayed. After the new card is added, the user can proceed with checkout.

Preconditions

Long-lived session or remember me flow
Face ID or Biometric

Log in to your PayPal app. On the home screen, select the avatar icon.
On the Personal account screen, select the Login and security option.
The Login and security screen should show the face ID or fingerprint and Extend your login sessions options disabled.
Select the toggle icon to enable each login method.

Test on iOS

Download TestFlight from the App Store.
Open Join the PayPal - Pay, Send, Save beta on your device.
Select View in TestFlight and select Open.
Select Install or choose Update for an existing build. This build will become unavailable after 90 days.

If you have the production version of the PayPal app installed, you will get a prompt stating that you already have the app installed. Select Install to replace it with the TestFlight build.

Test on Android

Open the Firebase App Distribution site to join the tester program.
Enter your email address to receive an invite.
To confirm your access, open the invite email on a device.
Select Get Started on your device after opening the invite email.
Check the consent box to agree to Firebase testing and select Accept Invitation. You now have access to the tester portal.
Select Download next to the latest build in the list.
After the download is complete, open the build. You can also find the file in your device notifications or in your downloads folder in the Files app.
Select Install when prompted to download the PayPal app.
If you see Update instead of Install, the PayPal app is already installed on your device. Select Cancel and uninstall the PayPal app before proceeding.
Select Open to access the PayPal app.
Log in using the email address provided in the invite. Your device now has the sandbox version of the PayPal app.

Select the Download App Tester button to ensure you receive notifications when new versions of the sandbox app are available.

After you complete the integration, contact your PayPal support team to enable App Switch for production traffic.

App Switch: JavaScript SDK one-time payments

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

App Switch: JavaScript SDK one-time payments

On this page

On this page