---
title: Accept a PayPal payment
description: Accept a PayPal payment in your Android app, including one-time
  checkout, save with purchase, and Pay Later and PayPal Credit.
badges:
  - type: neutral
    text: Mobile SDK v3
---

# Accept a PayPal payment (/sdk/android/add-payment-methods/paypal-checkout)



Checkout starts from a PayPal button. Your server creates and captures the order, and the SDK takes the buyer through approval in the PayPal app or a browser.

The buyer approves with biometrics or a passkey, then returns to your app through your Android App Link. If the PayPal app is not installed or the buyer is not eligible, checkout continues in a Chrome Custom Tab automatically.

## Checkout flow and call order [#checkout-flow-and-call-order]

When the buyer taps your PayPal button, call `createPayPalSession()` and create the order at the same time. Then call `start(activity, orderId, callback)` with the order ID.

The `start()` method requires a prepared shopper session. If you call it before `createPayPalSession()`, it fails with `PayPalError.sessionNotCreatedError` and logs the `SESSION_NOT_STARTED` event.

Call `createPayPalSession()` from your button’s `onClick` handler. It sends the token type, buyer identity, return URLs, and user action to PayPal and determines whether checkout opens in the PayPal app or an in-app browser. Create the PayPal session and order at the same time so both requests can run in parallel.

The `start()` callback only reports whether the authentication challenge launched. To receive the buyer’s approval, cancellation, or failure result, forward the return intent to `finishStart()`.

```mermaid
sequenceDiagram
    participant App as Your App
    participant SDK as PayPal SDK
    participant PayPal as PayPal (app or browser)
    participant Server as Your Server

    Note over App: Buyer taps your PayPal button
    par Prepare the session
        App->>SDK: createPayPalSession(tokenType=ORDER_ID, userIdentity, urlConfig, userAction)
    and Create the order
        App->>Server: Create order (Orders v2)
        Server-->>App: orderId
    end
    App->>SDK: start(activity, orderId, callback)
    alt Buyer eligible and PayPal app installed
        SDK->>PayPal: Open the PayPal app through your App Link
        Note over PayPal: Buyer approves with biometrics or a passkey
    else App not installed or buyer not eligible
        SDK->>PayPal: Open checkout in a Chrome Custom Tab
        Note over PayPal: Buyer logs in and approves
    end
    SDK->>App: PayPalPresentAuthChallengeResult (challenge presented)
    PayPal-->>App: Return to your app (App Link)
    App->>SDK: finishStart(intent)
    SDK->>App: PayPalFinishStartResult: Success / Canceled / Failure / NoResult
    App->>Server: Capture order (Orders v2)
```

## How the SDK works [#how-the-sdk-works]

The SDK handles the client side of checkout. Your server creates and captures orders with the Orders v2 API. Your responsibilities are:

* Configure the client.
* In your button's `onClick` handler, call `createPayPalSession()`, create the order, and pass the order ID and your `Activity` to `start()`.
* Forward the return intent to `finishStart()` and capture.

The SDK chooses the checkout experience, either the PayPal app or the in-app browser, and returns the buyer to your app. The one ordering rule is that you must call `createPayPalSession()` before `start()`.

## Before you begin [#before-you-begin]

Complete [Install and set up](/sdk/android/install-and-setup). For a PayPal Checkout integration:

* Add the `com.paypal.android:paypal-payments` and `com.paypal.android:payment-buttons` modules.
* Construct the client from the `CoreConfig` you built in setup:

```kotlin
val checkoutClient = PayPalClient(context, config)   // config from Install and set up
```

## Server: create an order [#server-create-an-order]

Call the Orders v2 API server-to-server and return only the order ID to your app. Pass return and cancel URLs to the SDK through the URL config from install and set up.

```shell
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-token>' \
  -d '{ "intent": "CAPTURE", "purchase_units": [ { "amount": { "currency_code": "USD", "value": "49.99" } } ] }'
```

## Integrate PayPal Checkout [#integrate-paypal-checkout]

These steps take the buyer from tapping the PayPal button to a captured payment. When the last step completes, your server has captured the order and the buyer sees confirmation of their payment.

### 1. Add the PayPal button [#1-add-the-paypal-button]

Render a `PayPalButton` on your checkout screen and set a click listener. It needs no order or session to display. Declare it in your layout, or create it programmatically, then wire the tap:

```kotlin
payPalButton.setOnClickListener {
    beginCheckout()   // Steps 2-4
}
```

Disable the button as soon as the buyer taps it, and show a loading indicator while `createPayPalSession()`, order creation, and `start()` are in flight. This prevents duplicate submissions.

### 2. Create the PayPal session [#2-create-the-paypal-session]

