# Accepting Card Payments

The Card 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](#setup-a-paypal-developer-account)
1. [Add Card Module](#add-card-module)
1. [Test and go live](#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](https://developer.paypal.com/api/rest/#link-getstarted) to create a client ID and generate an access token.

You will need a server integration to create an order and capture funds using [PayPal Orders v2 API](https://developer.paypal.com/docs/api/orders/v2).
For initial setup, the `curl` commands below can be used in place of a server SDK.

## Add Card 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:1.0.0"
}

### 2. Initiate the Payments SDK

Create a `CoreConfig` using your client ID from the PayPal Developer Portal:

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(config)
cardClient.approveOrderListener = this

### 3. Create an order

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

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"
            }
        }
    ]
}'

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](#3-create-an-order) to a `CardRequest`.

val cardRequest  = CardRequest("<ORDER_ID>", card)

Optionally, a merchant app can request Strong Consumer Authentication (SCA) for a `CardRequest` that will require users to provide additional authentication information via 3D Secure.

To request SCA, add the following to `CardRequest`:

cardRequest.threeDSecureRequest = ThreeDSecureRequest(
  sca = SCA.SCA_ALWAYS,
  returnUrl = "myapp://return_url"
  cancelUrl = "myapp://cancel_url"
)

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

Create an intent filter to specify a deep link target for the SDK to return control back to your application:

<activity
    android:name=".MyDeepLinkTargetActivity"
    ...
    >
    <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>

### 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(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
}

// optional
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 ''

## Testing and Go Live

### 1. Test the Card integration

- [PayPal Developer: 3D Secure test scenarios](https://developer.paypal.com/docs/checkout/advanced/customize/3d-secure/test/)

### 2. Go live with your integration

Follow [these instructions](https://developer.paypal.com/api/rest/production/) to prepare your integration to go live.