Integrate card payments in Android

The PayPal Mobile SDK is available through Maven Central. Add the mavenCentral repository to the build.gradle file of your project root:

1. Add snapshots repository

Add the snapshots repository to the build.gradle file of your project root.

2. Add snapshot to dependencies

Then, add a snapshot build by adding -SNAPSHOT to the current dependency version. For example, if you want to add a snapshot build for CardPayments, add the following:

Card

Integrate with card payments

Build and customize the card fields to align with your branding.

1. Add card payments module to your app

Add the card-payments package dependency in your app's build.gradle file:

1dependencies {
2  implementation "com.paypal.android:card-payments:CURRENT-VERSION"
3}

2. Create CardClient

A CardClient helps you attach a card to a payment.

In your Android app:

1. Use the CLIENT_ID to construct a CoreConfig.
2. Construct a CardClient using your CoreConfig object.

1val config = CoreConfig("CLIENT_ID", environment = Environment.SANDBOX)
2
3val cardClient = CardClient(config)

3. Get Order ID

On your server:

1. Create an ORDER_ID by using the Orders v2 API.
2. Pass your ACCESS_TOKEN in the Authorization header. To get an ACCESS_TOKEN, use the Authentication API.

   Note: This access token is only for the sandbox environment. When you're ready to go live, request a live access token by changing the request sandbox endpoint to https://api-m.paypal.com/v1/oauth2/token.

3. Pass the intent. You'll need to pass either AUTHORIZE or CAPTURE as the intent type. This type must match the /authorize or /capture endpoint you use to process your order.

Native Payments

Use PayPal native payments

Use PayPalNativePayments to add a PayPal paysheet to your app. The paysheet is a checkout page that the client launches within your app, instead of showing up as a pop-up. The paysheet shows all the PayPal payment methods available and helps the payer complete their payment.

Native checkout for a first-time customer

Native checkout for a returning customer

Follow these steps to add PayPalNativePayments:

1. Add PayPalNativePayments module to your app

Add the paypal-native-payments package dependency in your app's build.gradle file:

1dependencies {
2  implementation "com.paypal.android:paypal-native-payments:CURRENT-VERSION"
3}

Add the following Cardinal SDK Maven repository to your project’s top-level build.gradle file to pass credentials to Gradle:

1allprojects {
2  repositories {
3    maven {
4      url  "https://cardinalcommerceprod.jfrog.io/artifactory/android"
5      credentials {
6        username "paypal_sgerritz"
7        password "AKCp8jQ8tAahqpT5JjZ4FRP2mW7GMoFZ674kGqHmupTesKeAY2G8NcmPKLuTxTGkKjDLRzDUQ"
8      }
9    }
10  }
11}

2. Enable Native Checkout SDK

You'll need to set up authorization to use the Native Checkout SDK. To create a client ID and secret, follow the steps in Get Started. You need these values to generate an ACCESS_TOKEN.

Sandbox business account

Set up your sandbox business account to use native checkout as follows:

1. Log into the PayPal Developer Dashboard, toggle Sandbox, and go to Apps & Credentials.
2. In REST API apps, select the name of your app.
3. Go to Features > Accept payments and select *Native Checkout SDK.
4. Select Save Changes.

Add return URL

A return URL redirects users to the app after authenticating. Use the following steps to create a return URL:

1. Select your app from the My Apps & Credentials page on the Developer Dashboard.
2. Go to Features > Other features. Select the Log in with PayPal checkbox. Click on Advanced Settings. A pop-up window will open, and you'll see the Return URL field in the new window.

• 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 return URL with ://paypalpay as the suffix. For example, if your application ID is com.paypal.app, input com.paypal.app://paypalpay as the return URL.
• The return URL in the Developer Dashboard and the SDK must match exactly.
• The application ID and return URL must use lower case letters. The return URL is passed to the SDK via an intent filter and host name matching in the Android framework is case-sensitive

3. Select the Full Name and Email checkboxes found within the Advanced Settings. These are scopes of the Identity API.

3. Create PayPalNativeCheckoutClient

Use the following steps to set up the PayPal Native Checkout client for your app:

1. Construct CoreConfig

In your Android app, use the CLIENT_ID to construct a CoreConfig.

1val coreConfig = CoreConfig("CLIENT_ID", environment = Environment.SANDBOX)

2. Create native checkout request

Create a PayPalNativeCheckoutClient request to approve an order with a PayPal payment method and include the RETURN_URL:

1val payPalNativeClient = PayPalNativeCheckoutClient(
2  application = requireActvitiy().application,
3  coreConfig = coreConfig,
4  returnUrl = "RETURN_URL"
5)

3. Set up payment listener

Implement the PayPalNativeCheckoutListener on the PayPalNativeCheckoutClient to listen for result notifications from the SDK.

1payPalNativeClient.listener = object : PayPalNativeCheckoutListener {
2  override fun onPayPalCheckoutStart() {
3    // the PayPal paysheet is about to show up
4  }
5  override fun onPayPalCheckoutSuccess(result: PayPalNativeCheckoutResult) {
6    // order was approved and is ready to be captured/authorized
7  }
8  override fun onPayPalCheckoutFailure(error: PayPalSDKError) {
9    // handle the error
10  }
11  override fun onPayPalCheckoutCanceled() {
12    // the user canceled the flow
13  }
14}

4. Listen for shipping details

When a payer chooses to use shipping details from their PayPal profile, use PayPalNativeShippingListener to listen for changes to their shipping address or shipping method.

You can only implement PayPalNativeShippingListener if the shipping_preference in the order ID is set to GET_FROM_FILE.

Set a shippingListener on the PayPalNativeCheckoutClient to send notifications to your app when the user updates their shipping address or shipping method.

