App Switch

CurrentDocs

Last updated: Apr 21st, 1:54pm

This feature is currently in beta. Testing will be available starting May 2025.

Overview

App Switch allows PayPal customers to 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 and 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

Available for buyers and sellers in the United States only.

Available for one-time payments and vaulted payments flows only.

Must be integrated using PayPal JavaScript SDK v5 integration on the client side and either an Orders v2 or Payment Method Tokens v3 REST API integration on the server side.

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

actions.restart()

onShippingChange, onShippingAddressChange, onShippingOptionsChange

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

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: App Switch will be blocked if the JavaScript SDK is running inside an iframe.

Integrate server-side

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

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.

The return_url and cancel_url must:

Be the same.

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

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

Not contain any hash value at the end.

Create order with App Switch
Response

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: YOUR_PAYPAL_REQUEST_ID' \
4-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
5-d '{
6  "intent": "CAPTURE",
7  "payment_source": {
8    "paypal": {
9      "email_address": "customer@example.com",                            
10        "experience_context": {
11          "user_action": "PAY_NOW",
12          "return_url": "https://example.com/merchant_app_universal_link",
13          "cancel_url": "https://example.com/merchant_app_universal_link",
14          "app_switch_preference": {
15            "launch_paypal_app": true
16            }
17        }
18    }
19  },
20  "purchase_units": [
21      {
22        "amount": {
23          "currency_code": "USD",
24          "value": "64.00"
25        }
26    }
27]
28}'

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.

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

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.

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

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.

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 application helps PayPal users, both inside and outside the United States, to test the app switch consumer experience.

Who is this solution intended for?

This solution is available for your development team internationally.

Use cases that can be tested

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

Enable login methods with JavaScripst, iOS, and Android

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.

Note: 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.

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