App Switch: Direct API Vaulting without purchase

Last updated: Jul 17th, 1:10pm

Overview

Vaulting helps securely save a payer’s PayPal wallet, with the payer’s consent, for future use. PayPal Vault issues a tokenized version of a payment method such as a card or PayPal wallet that you can safely reuse for recurring or future purchases.

You do not need a transaction to save payment methods with the Payment Method Tokens API. You can charge payers later, even if they are not present. For example, you can offer a free trial and charge the payer after the trial ends.

With App Switch, payers save their PayPal Wallet for future use on the merchant app or mobile website seamlessly. App Switch streamlines the approval process by allowing payers to authenticate through the PayPal app Long Lived Session (LLS), biometrics, and multi-factor authentication.

When App Switch isn't available, payers use the current approval experience in the merchant app or mobile web.

This is a standalone API integration that manages the payer's interaction between the app or website and the PayPal app. The approval flow depends on where the payer starts and how the integration handles the payer's redirect back from the PayPal app.

This App Switch integration is currently only supported for US merchants and buyers.

Know before you code

Before saving payment methods, enable Vault, PayPal, and Venmo in your app settings and ensure the account is approved for saving PayPal payment methods.

In the REST API apps, select your app name.

Navigate toSandbox App Settings or Live App Settings and enable:
- Vault under Accept payments.
- PayPal and Venmo under Accept payments.

In your PayPal account settings, verify that your account status shows Approved for PayPal Wallet vaulting.

Prerequisites

Before beginning integration, meet these requirements:

For merchants:

Complete the Get Started guide to obtain sandbox test credentials for both payer and business sandbox accounts.

Obtain approval for billing agreements if you plan to use reference transactions.

Configure API credentials for client ID and secret.

Enable the Vault feature in PayPal Developer Dashboard.

Set up HTTPS-enabled return and cancel URLs.

For payers:

Active PayPal account

App Switch Vault flow

Payers can initiate App Switch in a couple of ways:

The payer is on the native merchant app and switches to the PayPal consumer app to review and approve saving of the PayPal Wallet in merchant's vault.

The payer is on the merchant website on a mobile browser and switches to the PayPal consumer app to review and approve saving of the PayPal Wallet in merchant's vault.

When the payer takes an action in the PayPal app, PayPal returns the payer to the merchant in one of the following ways:

If the payer starts in the merchant app, the PayPal app automatically redirects them back to the merchant app.

If the payer starts on the merchant website, the merchant can choose to redirect the payer automatically or require a manual redirect. For a manual redirect, the payer follows instructions in the PayPal app to return to the merchant website.

Best practices

If you encounter a server-side timeout during the Create Setup Token call and need to retry, use the same idempotency key. This ensures the setup token remains the same. Avoid creating a new Setup Token.

Configure App Switch for native apps and mobile web browsers. Make sure you validate and set up context-specific options as described in the Platform flow requirements section.

Post the Create Setup Token call after the payer selects the PayPal button. Apply this guidance to all PayPal-bound vault approval calls, including those that use App Switch.

When the payer selects the PayPal button on your page:

Disable the button to prevent multiple clicks while the user stays on the same screen.

Re-enable the button if the user navigates away from your app and then returns.

Unsupported integrations

Avoid opting in for App Switch in the following situations:

App Switch supports only mobile devices, including mobile apps and mobile websites. App Switch does not support desktop devices and tablets.

The merchant app approval experience is hosted in a web view, or a third-party app hosts the merchant website in a web view. Using App Switch in this scenario may cause unexpected redirects, browser launches, or app installation prompts.

The approval experience is embedded in an iFrame. Like web views, iFrames handle links differently and can result in an undesired payer experience when you use App Switch.

The approval experience is hosted with Safari View Controller or Chrome Custom Tabs. These components open web content in a browser tab that mimics the app's appearance but does not fully support App Switch.

Integrate App Switch

Enable App Switch for successful integration to support the payer's intent to save PayPal as the payment method in the vault.

Configure App Switch using the server-side Create Setup Token API request.

Gather specific information from your system and include it in the Create Setup Token API as part of your App Switch request to enable seamless payer approval flow.

To successfully handle App Switch flows originating from either a native app or a mobile web browser, implement careful validation and context-specific configuration steps, as detailed in the guide below.

Redirect the payer to approve, and send your payer to the PayPal approval URL from the response.

After they approve, convert that setup token to a reusable payment method.

Use a vaulted payment method token for a purchase. Payers can complete purchases using their saved PayPal Wallet without re-entering payment details.

Integrate merchant native mobile app

The payer starts in the merchant's native app and switches to the PayPal app to complete the approval flow. After completing the approval, PayPal redirects the payer back to the merchant app.

App Switch scenarios

When the merchant passes app_switch_context, the payer starts in the native merchant app, switches to the PayPal app to complete the approval flow, and is automatically redirected back to the merchant app.

If the merchant passes app_switch_context but the app switch to the PayPal app fails, the payer switches to their default browser, where the PayPal pay sheet loads. After completing the approval, the payer returns to the merchant app.

If the merchant does not pass app_switch_context or PayPal sets app_switch_eligibility to false, the payer completes the approval using the current experience without switching to the PayPal app.

Native app prerequisites

For traffic from your native app, complete several checks before you pass the app_switch_context parameter to PayPal.

Passing app_switch_context means you are opting in to App Switch behavior.

For Android devices, ensure the payer has enabled Open supported links for your merchant app. When PayPal redirects the payer to your app using app links, the payer lands on your mobile website instead of your app if Open supported links is not enabled.

If supported links are not enabled, we recommend that you do not pass the app_switch_context parameter. In the following code, the app checks whether supported links are enabled for your Android app.

The following code sample determines whether to opt in or out of App Switch behavior.

1// Kotlin
2fun hasEnabledSupportedLinks(context: Context): Boolean {
3    val intent = Intent(Intent.ACTION_VIEW, app_link_return_uri).apply {
4        addCategory(Intent.CATEGORY_BROWSABLE)
5    }
6    val resolvedActivity = context.packageManager.resolveActivity(intent, PackageManager.MATCH_DEFAULT_ONLY)
7    return if (resolvedActivity?.activityInfo?.packageName == context.packageName) {
8        // Open Supported Links for my native app enabled
9        // i.e. can return to this app via AppLinks invoked by PayPal
10        // opt-in to app switch
11        true
12    } else {
13        // Open Supported Links for my native app disabled
14        // i.e. cannot return to this app via AppLinks invoked by PayPal
15        // opt-out from app switch
16        false
17    }
18}

Ensure the payer has the PayPal app installed on their mobile device. Enabling App Switch without this check prevents the switch to the PayPal app. Instead, the PayPal approval experience opens in a browser, not within the merchant app. We recommend passing the app_switch_context parameter only if the PayPal app is installed.

Register the URL scheme in the Info.plist file. The following sample code checks if the PayPal app is installed on an iOS device. The following sample code checks if the PayPal app is installed on an iOS or Android device.

iOS
Android

1// Swift 
2public func isPayPalAppInstalled() -> Bool {
3    guard let payPalURL = URL(string: "paypal-app-switch://") else {
4        return false
5    }
6    return UIApplication.shared.canOpenURL(payPalURL)
7}

Register the packageName in the AndroidManifest file. The following sample checks if the PayPal app is installed on the device.

