App Switch: Direct API One-Time Payments

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}

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

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...
9</manifest>

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}`);

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a' \
4-H 'Authorization: Bearer 6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
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": "app://xo/234?clientStatus=success",
13                "cancel_url": "app://xo/234?clientStatus=cancel",
14                "app_switch_context": {
15                  "native_app":{
16                      "os_type": "IOS",
17                      "os_version": "17.3.1",
18                      "app_url": "https://example.com/merchant_app_universal_link"
19                  }
20              }
21            }
22        }
23    },
24    "purchase_units": [
25        {
26            "amount": {
27                "currency_code": "USD",
28                "value": "64.00"
29            }
30        }
31    ]
32}'

1{
2    "id": "11D37583KV396803L",
3    "intent": "CAPTURE",
4    "status": "PAYER_ACTION_REQUIRED",
5    "payment_source": {
6        "paypal": {
7            "email_address": "customer@example.com",
8            "app_switch_eligibility": true
9        }
10    },
11    "purchase_units": [
12        {
13            "reference_id": "default",
14            "amount": {
15                "currency_code": "USD",
16                "value": "64.00"
17            },
18            "payee": {
19                "email_address": "test@business.example.com",
20                "merchant_id": "CME27DCHYSLEL"
21            }
22        }
23    ],
24    "payer": {
25        "email_address": "customer@example.com"
26    },
27    "links": [
28        {
29            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/11D37583KV396803L",
30            "rel": "self",
31            "method": "GET"
32        },
33        {
34            "href": "https://www.paypal.com/app-switch-checkout?token=11D37583KV396803L",
35            "rel": "payer-action",
36            "method": "GET"
37        }
38    ]
39}

1"payment_source": {
2        "paypal": {
3            "email_address": "customer@example.com",
4            "app_switch_eligibility": true,
5            "experience_status":  "CANCELED"
6        }
7    }

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

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}

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

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

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}

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a' \
4-H 'Authorization: Bearer 6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g' \
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/checkout",
13                "cancel_url": "https://example.com/checkout",
14                "app_switch_context": {
15                    "mobile_web":{
16                     "return_flow": "AUTO" or "MANUAL",
17                     "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"
18                   }
19                }
20            }
21        }
22    },
23    "purchase_units": [
24        {
25            "amount": {
26                "currency_code": "USD",
27                "value": "64.00"
28            }
29        }
30    ]
31}'

1{
2    "id": "11D37583KV396803L",
3    "intent": "CAPTURE",
4    "status": "PAYER_ACTION_REQUIRED",
5    "payment_source": {
6        "paypal": {
7            "email_address": "customer@example.com",
8            "app_switch_eligibility": true
9        }
10    },
11    "purchase_units": [
12        {
13            "reference_id": "default",
14            "amount": {
15                "currency_code": "USD",
16                "value": "64.00"
17            },
18            "payee": {
19                "email_address": "test@business.example.com",
20                "merchant_id": "CME27DCHYSLEL"
21            }
22        }
23    ],
24    "payer": {
25        "email_address": "customer@example.com"
26    },
27    "links": [
28        {
29            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/11D37583KV396803L",
30            "rel": "self",
31            "method": "GET"
32        },
33        {
34            "href": "https://www.sandbox.paypal.com/checkoutnow?token=11D37583KV396803L",
35            "rel": "payer-action",
36            "method": "GET"
37        }
38    ]
39}

1"payment_source": {
2        "paypal": {
3            "email_address": "customer@example.com",
4            "app_switch_eligibility": true,
5            "experience_status":  "CANCELED"
6        }
7    }

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 order
5		// Verify the order approval, complete payment
6		// & redirect to confirmation page to complete flow
7	} else if (params.canceled) {
8		// Buyer canceled PayPal app switch
9	}
10})

1const onLoadHash = () => {
2	const hashParams = parseHashParams(window.location.hash);
3	
4	if (hashParams.approved) {
5		// Buyer is returning from app switch
6		// Complete payment & 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()

1document.addEventListener('visibilitychange', (e) => {
2	// call your server API to make a request to PayPal to get the order status and buyer cancellation status (if applicable)
3	
4	//If #change event was triggered then cancel this event (to avoid multiple payment/order calls from both the listeners)
5    const hashParams = parseHashParams(window.location.hash);
6	if (hashParams.approved || hashParams.cancelled) {
7		//Wil be handled by hashChange. Exit
8		return;
9	}
10	
11	const orderResponse = getOrderResponse(orderId);
12	const orderStatus = orderResponse.status;
13	const cancelledActivity = orderResponse?.payment_source?.paypal?.experience_status;
14	
15	//Order Approved
16	if (orderStatus === 'approved') {
17		// Capture payment & redirect to confirmation page
18	} 
19	
20	//Buyer cancels transaction
21	else if (orderStatus !== 'approved' && cancelledActivity == 'cancelled') {
22		// Buyer app switched to paypal but closed checkout before approving the transaction. 
23		// Display Cart page again or take the appropriate "cancel" action 
24	}
25	
26	else {
27		// Display a modal to complete payment on the PayPal App
28	}
29});

1router.get('/checkout', validateOnApprove, async (req, res) => {
2  try {
3    const {
4      PayerID,
5      token
6    } = req.query;
7	if (PayerID) {
8		// successfully approved - validate order, capture payment, & redirect
9	} else {
10		// not approved - render the full checkout page for cancel handling
11	}
12});

1const onLoadQuery = () => {
2	const queryParams = parseQueryParams(window.location.query);
3	if (queryParams.PayerID && queryParams.token) {
4		// Buyer is returning from full page redirect
5		// Complete payment & redirect to confirmation page
6	} else (!queryParams.PayerId && queryParams.token) {
7		// Buyer canceled payment with PayPal, display alternative checkout options
8	} else {
9		// New buyer checkout session, show standard checkout
10	}
11}
12onLoadQuery();