Call this in the button's `onClick`, before or alongside order creation. It returns immediately and prepares the session in the background. Pass `TokenType.ORDER_ID` for one-time checkout and save with purchase. PayPal approves both against an order ID. See [Save without purchase](#save-without-purchase) for the vault-only case.

```kotlin
import com.paypal.android.corepayments.model.TokenType

checkoutClient.createPayPalSession(
    tokenType    = TokenType.ORDER_ID,
    userIdentity = PayPalUserIdentity(email = "buyer@example.com"),  // or null, see Identity below
    urlConfig    = urlConfig,
    userAction   = PayPalUserAction.CONTINUE   // PAY_NOW for a "Pay Now" button
)
```

### 3. Collect device data [#3-collect-device-data]

Help reduce declines. Collect device data before you create the order, and attach the resulting client metadata ID to your create-order request.

```kotlin
val dataCollector = PayPalDataCollector(config)
val clientMetadataId = dataCollector.collectDeviceData(
    context, PayPalDataCollectorRequest(hasUserLocationConsent = false)
)
// Send clientMetadataId to your server; set it as the PayPal-Client-Metadata-Id header on your Orders v2 create call.
```

### 4. Create the order and start checkout [#4-create-the-order-and-start-checkout]

Create the order on your server, then hand the order ID to the SDK to launch the app-switch or in-app browser flow.

```kotlin
val orderId = myServer.createOrder()   // include the client metadata ID from Step 3

checkoutClient.start(
    activity = this,
    orderId  = orderId,
    callback = object : PayPalResultCallback {
        override fun onPayPalResult(result: PayPalPresentAuthChallengeResult) {
            when (result) {
                is PayPalPresentAuthChallengeResult.Success -> { /* Challenge presented (app switch or browser), awaiting the buyer's return */ }
                is PayPalPresentAuthChallengeResult.Failure -> showError(result.error)   // includes SESSION_NOT_STARTED
            }
        }
    }
)
```

### 5. Handle the return [#5-handle-the-return]

When your activity re-enters the foreground, forward the return intent to `finishStart()`. This intent delivers the buyer’s approval, cancellation, or failure. The `start()` callback only confirms that the challenge launched.

```kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    when (val result = checkoutClient.finishStart(intent)) {
        is PayPalFinishStartResult.Success  -> result.orderId?.let { captureOrder(it) }   // result.payerId also available; both are nullable
        is PayPalFinishStartResult.Canceled -> showCheckoutScreen()   // result.orderId also available, if present
        is PayPalFinishStartResult.Failure  -> showError(result.error)   // result.orderId also available, if present
        PayPalFinishStartResult.NoResult    -> Unit   // unrelated intent; ignore
        null                                 -> Unit   // finishStart() called without a matching start()/vault() call in this process
    }
}
```

Remove the loading indicator as soon as your app returns to the foreground, in `onNewIntent` or `onResume`. If the buyer backgrounded the PayPal app without approving or canceling, let them resume checkout.

Occasionally the OS opens the return in a Chrome tab instead of your app, usually because Android has not verified the App Link. Registering a `fallbackSchemeUrl` alongside your App Link covers the common case. As a safeguard, consider website logic that detects a redirected buyer, confirms order status, and guides them back.

### 6. Capture the order [#6-capture-the-order]

With the buyer's approval confirmed, capture the order on your server to complete the payment.

```kotlin
fun captureOrder(orderId: String) {
    // POST /v2/checkout/orders/{orderId}/capture on your server
    myServer.captureOrder(orderId)
}
```

## Identity: PayPalUserIdentity [#identity-paypaluseridentity]

You pass `userIdentity` to `createPayPalSession()` as a `PayPalUserIdentity` data class. The hint helps PayPal recognize the buyer, which can increase app-switch eligibility and approval rates. The SDK sends email and phone to PayPal for matching. The `userIdentity` parameter is nullable. Pass `null` when you have no buyer hint. PayPal still creates the session. When you have them, pass both email and phone: together they improve app-switch eligibility, risk assessment, and approval rates beyond email alone.

| Field                     | Type                 | When to use                                                                           |
| ------------------------- | -------------------- | ------------------------------------------------------------------------------------- |
| `existingPayPalSessionId` | `String?`            | Your server already created a buyer session. Pass its ID.                             |
| `email`                   | `String?`            | You know the buyer's email address.                                                   |
| `phone`                   | `PayPalPhoneNumber?` | You know the buyer's phone number. Construct with `countryCode` and `nationalNumber`. |

