CardPayments

Accepting Card Payments

The CardPayments module in the PayPal SDK enables Credit and Debit card payments in your app.

Follow these steps to add Card payments:

1. Setup a PayPal Developer Account
2. Add Card Module
3. Test and go live

Setup a PayPal Developer Account

You will need to set up authorization to use the PayPal Payments SDK. Follow the steps in Get Started to create a client ID.

You will need a server integration to create an order and capture funds using PayPal Orders v2 API. For initial setup, the curl commands below can be used in place of a server SDK.

Add CardPayments Module

1. Add the Payments SDK Card module to your app

In your app's build.gradle file, add the following dependency:

dependencies {
   implementation "com.paypal.android:card-payments:<CURRENT-VERSION>"
}

2. Initiate the Payments SDK

Create a CoreConfig using a client id:

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

Create a CardClient to approve an order with a Card payment method. Also, set a listener to receive callbacks from the client.

val cardClient = CardClient(activity, config)
cardClient.approveOrderListener = this

3. Create an order

When a user initiates a payment flow, call v2/checkout/orders to create an order and obtain an order ID:

Request

curl --location --request POST 'https://api.sandbox.paypal.com/v2/checkout/orders/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
    "intent": "<CAPTURE|AUTHORIZE>",
    "purchase_units": [
        {
            "amount": {
                "currency_code": "USD",
                "value": "5.00"
            }
        }
    ]
}'

Response

{
   "id":"<ORDER_ID>",
   "status":"CREATED"
}

The id field of the response contains the order ID to pass to your client.

4. Create a request containing the card payment details

Create a Card object containing the user's card details.

val card = Card(
    number = "4111111111111111",
    expirationMonth = "01",
    expirationYear = "25",
    securityCode = "123",
    billingAddress = Address(
        streetAddress = "123 Main St.",
        extendedAddress = "Apt. 1A",
        locality = "city",
        region = "IL",
        postalCode = "12345",
        countryCode = "US"
    )
)

Attach the card and the order ID from step 3 to a CardRequest. Strong Consumer Authentication (SCA) is enabled by default, so you need to specify a return_url to re direct to your app after the SCA challenge finishes. You can optionally set sca to SCA_ALWAYS if you want to require 3D Secure for every transaction.

val cardRequest  = CardRequest(
    orderId = "<ORDER_ID>",
    card = card,
    returnUrl = "myapp://return_url", // custom url scheme needs to be configured in AndroidManifest.xml (see below)
    sca = SCA.SCA_ALWAYS // default value is SCA_WHEN_REQUIRED
)

Notice the myapp:// portion of the returnUrl in the above code snippet. This myapp custom url scheme must also be registered in your app's AndroidManifest.xml.

Edit your app's AndroidManifest.xml to include an intent-filter and set the android:scheme on the Activity that will be responsible for handling the deep link back into the app. Also set the activity launchMode to singleTop:

Note: android:exported is required if your app compile SDK version is API 31 (Android 12) or later.

<activity
    android:name=".MyDeepLinkTargetActivity"
    android:launchMode="singleTop"
    android:exported="true"
    ...
    >
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <data android:scheme="myapp"/>
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

Also, add onNewIntent to your activity:

override fun onNewIntent(newIntent: Intent?) {
    super.onNewIntent(intent)
    intent = newIntent
}

5. Approve the order through the Payments SDK

Approve the order using your CardClient.

Call cardClient.approveOrder() to approve the order, and then handle results:

private fun approveMyOrder(cardRequest: CardRequest) {
  val result = cardClient.approveOrder(this, cardRequest)
}

fun onApproveOrderSuccess(result: CardResult) {
  // order was successfully approved and is ready to be captured/authorized (see step 6)
}

fun onApproveOrderFailure(error: PayPalSDKError) {
  // inspect `error` for more information
}

fun onApproveOrderCanceled() {
  // 3DS flow was canceled
}

fun onApproveOrderThreeDSecureWillLaunch() {
  // 3DS flow will launch
}

fun onApproveOrderThreeDSecureDidFinish() {
  // user successfully completed 3DS authentication
}

6. Capture/Authorize the order

If you receive a successful result in the client-side flow, you can then capture or authorize the order.

Call authorize to place funds on hold:

curl --location --request POST 'https://api.sandbox.paypal.com/v2/checkout/orders/<ORDER_ID>/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw ''

Call capture to capture funds immediately:

curl --location --request POST 'https://api.sandbox.paypal.com/v2/checkout/orders/<ORDER_ID>/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw ''

Test and Go Live

1. Test the Card integration

• PayPal Developer: 3D Secure test scenarios

2. Go live with your integration

Follow these instructions to prepare your integration to go live.