PayPal payments with single-page applications

CurrentDocs

Last updated: Feb 4th, 3:31pm

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

App Switch:

  • Is available for buyers and merchants in the United States only.
  • Requires a PayPal JavaScript SDK v5 integration on the client side.
  • Requires either an Orders v2 or Payment Method Tokens v3 REST API integration on the server side.
  • Is only available for one-time payments and recurring payments.

Buyer flow

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

  1. The buyer selects the PayPal button from another app or website.
  2. The PayPal app opens and uses biometrics or a passkey to log the buyer in.
  3. The buyer reviews purchase details and completes the transaction in the PayPal app.
  4. 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:

  1. Use the server-side create Order API request to configure App Switch.
  2. 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.
  1. Create order with App Switch
  2. 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:

  1. Add the App Switch flag to the PayPal button setup.
  2. 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}