Client-side integration

Follow these steps to add the PayPal Mobile Checkout SDK to your Android app

SDKBetaLast updated: October 5th 2021, @ 2:54:38 pm


Know before you code

  • Complete the steps in Get started to set up your PayPal account, client ID, and sandbox emails for testing.

  • You must have a minSdkVersion of API 21 (Android 5.0 Lollipop) or later.

  • Client-side and server-side integrations share many of the same integration steps. If you want to integrate the SDK with your server-side integration, continue with the steps on this page, until directed to the specific steps for a Server-side integration.

  • The PayPal Mobile Checkout SDK uses scopes from the Identity API.

  • PayPal Mobile Checkout SDK integrates with Cardinal Consumer Authentication. Cardinal Consumer Authentication handles any 3D Secure requirements set by the card issuer. If a buyer needs to be verified through 3D Secure, they are directed to a Custom Tab to complete a challenge. Then they can finish checkout through PayPal's mobile website. This helps to:

    • Improve authorization rates
    • Reduce fraud
    • Reduce false declines
    • Reduce manual review of orders
  • The version of the Cardinal Consumer Authentication library used in the SDK does not support AndroidX natively. To prevent runtime crashes when a buyer needs to be verified through 3D Secure, you should add android.enableJetifier=true to your gradle.properties file.

    Note: Before going live, PayPal must review your app to approve the sharing of customer data. The review automatically starts once you select the Log in with PayPal checkbox on your Developer Dashboard (Step 3 of Enable the SDK). The review for sandbox apps typically completes within 2 hours. The review for live apps typically completes within 2 business days, but under certain circumstance, can take up to 10 business days.

Enable the SDK

  1. Select your app from the My Apps & Credentials page on the Developer Dashboard.
  2. Enter a Return URL.
  • You can use an Android App Link registered within the Developer Console to handle SDK redirects.

  • Alternatively, you can use your application ID (typically referenced via BuildConfig.APPLICATION_ID) and register your application ID with ://paypalpay as the suffix. For example, if your application ID is com.paypal.app, input com.paypal.app://paypalpay in the Developer Console.

  • The return URL in the Developer Dashboard and the SDK must match exactly.

    Note: If you change the return URL in the Developer Dashboard, PayPal must review your app again. The review period automatically begins any time the return URL changes.

  1. Select the Log in with PayPal checkbox and the Full name and Email checkboxes found within the Advanced options. These are scopes of the Identity API.

Step result

The SDK is enabled.

Prepare your app

Define the android.permission.INTERNET permission in the AndroidManifest.xml file of your application as follows:

  <manifest xmlns:android="http://schemas.android.com/apk/res/android">

      <uses-permission android:name="android.permission.INTERNET" />
      ...

  </manifest>

Step result

Your app is ready to install the SDK.

Add the SDK to your app

The PayPal Mobile Checkout SDK is available through Maven Central. Add the SDK to your app through build.gradle updates.

  1. Add the required repositories to the build.gradle file of your project root.

    allprojects {
        repositories {
            mavenCentral()
            // This private repository is required to resolve the Cardinal SDK transitive dependency.
            maven {
                url  "https://cardinalcommerceprod.jfrog.io/artifactory/android"
                credentials {
                    // Be sure to add these non-sensitive credentials in order to retrieve dependencies from
                    // the private repository.
                    username paypal_sgerritz
                    password AKCp8jQ8tAahqpT5JjZ4FRP2mW7GMoFZ674kGqHmupTesKeAY2G8NcmPKLuTxTGkKjDLRzDUQ
                }
            }
        }
    }
    
  2. Add Java 8 compatibility to the build.gradle file of your app module.

    android {
        ...
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
    
        kotlinOptions {
            jvmTarget = "1.8"
        }
    }
    
  3. Add the PayPal Mobile Checkout SDK dependency to the build.gradle file of your app module. See the changelog for the most recent version.

    dependencies {
        implementation('com.paypal.checkout:android-sdk:X.X.X')
    }
    

Step result

The SDK is in your app.

Configure the SDK

Configure the PayPal Mobile Checkout SDK in the onCreate function of your app.

Sample code

This sample code includes these optional properties:

  • currencyCode
  • userAction
  • settingsConfig

Providing currencyCode and userAction can help with funding eligibility for payment buttons. The settingsConfig provides additional properties that are useful for development builds. We also set loggingEnabled to be true to enable logging from the SDK.