1// Kotlin
2<manifest xmlns:android="http://schemas.android.com/apk/res/android">
3
4    <queries>
5        <package android:name="com.paypal.android.p2pmobile" />
6    </queries>
7...
8</manifest>

Payment Method API integration

The Payment Method API enables secure integration with PayPal's vaulting system, allowing merchants to save customer payment methods for future transactions.

Use cases

The App Switch vaulting integration supports several key scenarios where users want to save payment methods without immediate purchases. See the primary use cases.

Use case 1: Save payment method during onboarding

Let users save their PayPal Wallet during onboarding or account setup without making a purchase, so they don't have to re-enter it later when making a purchase.

Payers trigger this intent when they want to securely store a payment method, even though they're not checking out. This commonly occurs during sign-up flows and when payers create accounts with billing preferences.

Intent	Example user phrases
`vault_paypal_payment_method`	“Save my PayPal for later.” “Set up my wallet for subscriptions.” “I don’t want to enter this again next time.”

Use case 2: Purchase with saved payment method

Payers can complete purchases using their saved PayPal Wallet without re-entering payment details.

Intent	Example user phrases
`vault_paypal_payment_method`	"Use my saved PayPal for this purchase" "Pay with my stored wallet" "Use my default payment method"

Visual flow summary

The App Switch vaulting integration follows a five-step process from token creation to payment processing.

Create a setup token → POST /v3/vault/setup-tokens

Redirect to approval → links[].rel = approve

Payer approves

Create payment token → POST /v3/vault/payment-tokens

Use the token with purchase → POST /v2/checkout/orders

Integration flow summary

This vaulting flow helps payers consent to saving a payment method.

Intent	API endpoint	Expected outcome	Next step
`vault_paypal_payment_method`	`POST /v3/vault/setup-tokens`	Creates a `setup_token` and approval URL for App Switch.	Redirect the payer to `links[].approve.href`.
Implicit	Off-platform redirect	Payer grants approval to vault method.	Convert the setup token to a payment method token.
`create_payment_token`	`POST /v3/vault/payment-tokens`	Returns `payment_token` and saves method metadata.	Store the token securely, and display confirmation.

Create setup token

Create a setup token using the POST /v3/vault/setup-tokens endpoint. This generates a setup token and approval URL that helps the payer authenticate and approve vaulting their payment method.

This creates a setup token and an approval URL. The payer must authenticate and approve vaulting.

The initial POST on setup-tokens completes the following actions:

Returns a PAYER_ACTION_REQUIRED status.

Creates a temporary setup token.

Redirects to the approve URL.

Update app_switch_context for the native app.

When saving a payer's PayPal Wallet for the first time, the response returns the PayPal-generated customer.id and setup_token_id.

For payers with previously stored payment_sources, pass the customer.id in the setup-token request. This links additional payment_sources to the payer.

Store a merchant_customer_id aligned with the system to simplify the mapping customer information between the system and PayPal when creating a setup token. This optional field returns the value shared in the response.

Include the following parameters in the Create Setup Token API request: payment_source.paypal and payment_source.paypal.experience_context.

Parameter	Description	Priority
`payment_source.paypal.email_address`	Merchants can pass the payer's email in the setup token-creation request, which can be the same email used in the merchant's application. Including the email address helps us determine if the payer has a PayPal account and whether the app is installed, allowing for a quicker assessment of App Switch eligibility and enhancing the payer experience.	Optional
`payment_source.paypal.experience_context.user_action`	The `user_action` configures the PayPal Approval flow and uses the `SETUP_NOW` flow. App Switch currently only supports `SETUP_NOW` flows. `SETUP_NOW` is a PayPal feature that supports payers to approve and save the agreement on the PayPal review page.	Mandatory

Return and cancel URLs

PayPal expects the merchant to pass payment_source.paypal.experience_context.return_url and payment_source.paypal.experience_context.cancel_url:

return_url is the URL that tells PayPal where to send the payer after completing the approval on the PayPal app. Set the URL to the page where the payer selects the PayPal button. (Mandatory)

cancel_url is the URL that tells PayPal where to send the payer when the payer cancels or doesn't complete the approval on the PayPal app. Set the URL to the page where the payer should be redirected when they cancel the approval flow. (Mandatory)

Use Mandatory requirements

Merchant native apps

The return_url and cancel_url must be associated with the merchant app.

If the merchant app supports iOS v17.4 and earlier and uses ASWebAuthenticationSession, pass deep links in the return_url and cancel_url fields. Otherwise, the payer won't return to the app as expected.

Include the app_url parameter. (Mandatory) This takes precedence over return_url and cancel_url.

If PayPal determines the App Switch is eligible, we use the app_url to return the payer to the merchant app. If not, we use the return_url and cancel_url.

Opt into App Switch

PayPal considers passing payment_source.paypal.experience_context.app_switch_context as the merchant opting in to App Switch.

Native app parameters

If a payer starts from the native app, use payment_source.paypal.experience_context.app_switch_context.native_app.

Field	Requirement	Priority
`os_type`	The payer’s mobile operating system (OS) family. PayPal uses this value to assess App Switch eligibility. Accepted values: `ANDROID`, `IOS`, and `OTHER`.	Mandatory
`os_version`	The payer’s mobile OS version used for telemetry	Optional
`app_url`	Pass `app_url` as the universal link or app link associated with the merchant app. After the payer uses App Switch to approve or cancel the approval in the PayPal app, PayPal uses this URL to redirect the payer back to the merchant app. During an App Switch flow, `app_url` takes precedence over `return_url` and `cancel_url`.	Mandatory

The following code sample shows how to derive the payer’s os_type and os_version needed to include in the Create Setup Token API request.

1function parseMobileOS(userAgent) {
2  const os = {
3    name: "Unknown",
4    version: "Unknown"
5  };
6
7  const osPatterns = [
8    // iOS
9    { regex: /iPhone|iPad|iPod.*OS (\d+[_\.]\d+)/, name: "iOS", versionIndex: 1 },
10
11    // Android
12    { regex: /Android (\d+\.\d+)/, name: "Android", versionIndex: 1 },
13
14    // Windows Phone (older devices)
15    { regex: /Windows Phone (\d+\.\d+)/, name: "Windows Phone", versionIndex: 1 },
16
17    // Windows 10 Mobile
18    { regex: /Windows NT 10.0.*Mobile/, name: "Windows 10 Mobile", version: "10" },
19
20    // Other mobile OS
21    { regex: /Linux.*(Ubuntu)/, name: "Ubuntu", version: "Unknown" },
22    { regex: /Linux/, name: "Linux", version: "Unknown" }
23  ];
24
25  for (const pattern of osPatterns) {
26    const match = userAgent.match(pattern.regex);
27    if (match) {
28      os.name = pattern.name;
29      if (pattern.version) {
30        os.version = pattern.version;
31      } else if (pattern.versionIndex && match[pattern.versionIndex]) {
32        os.version = match[pattern.versionIndex].replace("_", ".");
33      }
34      break;  // Once we match, no need to check further
35    }
36  }
37
38  return os;
39}
40
41// Example usage:
42const userAgent = navigator.userAgent;  // Automatically gets the user's device info
43const os = parseMobileOS(userAgent);
44console.log(`OS: ${os.name}, Version: ${os.version}`);

Sample setup token API request

