App Switch

CurrentDocs

Last updated: Feb 27th, 2:18pm

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

You'll need access to the TestFlight PayPal Sandbox app to test this flow in the sandbox.

To request access to the TestFlight PayPal Sandbox app, contact app-switch-onboarding@paypal.com.

Remove the production PayPal app from your device to complete the App Switch flow in the sandbox.

You can test App Switch in both the PayPal production and sandbox environments as long as your integration is eligible and you have integrated App Switch.

To test your App Switch integration in the production environment, download the PayPal app from the App Store or Google Play.