This code sample uses a try…catch function to handle the response:

1payPalNativeClient.shippingListener = object : PayPalNativeShippingListener {
2  override fun onPayPalNativeShippingAddressChange(
3    actions: PayPalNativePaysheetActions,
4    shippingAddress: PayPalNativeShippingAddress
5  ) {
6    // called when the user updates their chosen shipping address
7    // you must call actions.approve() or actions.reject() in this callback
8    actions.approve()
9    // OPTIONAL: you can optionally patch your order. Once complete, call actions.approve() if successful or actions.reject() if not.
10  }
11  override fun onPayPalNativeShippingMethodChange(
12    actions: PayPalNativePaysheetActions,
13    shippingMethod: PayPalNativeShippingMethod
14  ) {
15    // called when the user updates their chosen shipping method
16    // patch your order server-side with the updated shipping amount.
17    // Once complete, call `actions.approve()` or `actions.reject()`
18    try {
19      // TODO: patch order on server side, notify SDK of success by calling actions.approve()
20      actions.approve()
21    } catch (e: Exception) {
22      // catch any errors from patching the order e.g. network unavailable
23      // and notify SDK that the update was unsuccessful
24      actions.reject()
25    }
26  }
27}

5. Modify shipping details

When the shipping method changes, update the order details on your server by sending a PATCH request to the Update order endpoint of the Orders API.

Approve or reject changes to the shipping information to see changes appear in the paysheet UI by calling either PayPalNativePaysheetActions.approve() or PayPalNativePaysheetActions.reject().

To update the paysheet with a new shipping method, or when onPayPalNativeShippingMethodChange is called:

1. Patch the order on your server using the replace operation with all shipping methods.
   • Mark the new shipping method as selected.
   • Optional: Update the amount to reflect the new shipping cost.
2. Call approve() or reject() to accept or reject the changes and continue the payment flow.

For more information, visit the Update order endpoint of the Orders v2 API.

4. Get Order ID

On your server:

1. Create an ORDER_ID by using the Orders v2 API.
2. Pass your ACCESS_TOKEN in the Authorization header. To get an ACCESS_TOKEN, use the Authentication API.

   Note: This access token is only for the sandbox environment. When you're ready to go live, request a live access token by changing the request sandbox endpoint to https://api-m.paypal.com/v1/oauth2/token.

3. Pass the intent. You'll need to pass either AUTHORIZE or CAPTURE as the intent type. This type must match the /authorize or /capture endpoint you use to process your order.

Web payments

PayPal Web Payments

Integrate PayPalWebPayments to add a lighter checkout integration to your app. The checkout experience is launched in a browser within your application, reducing the size of the SDK.

Follow these steps to integrate PayPalWebPayments:

1. Add PayPalWebPayments to your app

Add the paypal-web-payments package dependency in your app's build.gradle file:

1dependencies {
2      implementation "com.paypal.android:paypal-web-payments:CURRENT-VERSION"
3    }

2. Set up your app for browser switching

PayPalWebPayments launches a checkout page in a browser within your application. Your app needs to handle the browser switch between the checkout page and your app. Set up a return URL that returns to your app from the browser.

Update your app's AndroidManifest.xml with details about the card payment activity that will return the user to your app after completing the payment. Include the following elements:

1. Set the activity launchMode to singleTop.
2. Set the android:scheme on the Activity that will be responsible for handling the deep link back into the app.
3. Add an intent-filter.
4. Register the myapp:// custom URL scheme in the intent-filter.

1<activity android:name="com.company.app.MyPaymentsActivity" android:exported="true" android:launchmode="singleTop">
2              ...
3      <intent-filter>
4        <action android:name="android.intent.action.VIEW">
5        <data android:scheme="custom-url-scheme">
6        <category android:name="android.intent.category.DEFAULT">
7        <category android:name="android.intent.category.BROWSABLE">
8      </category></category></data></action></intent-filter>
9 </activity>

Also, add onNewIntent to the host activity in your app:

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

3. Create PayPalWebCheckoutClient

Use the following steps to set up the PayPal Native Checkout client for your app:

1. Construct CoreConfig

In your Android app, use the CLIENT_ID to construct a CoreConfig.

1val config = CoreConfig("CLIENT_ID", environment = Environment.SANDBOX)

2. Create return URL

Set a return URL using the custom scheme you configured in the ActivityManifest.xml:

1val returnUrl = "custom-url-scheme"

3. Create web checkout request

Create a PayPalWebCheckoutClient to approve an order with a PayPal payment method:

1val payPalWebCheckoutClient = PayPalWebCheckoutClient(requireActivity(), config, returnUrl)

4. Set up payment listener

Set a PayPalWebCheckoutListener on the client to receive payment flow callbacks:

1payPalWebCheckoutClient.listener = object : PayPalWebCheckoutListener {
2      override fun onPayPalWebSuccess(result: PayPalWebCheckoutResult) {
3        // order was approved and is ready to be captured/authorized (see step 7)
4      }
5      override fun onPayPalWebFailure(error: PayPalSDKError) {
6        // handle the error
7      }
8      override fun onPayPalWebCanceled() {
9        // the user canceled the flow
10      }
11    }

4. Get Order ID

On your server:

1. Create an ORDER_ID by using the Orders v2 API.
2. Pass your ACCESS_TOKEN in the Authorization header. To get an ACCESS_TOKEN, use the Authentication API.

   Note: This access token is only for the sandbox environment. When you're ready to go live, request a live access token by changing the request sandbox endpoint to https://api-m.paypal.com/v1/oauth2/token.

3. Pass the intent. You'll need to pass either AUTHORIZE or CAPTURE as the intent type. This type must match the /authorize or /capture endpoint you use to process your order.