The following sample code shows a create setup token request with App Switch opt-in for a merchant native app.

1# x-function-name": "vault_paypal_payment_method"
2# x-intent": "vault.save_paypal_payment_method"
3curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
4  -H "Content-Type: application/json" \
5  -H "Authorization: Bearer ACCESS-TOKEN" \
6  -H "PayPal-Request-Id: REQUEST-ID" \
7  -d '{
8    "payment_source": {
9      "paypal": {
10        "description": "Save your PayPal account for faster checkout",
11        "shipping": {
12          "name": {
13            "full_name": "Firstname Lastname"
14          },
15          "address": {
16            "address_line_1": "2211 N First Street",
17            "address_line_2": "Building 17",
18            "admin_area_2": "San Jose",
19            "admin_area_1": "CA",
20            "postal_code": "95131",
21            "country_code": "US"
22          }
23        },
24        "permit_multiple_payment_tokens": false,
25        "usage_pattern": "IMMEDIATE",
26        "usage_type": "MERCHANT",
27        "customer_type": "CONSUMER",
28        "experience_context": {
29          "user_action": "SETUP_NOW",
30          "shipping_preference": "SET_PROVIDED_ADDRESS",
31          "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
32          "brand_name": "EXAMPLE INC",
33          "locale": "en-US",
34          "return_url": "app://xo/234?clientStatus=success",
35          "cancel_url": "app://xo/234?clientStatus=cancel",
36          "app_switch_context": {
37            "native_app": {
38              "os_type": "IOS",
39              "os_version": "17.3.1",
40              "app_url": "https://example.com/merchant_app_universal_link"
41            }
42          }
43        }
44      }
45    }
46  }'

Modify the code

Copy the code sample.

Replace ACCESS-TOKEN with the sandbox access token.

Replace REQUEST-ID with unique alphanumeric characters, such as a timestamp.

Configure PayPal as the payment_source and complete the remaining source object properties for the use case.

Set the return_url value to the URL that redirects users after they approve the flow.

Set the cancel_url value to the URL that redirects users after they cancel the flow.

Configure the app_switch_context parameters for native app.

Setup token response

A successful request returns an HTTP response code of 200 or 201 and a status of PAYER_ACTION_REQUIRED. Returns 200 for idempotent requests.

In the Setup Token response, the app_switch_eligibility flag is set to true. This flag indicates that the information in the Setup Token request is correct and that PayPal has found the payer eligible. The merchant should attempt to App Switch.

app_switch_eligibility = true does not guarantee that the payer will switch to the PayPal app. It only indicates that PayPal requests the merchant to attempt App Switch for the payer.

The response includes the following HATEOAS links:

Rel	Method	Description
`approve`	GET	Use this link to take the payer through a PayPal-hosted approval flow.
`confirm`	POST	Make a POST request to use an approved setup token to save the PayPal Wallet and generate a payment token.
`self`	GET	Make a GET request to view the state of the setup token and payment method details.

The following sample code includes the setup token ID, customer information, payment source details, and links to approve the vaulting request.

1{
2    "id": "5C991763VB2771612",
3    "customer": {
4        "id": "customer_4029352051",
5        "merchant_customer_id": "merchant_cust_ID"
6    },
7    "status": "PAYER_ACTION_REQUIRED",
8    "payment_source": {
9        "paypal": {
10            "email_address": "customer@example.com",
11            "usage_pattern": "RECURRING_PREPAID",
12            "shipping": {
13                "name": {
14                    "full_name": "John Doe"
15                },
16                "address": {
17                    "address_line_1": "2211 N First Street",
18                    "address_line_2": "Building 17",
19                    "admin_area_2": "San Jose",
20                    "admin_area_1": "CA",
21                    "postal_code": "95131",
22                    "country_code": "US"
23                }
24            },
25            "permit_multiple_payment_tokens": false,
26            "usage_type": "MERCHANT",
27            "customer_type": "CONSUMER",
28            "app_switch_eligibility": true,
29            "experience_status": "CANCELED"
30        }
31    },
32    "links": [
33        {
34            "href": "https://api.sandbox.paypal.com/v3/vault/setup-tokens/1VH10267W9768550E",
35            "rel": "self",
36            "method": "GET",
37            "encType": "application/json"
38        },
39        {
40            "href": "https://www.sandbox.paypal.com/checkoutnow?token=1VH10267W9768550E",
41            "rel": "approve",
42            "method": "GET",
43            "encType": "application/json"
44        }
45    ]
46}

Setup token lifecycle

Token type	Status	Description	Agent action
Setup_token	`CREATED`	Initial token created.	No action required.
Setup_token	`PAYER_ACTION_REQUIRED`	Awaiting payer approval.	Redirect the payer to PayPal approval URL.
Setup_token	`APPROVED`	Payer completed approval.	Call `POST /v3/vault/payment-tokens`.
Setup_token	`TOKENIZED`	Payment token created successfully.	Store the token securely for future use.
Setup_token	`VAULTED`	Payment method is stored in the vault.	Ready for future transactions.

Redirect the payer to the approve link to begin the approval process.

After the payer completes the approval flow, upgrade the setup token to a payment method token by calling the create payment tokens endpoint. Setup tokens expire after 3 days by default.

Sample GET response

In the GET setup-token response, PayPal returns the app_switch_eligibility flag.

When payers cancel the transaction in the PayPal app before approval, the GET order response includes a cancellation status with experience_status = CANCELED. Use this information to control the cancel flow and determine what to display when payers cancel PayPal approval. This applies when return_flow is set to MANUAL.

The experience_status flag indicates the current state of the PayPal checkout. This flag does not replace the setup token status but helps identify if payers canceled the approval process at any point.

After payer cancellation, PayPal returns this information in the GET /v3/vault/setup-tokens/{id} response.

The following code sample shows a canceled approval.

1{
2    "id": "5C991763VB2771612",
3    "customer": {
4        "id": "customer_4029352051",
5        "merchant_customer_id": "merchant_cust_ID"
6    },
7    "status": "PAYER_ACTION_REQUIRED",
8    "payment_source": {
9        "paypal": {
10            "email_address": "customer@example.com",
11            "app_switch_eligibility": true,
12            "experience_status": "CANCELED"
13        }
14    },
15    "links": [
16        {
17            "href": "https://www.sandbox.paypal.com/checkoutnow?token=1VH10267W9768550E",
18            "rel": "approve",
19            "method": "GET",
20            "encType": "application/json"
21        },
22        {
23            "href": "https://api-m.paypal.com/v3/vault/payment-token",
24            "rel": "confirm",
25            "method": "POST",
26            "encType": "application/json"
27        },
28        {
29            "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
30            "rel": "self",
31            "method": "GET",
32            "encType": "application/json"
33        }
34    ]
35}

App Switch to and from PayPal

If the merchant opts in to App Switch and passes the app_switch_context, and the PayPal app is installed with app_switch_eligibility = true, the merchant should attempt to switch to the PayPal app.

The following code sample shows how to make the switch.

1// Swift
2UIApplication.shared.open(url, options: [:], completionHandler: nil)

If the OS cannot open the PayPal app or the app is not installed, the URL can open in a browser. The following sample code shows how to handle this scenario.