```kotlin
// Email only
PayPalUserIdentity(email = "buyer@example.com")

// Email and phone together improve matching further
PayPalUserIdentity(
    email = "buyer@example.com",
    phone = PayPalPhoneNumber(countryCode = "1", nationalNumber = "4085551234")
)

// Server-side shopper session
PayPalUserIdentity(existingPayPalSessionId = serverSideSessionId)

// No buyer hint
checkoutClient.createPayPalSession(tokenType = TokenType.ORDER_ID, userIdentity = null, urlConfig = urlConfig, userAction = PayPalUserAction.CONTINUE)
```

## Save with purchase [#save-with-purchase]

Save with purchase saves the buyer’s PayPal account during a purchase with a single approval. The button sequence is the same as for a regular checkout.

The only difference is that your server creates the order with `payment_source.paypal.attributes.vault` set. When saving a payment method, the API also requires `experience_context.return_url` and `cancel_url` on the request. The SDK's App Link handles the buyer's actual return, so these can be placeholder values:

```shell
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-token>' \
  -d '{
    "intent": "CAPTURE",
    "purchase_units": [ { "amount": { "currency_code": "USD", "value": "49.99" } } ],
    "payment_source": {
      "paypal": {
        "experience_context": { "return_url": "https://example.com/return", "cancel_url": "https://example.com/cancel" },
        "attributes": { "vault": { "store_in_vault": "ON_SUCCESS", "usage_type": "MERCHANT", "customer_type": "CONSUMER" } }
      }
    }
  }'
```

On approval, PayPal both completes the purchase and stores the payment method, but `PayPalFinishStartResult.Success` carries only the order ID and payer ID. Retrieve the vaulted token server-side after capture, either by getting the order or through the Payment Method Tokens API.

## Save without purchase [#save-without-purchase]

Save a buyer's PayPal account for future charges with no purchase now. Call `createPayPalSession()` first with `tokenType = TokenType.VAULT_ID`, using `SETUP_NOW` for a "Set up now" button, then create the setup token on your server and call `vault()`.

```kotlin
// In your "Set up now" button's onClick handler:
checkoutClient.createPayPalSession(
    tokenType    = TokenType.VAULT_ID,
    userIdentity = userIdentity,
    urlConfig    = urlConfig,
    userAction   = PayPalUserAction.SETUP_NOW
)

val setupTokenId = myServer.createSetupToken()

checkoutClient.vault(
    activity     = this,
    setupTokenId = setupTokenId,
    callback = object : PayPalResultCallback {
        override fun onPayPalResult(result: PayPalPresentAuthChallengeResult) {
            when (result) {
                is PayPalPresentAuthChallengeResult.Success -> { /* Challenge presented, awaiting the buyer's return */ }
                is PayPalPresentAuthChallengeResult.Failure -> showError(result.error)   // includes SESSION_NOT_STARTED
            }
        }
    }
)
```

Forward the return intent to `finishVault()` in `onNewIntent`, the same way checkout forwards to `finishStart()`. The `approvalSessionId` value identifies the vaulted approval.

```kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    when (val result = checkoutClient.finishVault(intent)) {
        is PayPalFinishVaultResult.Success -> savePaymentToken(result.approvalSessionId)
        PayPalFinishVaultResult.Canceled   -> showVaultScreen()
        is PayPalFinishVaultResult.Failure -> showError(result.error)
        PayPalFinishVaultResult.NoResult   -> Unit   // unrelated intent; ignore
        null                                -> Unit   // finishVault() called without a matching start()/vault() call in this process
    }
}
```

## Pay Later and PayPal Credit [#pay-later-and-paypal-credit]

Pay Later and PayPal Credit are PayPal funding sources, not separate SDK flows. Select the funding source on your server when you create the order by setting `payment_source.paypal.experience_context.payment_method_selected` to one of these values:

* `PAYPAL` (default)
* `PAYPAL_PAY_LATER`
* `PAYPAL_CREDIT`

All three funding sources follow the same client-side flow as PayPal Checkout:

`createPayPalSession()` → `start(activity, orderId, callback)` → `finishStart(intent)`

Pay Later and PayPal Credit support one-time checkout and save with purchase. They don't support save without purchase.

Use `PayPalCheckoutFundingSource` (`PAYPAL`, `PAY_LATER`, or `PAYPAL_CREDIT`) in your app code to track the buyer's selection and map it to the corresponding `payment_method_selected` value in your create-order request. The SDK doesn't pass this enum to any `PayPalClient` method.

You can also add dedicated buttons with the `payment-buttons` module:

* `PayLaterButton`
* `PayPalCreditButton`

## Handle results [#handle-results]

The SDK reports results in two stages:

1. The `start()` or `vault()` callback confirms whether the authentication challenge launched.
2. The `finishStart()` or `finishVault()` method reports the buyer’s final outcome.

Handle every result described below. Treat cancellation as a normal buyer choice.

### Handle the authentication challenge result [#handle-the-authentication-challenge-result]