Note: You must initialize the SDK by calling PayPalCheckout.setConfig(config) in your application class's onCreate(). Initializing it on other areas may lead to an IllegalStateException.

  1. Kotlin
  2. Java
1class YourApp : Application() {
2 override fun onCreate() {
3 super.onCreate()
4 val config = CheckoutConfig(
5 application = this,
6 clientId = YOUR_CLIENT_ID,
7 environment = Environment.SANDBOX,
8 returnUrl = "${BuildConfig.APPLICATION_ID}://paypalpay",
9 currencyCode = CurrencyCode.USD,
10 userAction = UserAction.PAY_NOW,
11 settingsConfig = SettingsConfig(
12 loggingEnabled = true
13 )
14 )
15 PayPalCheckout.setConfig(config)
16 }
17 }

Note: If your application ID contains underscores then you need to modify the returnUrl so that it forms a valid URI. For details, see Customize return URL.

Step result

The SDK is configured and your app is ready to add payment buttons.

Add payment buttons

To render the payment buttons on your app, add the following code to your checkout page:

<com.paypal.checkout.paymentbutton.PaymentButtonContainer
    android:id="@+id/payment_button_container"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:paypal_button_color="silver"
    app:paypal_button_label="pay"
    app:paypal_button_shape="rectangle"
    app:paypal_button_size="large"
    app:paypal_button_enabled="true" />

Step result

Payment buttons display on your app.

Create and capture orders

You have two options to complete your integration:

Integration typeUse case
Client-side integrationIf want the simplest integration, continue with the sample code below for a client-side integration. Client-side integrations don't require you to create your own server infrastructure.
Server-side integrationChose a server-side integration if you want more control over your integration. Server-side integrations require you to have your own server infrastructure.

Sample code

This sample code creates an order of a single item for $10.00 USD. When the buyer selects Pay Now on a payment sheet, the OnApprove callback invokes and the funds are ready for immediate capture.

  1. Kotlin
  2. Java
1class CheckoutActivity : AppCompatActivity() {
2 override fun onCreate(savedInstanceState: Bundle?) {
3 super.onCreate(savedInstanceState)
4 // ...
5 paymentButtonContainer.setup(
6 createOrder =
7 CreateOrder { createOrderActions ->
8 val order =
9 Order(
10 intent = OrderIntent.CAPTURE,
11 appContext = AppContext(userAction = UserAction.PAY_NOW),
12 purchaseUnitList =
13 listOf(
14 PurchaseUnit(
15 amount =
16 Amount(currencyCode = CurrencyCode.USD, value = "10.00")
17 )
18 )
19 )
20 createOrderActions.create(order)
21 },
22 onApprove =
23 OnApprove { approval ->
24 approval.orderActions.capture { captureOrderResult ->
25 Log.i("CaptureOrder", "CaptureOrderResult: $captureOrderResult")
26 }
27 }
28 )
29 }
30}

Add and modify the code

  1. (Optional) Add the OnCancel callback to be notified if the buyer cancels the order.

    1. Kotlin
    2. Java
    1paymentButtonContainer.setup(
    2 // ...
    3 onCancel = OnCancel {
    4 Log.d("OnCancel", "Buyer canceled the PayPal experience.")
    5 }
    6 )
  2. (Optional) Add the OnError callback to be notified if the SDK encounters an error, resulting in the dismissal of the payment sheet.

    1. Kotlin
    2. Java
    1paymentButtonContainer.setup(
    2 // ...
    3 onError = OnError { errorInfo ->
    4 Log.d("OnError", "Error: $errorInfo")
    5 }
    6 )
  3. (Optional) Configure the following messages to display to buyers:

    • Success message when funds capture successfully.
    • Cancellation confirmation when the buyer selects to cancel the order.
    • Error message when the capture is unsuccessful.

    Note: For more information about creating orders, including additional parameters that can be submitted, view Orders REST API.

Step result

You can now test purchases.

Test and go live

  • Use your client ID when adding the PayPal Mobile Checkout SDK to your app.
  • Use your sandbox accounts when testing the SDK.
  • The SDK may prompt buyers to log in with a one-time passcode sent by SMS to their phone number.
  • Sandbox accounts with a confirmed phone number and US as the selected country will always prompt the buyer to log in with a one-time passcode.
  • When testing the SDK with sandbox accounts, enter 111111 as the one-time passcode.

Next steps

See also