1// Kotlin
2fun launchUrl(context: Context, url: Uri, launchAsNewTask: Boolean) {
3    try {
4        val customTabsIntent: CustomTabsIntent = CustomTabsIntent.Builder().build()
5        if (launchAsNewTask) {
6            customTabsIntent.intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
7        }
8        customTabsIntent.launchUrl(context, url)
9    } catch (e: ActivityNotFoundException) {
10        if (hasEnabledSupportedLinks(context)) {
11            val intent = Intent(Intent.ACTION_VIEW).apply {
12                    data = url
13                }
14            startActivity(intent)
15        } else {
16            // Cannot switch to PayPal app, cannot open fallback into custom tabs, cannot return from browser
17            // Gracefully handle error
18        }
19    }
20}

See the following sample code to handle the return to the merchant app.

1override fun onNewIntent(intent: Intent) {
2    super.onNewIntent(intent)
3    
4}

Add a custom tabs dependency to your build.gradle file if needed.

1// kotlin
2dependencies {
3...
4  implementation("androidx.browser:browser:1.8.0")
5...
6}

If the merchant opts in to App Switch, passes the app_switch_context, and PayPal returns app_switch_eligibility = false, the merchant can open the approval in the native app so the payer can complete the approval. Handle this the same way as the existing non-App Switch integration.

If the payer manually navigates back to the merchant app without taking action in the PayPal app, or if they leave the PayPal app, the merchant should be prepared to handle these situations appropriately.

The following code samples show how to open the approval experience in the merchant’s native app.

iOS
Android

1// Swift 
2DispatchQueue.main.async {
3	let callbackURLScheme = //your app scheme
4    let webAuthSession = ASWebAuthenticationSession(url: url, callbackURLScheme: callbackURLScheme) { [weak self] callbackURL, error in
5        DispatchQueue.main.async {
6            if let callbackURL  {
7              // handle return
8            } else if let error {
9              // error returned, can be cancel or an error
10            }
11        }
12    }
13    session.presentationContextProvider = self
14    session.start()
15}

Integrate merchant website mobile browser

When a payer uses a mobile browser to access the merchant's website and switches to the PayPal app to complete the approval, the app redirects them to the merchant's site or requires them to return manually.

Create a setup token using the PayPal API after completing the native app prerequisites.

Create a setup token

Create a setup token using the POST /v3/vault/setup-tokens endpoint. This generates a setup token and approval URL that helps the payer authenticate and approve vaulting their payment method.

The initial POST on setup-tokens completes the following actions:

Returns a PAYER_ACTION_REQUIRED status.

Creates a temporary setup token.

Redirects to the approve URL.

Update app_switch_context for the native app.

When you save a payer's PayPal Wallet for the first time, the response returns the PayPal-generated customer.id and setup_token_id.

For payers with previously stored payment_sources, pass the customer.id in the setup-token request. This links additional payment_sources to the payer.

You can store a merchant_customer_id aligned with your system to simplify the mapping customer information between the system and PayPal when creating a setup token. This optional field returns the value shared in the response.

Include the following parameters in the Create Setup Token API request: payment_source.paypal and payment_source.paypal.experience_context.

Parameter	Description	Priority
`payment_source.paypal.email_address`	Merchants can pass the payer's email in the order-creation request, which can be the same email used in the merchant's application. Including the email address helps us determine if the payer has a PayPal account and whether the app is installed, allowing for a quicker assessment of App Switch eligibility and enhancing the payer experience.	Optional
`payment_source.paypal.experience_context.user_action`	The user_action configures the PayPal Approval flow and uses the `SETUP_NOW` flow. App Switch currently only supports `SETUP_NOW` flows. `SETUP_NOW` is a PayPal feature that supports payers to approve and save the agreement on the PayPal review page.	Mandatory

Return and cancel URLs

PayPal expects the merchant to pass payment_source.paypal.experience_context.return_url and payment_source.paypal.experience_context.cancel_url:

return_url is the URL that tells PayPal where to send the payer after completing the approval on the PayPal app. Set the URL to the page where the payer selects the PayPal button. (Mandatory)

cancel_url is the URL that tells PayPal where to send the payer when the payer cancels or doesn't complete the approval on the PayPal app. Set the URL to the page where the payer should be redirected when they cancel the approval. (Mandatory)

Use Mandatory requirements

Merchant mobile website

Set the return_url and cancel_url to the same value. If the URLs are different, PayPal redirects the payer to the merchant website on a different tab or browser.

The return_url and cancel_url must be web URLs linked to the website where the payer clicked the PayPal button.

If you want to pass query parameters to PayPal that you expect PayPal to return, add the query parameters to the return_url and cancel_url as fragments after the #.

Use a unique identifier for each payer’s session, so you recognize the payer when PayPal redirects them to your website.

Opt into App Switch

PayPal considers passing payment_source.paypal.experience_context.app_switch_context as the merchant opting in to App Switch.

Mobile web parameters

If a payer starts from the merchant mobile website, use payment_source.paypal.experience_context.app_switch_context.mobile_web.

Field Requirement Priority

buyer_user_agent

Pass this field as a raw string without any modifications. PayPal derives the payer's device OS type, OS version, and browser details from this value.

Do not alter or modify the payer's device user agent string. Send it to PayPal as is.

Mandatory

return_flow

The return_flow field defines how payers return to the merchant's website after approving the agreement in the PayPal app. For approvals that start on the merchant's website in a mobile browser, the return experience to the merchant's site depends on the merchant's preferences and technical setup.

Accepted Values:

AUTO: After the payer approves the agreement in the PayPal app, PayPal automatically redirects them to the merchant's website.

MANUAL: After the payer approves the agreement in the PayPal app, they must manually navigate back to the merchant's website where they started the payment.

Mandatory

Create setup token request

Use the following code sample to create a setup token for PayPal vaulting with App Switch configuration for mobile web.

1# x-function-name": "vault_paypal_payment_method"
2# x-intent": "vault.save_paypal_payment_method"
3curl -v -k -X POST 'https: //api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
4-H "Content-Type: application/json" \
5-H "Authorization: Bearer ACCESS-TOKEN" \
6-H "PayPal-Request-Id: REQUEST-ID" \
7-d '{
8    "payment_source": {
9        "paypal": {
10            "description": "Save your PayPal account for faster checkout",
11            "shipping": {
12                "name": {
13                    "full_name": "Firstname Lastname"
14                },
15                "address": {
16                    "address_line_1": "2211 N First Street",
17                    "address_line_2": "Building 17",
18                    "admin_area_2": "San Jose",
19                    "admin_area_1": "CA",
20                    "postal_code": "95131",
21                    "country_code": "US"
22                }
23            },
24            "permit_multiple_payment_tokens": false,
25            "usage_pattern": "IMMEDIATE", 
26            "usage_type": "MERCHANT", 
27            "customer_type": "CONSUMER", 
28            "experience_context": {
29                "user_action": "SETUP_NOW",
30                "shipping_preference": "SET_PROVIDED_ADDRESS", 
31                "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED", 
32                "brand_name": "EXAMPLE INC",
33                "locale": "en-US",
34                "return_url": "https://example.com/merchant_app_universal_link",
35                "cancel_url": "https://example.com/merchant_app_universal_link",
36                "app_switch_context": {
37                    "mobile_web": {
38                        "return_flow": "AUTO" or "MANUAL",
39                        "buyer_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.4 Mobile/15E148 Safari/604.1"
40                    }
41                }
42            }
43        }
44    }