The callbacks for `start()` and `vault()` return a `PayPalPresentAuthChallengeResult`. Handle these results:

* **Success**: The authentication challenge launched.
* **Failure** (`Failure(error)`): Checkout or vaulting did not launch. Show the error.

The `SESSION_NOT_STARTED` event means your app called `start()` or `vault()` before `createPayPalSession()`. Call `createPayPalSession()` first.

### Handle checkout results [#handle-checkout-results]

Forward the return intent to `finishStart()` for checkout and save with purchase. This method returns a `PayPalFinishStartResult?`.

Handle these results:

* **Success** (`Success(orderId?, payerId?)`): Capture the order if `orderId` is present.
* **Canceled** (`Canceled(orderId?)`): Return the buyer to your checkout screen. The result includes `orderId` when available. No charge occurs.
* **Failure** (`Failure(error, orderId?)`): Show the error. The result includes `orderId` when available.
* **No result** (`NoResult`): The intent was not a PayPal return. Ignore it.
* **Null** (`null`): No matching `start()` or `vault()` call occurred in this process. Ignore the result.

### Handle vault results [#handle-vault-results]

Forward the return intent to `finishVault()` for save without purchase. This method returns a `PayPalFinishVaultResult?`.

Handle these results:

* **Success** (`Success(approvalSessionId)`): Store the returned `approvalSessionId`.
* **Canceled** (`Canceled`): Return the buyer to your save screen.
* **Failure** (`Failure(error)`): Show the error.
* **No result** (`NoResult`): The intent was not a PayPal return. Ignore it.
* **Null** (`null`): No matching `start()` or `vault()` call occurred in this process. Ignore the result.

## Test and go live [#test-and-go-live]

Test on a physical device, because the app-switch path requires one.

### Trigger the app-switch path [#trigger-the-app-switch-path]

The SDK switches to the PayPal app only when all of the following hold. Otherwise it falls back to a Chrome Custom Tab:

* A physical device with the PayPal app installed, using the sandbox app for sandbox testing.
* Merchant and buyer are in the US, and your integration is App Switch eligible.
* The buyer-identity email you pass to `createPayPalSession()` matches the account signed into the PayPal app.
* In the PayPal app, you enabled **Extend your login session** and fingerprint under **Avatar › Login and security**.

To test the in-app browser path, use a device without the PayPal app installed, or an ineligible buyer. Full sandbox-app setup lives in the published [PayPal Android testing guide](https://developer.paypal.com/braintree/docs/guides/paypal/testing-go-live/android/v5#testing-app-switch).

### Test scenarios [#test-scenarios]

| Scenario                                   | Expected result                                                                                                                   |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| App switch: end to end                     | The buyer switches to the PayPal app, approves, returns to your app, and the order captures.                                      |
| In-app browser: end to end                 | With the PayPal app not installed, or with an ineligible buyer, checkout completes in a Chrome Custom Tab and the order captures. |
| Buyer cancels in PayPal                    | Your app returns the buyer to your checkout screen and PayPal makes no charge.                                                    |
| Save with purchase                         | Order captures. The vaulted token is retrievable server-side.                                                                     |
| Save without purchase                      | You receive and store the approval session ID from `finishVault()`, and can charge the vaulted account later.                     |
| Pay Later and PayPal Credit eligible buyer | Financing offers render. Approval and capture proceed the same as standard PayPal.                                                |

### Go live checklist [#go-live-checklist]

* Call `createPayPalSession()` on the button tap, before or alongside order creation.
* Switch `CoreEnvironment.SANDBOX` to `CoreEnvironment.LIVE` and use your live client ID and merchant ID.
* Verify the App Link return works in a release build, after you host and verify assetlinks.json.
* Verify that you registered the custom-scheme fallback, `fallbackSchemeUrl`, and that it returns the buyer to your app.
* Confirm your code handles all result variants: `PayPalPresentAuthChallengeResult` (Success, Failure) from `start()` or `vault()`, and `PayPalFinishStartResult` and `PayPalFinishVaultResult` (Success, Canceled, Failure, NoResult, and `null`) from `finishStart()` or `finishVault()`.
* Collect device data and pass the client metadata ID on your Orders v2 request.
* Contact your PayPal account team to enable App Switch for production traffic.

## See also [#see-also]

* [Buttons](/sdk/android/add-payment-methods/payment-buttons): add and style the PayPal button that starts this flow.
* [Troubleshooting](/sdk/android/troubleshooting): diagnose common build and integration failures by symptom.
* [PayPal Developer Dashboard](/dashboard/): get your client ID and merchant ID and enable payment methods.
* [Orders v2 API](/api/orders/v2/): create, authorize, capture, and refund orders from your server.