Create setup token response

In the Create setup token response, the app_switch_eligibility flag is set to true. This flag indicates that the information in the Create Setup Token request is correct, and that PayPal has found the payer eligible and is attempting to use App Switch.

app_switch_eligibility = true does not guarantee that the payer will successfully switch to the PayPal app. It only indicates that PayPal is attempting App Switch for the payer. PayPal returns the payer_id in the response when a payer approves saving of the PayPal Wallet.

1{
2    "id": "5C991763VB2771612",
3    "customer": {
4        "id": "customer_4029352051", 
5        "merchant_customer_id": "merchant_cust_ID"
6    },
7    "status": "PAYER_ACTION_REQUIRED", 
8    "payment_source": {
9        "paypal": {
10            "email_address": "customer@example.com",
11            "usage_pattern": "RECURRING_PREPAID",
12            "shipping": {
13                "name": {
14                    "full_name": "John Doe"
15                },
16                "address": {
17                    "address_line_1": "2211 N First Street",
18                    "address_line_2": "Building 17",
19                    "admin_area_2": "San Jose",
20                    "admin_area_1": "CA",
21                    "postal_code": "95131",
22                    "country_code": "US"
23                }
24            },
25            "permit_multiple_payment_tokens": false,
26            "usage_type": "MERCHANT",
27            "customer_type": "CONSUMER",
28            "app_switch_eligibility": true,
29            "experience_status": "CANCELED"
30        }
31    },
32    "links": [
33        {
34            "href": "https://api.sandbox.paypal.com/v3/vault/setup-tokens/1VH10267W9768550E",
35            "rel": "self",
36            "method": "GET",
37            "encType": "application/json"
38        },
39        {
40            "href": "https://www.sandbox.paypal.com/checkoutnow?token=1VH10267W9768550E",
41            "rel": "approve",
42            "method": "GET",
43            "encType": "application/json"
44        }
45    ]
46}

Setup token lifecycle

Token type	Status	Description	Agent action
Setup_token	`CREATED`	Initial token created.	No action required.
Setup_token	`PAYER_ACTION_REQUIRED`	Awaiting payer approval.	Redirect the payer to PayPal approval URL.
Setup_token	`APPROVED`	Payer completed approval.	Call `POST /v3/vault/payment-tokens`.
Setup_token	`TOKENIZED`	Payment token created successfully.	Store the token securely for future use.
Setup_token	`VAULTED`	Payment method is stored in the vault.	Ready for future transactions.

Redirect the payer to the approve link to begin the approval process. After the payer completes the approval flow, upgrade the setup token to a payment method token by calling the create payment tokens endpoint. Setup tokens expire after 3 days by default.

Sample GET response

In the GET setup-token response, PayPal returns the app_switch_eligibility flag.

If the payer cancels in the PayPal app during the approval process, the GET setup-token response includes a cancellation status, indicated by experience_status = CANCELED. Use this information to control the cancel flow and determine what to display when the payer cancels PayPal approval. This is relevant when return_flow is set to MANUAL.

The experience_status flag indicates the current state of the PayPal checkout. It does not replace the setup token status, but helps identify if the payer canceled the approval process at any point.

PayPal returns this information in the GET /v3/vault/setup-tokens/{id} response after payer cancellation. The following code sample shows a canceled approval.

1{
2 "id": "5C991763VB2771612", // setup_token ID
3    "customer": {
4        "id": "customer_4029352051", //Your PayPal generated reference to the buyer
5        "merchant_customer_id": "merchant_cust_ID"
6    },
7    "status": "PAYER_ACTION_REQUIRED", // enum: CREATED, PAYER_ACTION_REQUIRED, APPROVED, VAULTED,TOKENIZED
8  "payment_source": {
9    "paypal": {
10            "email_address": "customer@example.com",
11            "app_switch_eligibility": true,
12           "experience_status":"CANCELED"
13        }
14  },
15  "links": [
16    {
17      "href": "https://www.sandbox.paypal.com/checkoutnow?token=1VH10267W9768550E",
18      "rel": "approve",
19      "method": "GET",
20      "encType": "application/json"
21    },
22    {
23      "href": "https://api-m.paypal.com/v3/vault/payment-token",
24      "rel": "confirm",
25      "method": "POST",
26      "encType": "application/json"
27    },
28    {
29      "href": "https://api-m.paypal.com/v3/vault/setup-tokens/5C991763VB2771612",
30      "rel": "self",
31      "method": "GET",
32      "encType": "application/json"
33    }
34  ]
35}

Redirects to merchant website

The payer's App Switch experience may vary based on the device OS, the default browser, the merchant's preferred return flow, and where the merchant website is hosted. There are technical constraints related to the OS:

When a payer completes the approval flow in the PayPal app and PayPal redirects them back to the merchant's website, the OS opens the site in the payer's default browser.

For example, the payer may start the approval on the merchant website in a non-default browser, such as Chrome on Android. However, due to OS limitations, when PayPal redirects the payer back, the merchant's website opens in the browser set as default on their device, such as Firefox.

Review the following table to see how App Switch works in different settings. Use this information to verify the integration during testing and identify situations that require handling a fallback.

Platform	Browser	Mode	Notes
iOS	Safari	Default browser
iOS	Safari	Private
iOS	Safari	Not default	Dot of the "i" Stem of the "i" App Switch redirects to the default browser
iOS	Chrome	Default browser	Dot of the "i" Stem of the "i" App Switch redirects to a new tab in the same browser
Android	Chrome	Default browser
Android	Chrome	Incognito	Fallback experience
Android	Chrome	Not default	Dot of the "i" Stem of the "i" App Switch redirects in the default browser
Android	Firefox or other	Default	Dot of the "i" Stem of the "i" App Switch redirects to a new tab in the same browser

Handle auto return flow

When the return_flow value is set to AUTO and the payer completes or cancels the approval flow in the PayPal app, PayPal automatically redirects the payer back to the merchant website using the return_url or cancel_url.

To handle the payer’s return and account for these scenarios, the merchant needs to implement the following:

App Switch from a native default browser

A payer starts on the merchant website in a native browser, such as Safari on iOS, and sets the native browser as the default. When the payer completes or cancels the approval, the PayPal app automatically redirects the payer back to the same default browser.

Use the visibilitychange event listener to handle scenarios where the payer abandons the approval.

Include a client-side event listener to identify this event. Use the hashchange listener, and the completion status will be included as additional hash parameters.

The following sample client-side code handles this request.

1document.addEventListener('hashchange', (e) => {
2	const params = parseHashParams(window.location.hash); 
3	if(params.approved) {
4		// Buyer is returning from app switch with an approved setup token
5		// Verify the setup token approval, complete vaulting
6		// & redirect to confirmation page to complete flow
7	} else if (params.canceled) {
8		// Buyer canceled PayPal app switch
9	}
10})

App Switch from a non-default browser

When a payer starts on the merchant website in a browser, such as Safari on iOS, but has Chrome set as the default browser, PayPal redirects the payer back to the merchant’s website in Chrome after they complete or cancel the approval.

Use the visibilitychange event listener to handle cases when the payer abandons checkout.

In this scenario, the payer starts in a non-default browser, completes an action in the PayPal app, and returns to the default browser. Because browsers do not share cookies, use the token that PayPal returns to look up the setup token details, or include the original setup token ID in the approval URL to keep the session and complete the payment.

The PayPal app sends order approval or cancellation details as URL parameters during the redirect. Client-side code can read these parameters, but server-side routes cannot. When approved, PayPal also returns payer_id as a URL parameter during the redirect.

The following code handles the redirects and processes approval data from the URL parameters on the client side.

1const onLoadHash = () => {
2	const hashParams = parseHashParams(window.location.hash);
3	
4	if (hashParams.approved) {
5		// Buyer is returning from app switch
6		// Complete payment method vaulting & redirect to confirmation page
7	} else if (hashParams.canceled) {
8		// Buyer has canceled app switch and returned
9	} else {
10		// No hash params, display standard checkout page
11	}
12}
13onLoadHash()

Handle manual return flow

When the return_flow value is set to MANUAL and the payer completes or cancels the approval in the PayPal app, the app prompts the payer to manually return to the merchant website. Use the visibilitychange event listener to detect when the payer returns to the merchant website.

For additional visibility into payer actions in the PayPal app, check the experience_status in the GET setup token response. When this is approved, PayPal removes experience_status from the GET setup token response.

The visibilitychange event listener also handles scenarios where the payer abandons approval and the return_flow value is AUTO.

If the payer abandons PayPal approval and navigates back to the merchant website, it is not a terminal state. The payer can switch to PayPal again to review and approve the saving of PayPal wallet in the vault.

The following sample code shows how to handle the visibilitychange event listener.

1document.addEventListener('visibilitychange', (e) => {
2	// call your server API to make a request to PayPal to get the setup token status and buyer cancellation status (if applicable)
3	//If #change event was triggered then cancel this event (to avoid multiple GET calls from both the listeners)
4    const hashParams = parseHashParams(window.location.hash);
5	if (hashParams.approved || hashParams.cancelled) {
6		//Wil be handled by hashChange. Exit
7		return;
8	}
9	const vaultResponse = getSetupToken(setuptokenId);
10	const setupTokenStatus = vaultResponse.status;
11	const experiencStatus = vaultResponse?.payment_source?.paypal?.experiencStatus;
12	// Extract only "CANCELLED" status 
13    const cancelledexperiencStatus= paypal.experiencStatus
14                                .filter(item => item.experiencStatus && item.experiencStatus.includes("CANCELLED"))
15                                .map(item => item.experiencStatus);
16	//setupTokenStatus Approved
17	if (setupTokenStatus === 'approved') {
18		// Create the Payment Token 
19	} 
20	//Buyer cancels vaulting
21	else if (setupTokenStatus !== 'approved' && cancelledexperiencStatus == 'cancelled') {
22		// Buyer app switched to paypal but closed before approving the vaulting. 
23		// Dont call create payment token & take the appropriate "cancel" action 
24	}
25	else {
26		// Continue current buyer approval process
27	}
28});

Create payment method token

Redirect the payer to the approve link to begin the approval process.

After the payer completes the approval flow, upgrade the setup token to a payment method token by calling the create payment tokens endpoint. Setup tokens expire after 3 days by default.

After the payer approves the setup token, redirect them to the approve link to complete the approval process.

Use the POST /v3/vault/payment-tokens endpoint to convert the approved setup token into a reusable payment method token, also known as a vault_id. Call this endpoint only after the payer has approved the setup token through the PayPal approval flow.

Request

The following code exchanges an approved setup token for a payment token stored in the vault.

1# x-function-name: convert_payment_token
2# x-intent: vault.create_payment_token
3# description: Exchanges an approved setup token for a payment token stored in the Vault.
4# example_request_comment: |
5#   Step 2 of the vaulting flow.
6#   Only call this after the payer has approved the setup token.
7#   This returns a reusable vault token (e.g., for PayPal Wallet).
8curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens' \
9  -H "Content-Type: application/json" \
10  -H "Authorization: Bearer ACCESS-TOKEN" \
11  -H "PayPal-Request-Id: REQUEST-ID-123" \
12  -d '{
13    "payment_source": {
14      "token": {
15        "id": "4G4976650J0948357", 
16        "type": "SETUP_TOKEN"             
17      }
18    }
19  }'

Use the following parameters in the request.

Field	Type	Description
`payment_source.token.id`	string	Pass the `setup_token` that the payer approved.
`payment_source.token.type`	string	Set this value to `SETUP_TOKEN`.

Expected output

The following JSON sample shows the response structure returned after successfully creating a vault token for a PayPal payment method.

1{
2    "id": "VAULT-TOKEN-XYZ789",
3    "payment_source": {
4        "paypal": {
5            "email": "buyer@example.com",
6            .......
7        }
8    },
9    ...
10}

Next steps

After receiving the response, follow these steps:

Store the returned id securely as the reusable vault token.

Use the vault token in future transactions by passing it as vault_id in /v2/checkout/orders or similar API calls.

Response details

The API response contains the following information.

Field	Value
Function	`convert_payment_token`
Intent	`vault.convert_payment_token`
Outcome	`payment_token_created_successfully`
Description	Convert an approved setup token into a reusable vault token for a PayPal Wallet.

Response payload

This code sample shows the vault token details returned after converting an approved setup token.

1{
2  "id": "jwgvx42",                     
3  "customer": {
4    "id": "customer_4029352051" ,     
5    "merchant_customer_id": "merchant_cust_ID"
6  },
7  "payment_source": {
8    "paypal": {
9      "description": "Description for PayPal to be shown to PayPal payer",
10      "usage_pattern": "IMMEDIATE",   
11      "shipping": {
12        "name": {
13          "full_name": "Firstname Lastname"
14        },
15        "address": {
16          "address_line_1": "2211 N First Street",
17          "address_line_2": "Building 17",
18          "admin_area_2": "San Jose",
19          "admin_area_1": "CA",
20          "postal_code": "95131",
21          "country_code": "US"
22        }
23      },
24      "permit_multiple_payment_tokens": false,
25      "usage_type": "MERCHANT",                 
26      "customer_type": "CONSUMER",             
27      "email_address": "email@example.com",    
28      "payer_id": "AJM9JTWQJCFTA"               
29    }
30  },
31  "links": [
32    {
33      "rel": "self",
34      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
35      "method": "GET",
36      "encType": "application/json",
37    },
38    {
39      "rel": "delete",
40      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
41      "method": "DELETE",
42      "encType": "application/json",
43    }
44  ]
45}

Next steps

After creating the vault token, complete the store_payment_token and customer_id process by following these actions:

Store the token ID jwgvx42 securely for this customer.

Display the masked PayPal email for confirmation.

Use this token as vault_id in /v2/checkout/orders.

Postconditions

Validate these conditions to ensure successful implementation:

Persist the token in your backend.

Prepare the PayPal Wallet token for future checkout.

Configure the token for use as payment_source.paypal.vault_id in checkout.

Use case 3: Mobile browser purchase with saved payment method

After receiving the payment method token ID, use it with the Orders v2 API to create the order with the saved payment method.

Intent	Function name	API endpoint	Expected outcome	Next step
`use_saved_payment`	`create_order_with_vaulted_paypal_wallet`	`POST /v2/checkout/orders`	Creates an order using a previously vaulted `payment method token`.	Save `order_id`.

Create order with saved payment method token

Use the POST /v2/checkout/orders endpoint to create an order with the saved PayPal Vault token. This represents the final step in the vault flow when processing a purchase using a previously saved payment method token.

Sample API request

Copy and modify the following code to create an order with a payment token associated with a PayPal account.

1# x-function-name: create_order_with_vaulted_paypal_wallet
2# x-intent: checkout.use_saved_payment
3# description: Creates a PayPal checkout order using a previously vaulted PayPal Wallet via `vault_id`.
4# example_request_comment:
5#   Step 3: This is the final step in the vault flow.
6#   Use this when you're ready to make a purchase using a saved PayPal Wallet token (e.g., from Vault v3).
7#   `vault_id` comes from the payment_token returned after converting the setup token.
8curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
9  -H "PayPal-Request-Id: unique-request-id-987" \
10  -H "Authorization: Bearer ACCESS-TOKEN" \
11  -H "Content-Type: application/json" \
12  -d '{
13    "intent": "CAPTURE",
14    "purchase_units": [
15      {
16        "amount": {
17          "currency_code": "USD",
18          "value": "100.00"
19        }
20      }
21    ],
22    "payment_source": {
23      "paypal": {
24        "vault_id": "jwgvx42"  
25      }
26    }
27  }'

Expected output

The following JSON sample shows the response structure returned after successfully creating a checkout order using a vaulted PayPal Wallet token.

1{
2    "id": "ORDER-ID-12345",
3    "status": "CREATED",
4    "links": [
5        {
6            "rel": "self",
7            "href": "...",
8            "method": "GET"
9        }
10    ]
11}

Next steps

Store the order ID and log transaction metadata if needed.

Modify the code

Copy the code sample.

Replace ACCESS-TOKEN with your sandbox access token.

Replace REQUEST-ID with unique alphanumeric characters, such as a timestamp.

Use your payment method token ID as the vault_id.

Sample API response

The following sample API response demonstrates a successful order creation and capture using a vaulted PayPal payment method, showing the completed transaction with fee breakdown and capture details.

1{
2  "id": "4TH21426N05692944",
3  "status": "COMPLETED",
4  "payment_source": {
5    "paypal": {
6      "email_address": "email@example.com",
7      "account_id": "AJM9JTWQJCFTA",
8      "name": {
9        "given_name": "Firstname",
10        "surname": "Lastname"
11      },
12      "address": {
13        "country_code": "US"
14      }
15    }
16  },
17  "purchase_units": [
18    {
19      "reference_id": "default",
20      "payments": {
21        "captures": [
22          {
23            "id": "3B017991HX624902V",
24            "status": "COMPLETED",
25            "amount": {
26              "currency_code": "USD",
27              "value": "100.00"
28            },
29            "final_capture": true,
30            "seller_protection": {
31              "status": "ELIGIBLE",
32              "dispute_categories": [
33                "ITEM_NOT_RECEIVED",
34                "UNAUTHORIZED_TRANSACTION"
35              ]
36            },
37            "seller_receivable_breakdown": {
38              "gross_amount": {
39                "currency_code": "USD",
40                  "value": "100.00"
41                },
42              "paypal_fee": {
43                "currency_code": "USD",
44                "value": "3.98"
45              },
46              "net_amount": {
47                "currency_code": "USD",
48                "value": "96.02"
49              }
50            },
51            "links": [
52              {
53                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3B017991HX624902V",
54                "rel": "self",
55                "method": "GET"
56              },
57              {
58                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/3B017991HX624902V/refund",
59                "rel": "refund",
60                "method": "POST"
61              },
62              {
63                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/4TH21426N05692944",
64                "rel": "up",
65                "method": "GET"
66              }
67            ],
68            "create_time": "2022-08-08T23:13:35Z",
69            "update_time": "2022-08-08T23:13:35Z"
70          }
71        ]
72      }
73    }
74  ],
75  "payer": {
76    "name": {
77      "given_name": "Firstname",
78      "surname": "Lastname"
79    },
80    "email_address": "email@example.com",
81    "payer_id": "AJM9JTWQJCFTA",
82    "address": {
83        "country_code": "US"
84    }
85  },
86  "links": [
87    {
88      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/4TH21426N05692944",
89      "rel": "self",
90      "method": "GET"
91    }
92  ]
93}

Use payment token on behalf of payer

When payers aren't present to checkout, use their payment method token to create an order on their behalf.

If the payment token the payer created on the site is stored, skip this step.

To process a payment on behalf of the payer, retrieve the payment token they created. The process requires the customer ID that was assigned to this payer when they saved their payment method.

Sample API request

Use the Payment Methods Token API endpoint to retrieve stored payment tokens by customer ID.

1curl -v -k -X GET 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352051' \
2 -H 'Authorization: Bearer ACCESS-TOKEN' \
3 -H 'Content-Type: application/json'

Modify the code

Copy the code sample.

Replace ACCESS-TOKEN with your sandbox access token.

Pass the PayPal-generated customer_id to retrieve the payment token details associated with the payer.

The response returns the Merchant Customer ID if stored in the payment token

Sample response

This sample response returns all stored payment tokens for the specified customer ID, including payer information, shipping details, and links for token management.

1{
2  "customer": {
3    "id": "customer_4029352051"
4  },
5  "payment_tokens": [
6    {
7      "id": "jwgvx42",
8      "customer": {
9        "id": "customer_4029352051",
10      },
11      "payment_source": {
12        "paypal": {
13          "description": "Description for PayPal to be shown to PayPal payer",
14          "shipping": {
15            "name": {
16              "full_name": "Firstname Lastname"
17            },
18            "address": {
19              "address_line_1": "2211 N First Street",
20              "address_line_2": "Building 17",
21              "admin_area_2": "San Jose",
22              "admin_area_1": "CA",
23              "postal_code": "95131",
24              "country_code": "US"
25            }
26          },
27          "usage_type": "MERCHANT",
28          "customer_type": "CONSUMER",
29          "name": {
30            "given_name": "Firstname",
31            "surname": "Lastname",
32            "full_name": "Firstname Lastname"
33          },
34          "email_address": "john.doe@example.com",
35          "payer_id": "AJM9JTWQJCFTA",
36          "phone": {
37            "phone_number": {
38              "country_code": "US",
39              "national_number": "408-208-9263"
40            }
41          }
42        }
43      },
44      "links": [
45        {
46          "rel": "self",
47          "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
48          "method": "GET",
49          "encType": "application/json"
50        },
51        {
52          "rel": "delete",
53          "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/jwgvx42",
54          "method": "DELETE",
55          "encType": "application/json"
56        }
57      ]
58    }
59  ],
60  "links": [
61    {
62      "rel": "self",
63      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352051&page=1&page_size=5&total_required=false",
64      "method": "GET",
65      "encType": "application/json"
66    },
67    {
68      "rel": "first",
69      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352051&page=1&page_size=5&total_required=false",
70      "method": "GET",
71      "encType": "application/json"
72    },
73    {
74      "rel": "last",
75      "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens?customer_id=customer_4029352051&page=1&page_size=5&total_required=false",
76      "method": "GET",
77      "encType": "application/json"
78    }
79  ]
80}

A successful request returns an HTTP response code of 200 OK with payment method details and status for the provided payment token.

The response includes the following HATEOAS links:

Rel	Method	Description
`self`	GET	Make a GET request to this link to retrieve data about the saved payment method.
`delete`	DELETE	Make a DELETE request to delete the payment token from the vault.

After getting the payment method token ID, use a payment method token with checkout to create the order.

Troubleshooting

Error	Meaning	Solution
`INVALID_RESOURCE_ID`	Setup token is invalid or expired.	Restart the vault flow.
`422 Unprocessable`	Missing field or invalid value.	Check all required fields.
`DUPLICATE_REQUEST_ID`	You reused an idempotency key.	Use a new key or retry only if needed.

For more information, see Payment Method Tokens.

Webhooks

Use webhooks to receive real-time notifications about payment token events in the PayPal Vault integration. This helps track when tokens are created, deleted, or when deletion requests are initiated.

Subscribe to the VAULT.PAYMENT-TOKEN.CREATED event to monitor when payment tokens are successfully created.

Sample webhook payload

The following payload shows the webhook data sent when a payment token is created, including the token ID, payer information, and available actions.

1{
2    "event_version": "1.0",
3    "event_type": "VAULT.PAYMENT-TOKEN.CREATED",
4    "resource_type": "payment_token",
5    "resource_version": "3.0",
6    "resource": {
7        "owner": {
8            "merchant_id": "9LADS7VH329CG"
9        },
10        "owner_id": "9LADS7VH329CG",
11        "time_created": "2025-06-27T09:35:35.537PDT",
12        "links": [
13            {
14                "href": "https://msmaster.qa.paypal.com/v3/vault/payment-tokens/1ct24655vx634972d",
15                "rel": "self",
16                "method": "GET",
17                "encType": "application/json"
18            },
19            {
20                "href": "https://msmaster.qa.paypal.com/v3/vault/payment-tokens/1ct24655vx634972d",
21                "rel": "delete",
22                "method": "DELETE",
23                "encType": "application/json"
24            }
25        ],
26        "id": "1ct24655vx634972d",
27        "payment_source": {
28            "paypal": {
29                "description": "Description for PayPal to be shown to PayPal payer",
30                "usage_pattern": "IMMEDIATE",
31                "shipping": {
32                    "name": {
33                        "full_name": "Firstname Lastname"
34                    },
35                    "address": {
36                        "address_line_1": "2211 N First Street",
37                        "address_line_2": "Building 17",
38                        "admin_area_2": "San Jose",
39                        "admin_area_1": "CA",
40                        "postal_code": "95131",
41                        "country_code": "US"
42                    }
43                },
44                "permit_multiple_payment_tokens": false,
45                "usage_type": "MERCHANT",
46                "customer_type": "CONSUMER",
47                "email_address": "_sys_aquarium-7381640844368376@paypal.com",
48                "payer_id": "4T7SJAMG62XMC",
49                "name": {
50                    "given_name": "Raymond",
51                    "surname": "Gerald"
52                }
53            }
54        },
55        "customer": {
56            "id": "test-sample-webhook"
57        }
58    },
59    "summary": "A payment token has been created.",
60    "time_created": "2025-06-27T09:35:35.537PDT"
61}

Available webhook events

Configure the webhook endpoint to listen for the following PayPal Vault events.

Event	Trigger	Payment methods
`VAULT.PAYMENT-TOKEN.CREATED`	A payment token is created to save a payment method.	Cards and PayPal
`VAULT.PAYMENT-TOKEN.DELETED`	A payment token is deleted. The payer's payment method is no longer saved to the PayPal vault.	Cards and PayPal
`VAULT.PAYMENT-TOKEN.DELETION-INITIATED`	A request to delete a payment token has been submitted to the Payment Method Tokens API.	PayPal

Test App Switch

You can test this feature in both the PayPal production app and sandbox environments. To test App Switch, make sure your integration meets these requirements:

You have completed the PayPal App Switch integration.

You have opted in for App Switch.

Test your integration using PayPal's sandbox

This solution is available for your development team internationally.

Preconditions

Long-lived session or remember me flow

Face ID or Biometric

Enable login methods

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.

Testable use cases

Flow	Scenario	Expected behavior
Native app	The user starts from the merchant’s native app.	The user switches to the PayPal app and, after completing the approval flow, is automatically redirected back to the merchant app.
Mobile web	The user starts from the native default browser, such as Safari on iOS or Chrome on Android. The user has the PayPal app installed. The merchant sets return_flow to `AUTO`.	The user switches to the PayPal app and, after completing the approval flow, is automatically redirected back to the merchant website in the same browser tab.
Mobile web	The user starts from a non-native default browser, such as Chrome on iOS or Firefox on Android. The user has the PayPal app installed. The merchant sets `return_flow` to `AUTO`.	The user switches to the PayPal app and, after completing the approval flow, is automatically redirected back to the merchant website in the default browser.
Mobile web	The merchant sets `return_flow` to `MANUAL`. The user has the PayPal app installed.	The user switches to the PayPal app and, after completing the approval flow, the app prompts the payer to manually navigate back to the merchant website.
Mobile web	The user does not have the PayPal app installed, but the merchant has opted in for App Switch.	The user does not switch to the PayPal app and completes approval using the existing non-App Switch API integration.
Native app and mobile web	After App Switch, the user changes the payment method on the pay sheet and completes the flow.	The user completes approval with the new payment method they selected.
Native app and mobile web	After logging in, the user cancels the operation on the pay sheet screen in the PayPal app.	The user is switched back to the merchant browser or merchant app after canceling the approval flow.
Native app and mobile web	The user adds a new card.	When the user selects Add Card, they are prompted to log in again. After logging in, the new card form appears. Once the new card is added, the user can proceed with approval.

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.

Next steps

To deploy your PayPal Vault integration to production, complete these steps:

Verify that all functionality works correctly in the sandbox environment.

Complete the go-live onboarding process to enable PayPal Wallet processing with your live PayPal account.

Replace sandbox credentials and API URLs with production values when you deploy your integration.

Use the Payment Method Tokens API to retrieve payment tokens, list all payment tokens, and delete payment tokens.

App Switch: Direct API Vaulting without purchase

Overview

Know before you code

Prerequisites

App Switch Vault flow

Best practices

Unsupported integrations

Integrate App Switch

Integrate merchant native mobile app

App Switch scenarios

Native app prerequisites

Payment Method API integration

Use cases

Use case 1: Save payment method during onboarding

Use case 2: Purchase with saved payment method

Visual flow summary

Integration flow summary

Create setup token

Return and cancel URLs

Opt into App Switch

Sample setup token API request

Modify the code

Setup token response

Setup token lifecycle

Sample GET response

App Switch to and from PayPal

Integrate merchant website mobile browser

Create a setup token

Return and cancel URLs

Opt into App Switch

Create setup token request

Create setup token response

Setup token lifecycle

Sample GET response

Redirects to merchant website

Handle auto return flow

Handle manual return flow

Create payment method token

Request

Expected output

Next steps

Response details

Response payload

Next steps

Postconditions

Use case 3: Mobile browser purchase with saved payment method

Create order with saved payment method token

Sample API request

Expected output

Next steps

Modify the code

Sample API response

Use payment token on behalf of payer

Sample API request

Modify the code

Sample response

Troubleshooting

Webhooks

Sample webhook payload

Available webhook events

Test App Switch

Test your integration using PayPal's sandbox

Preconditions

Enable login methods

Testable use cases

Test on iOS

Test on Android

Next steps

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