# Pay Kit Android: Getting Started

**Integrate with Cash App Pay's Android SDK**

***

## Prerequisites

* All integrations require a Client ID provided by Cash App (see [Deliverables: Cash App Pay Partner Engineering](/cash-app-pay-partner-api/guides/partnerships/partner-onboarding-requirements))
* To authorize payments for a specific Merchant or Brand, you'll need to [create a Merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant) or [create a Brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand) using the Cash App REST APIs.

> One-time payments can be authorized for a Merchant, Brand, or Client. On-file payments can only be authorized for a Brand or Client.

## General SDK information

* Minimum Android supported SDK: `21`
* Target Android SDK: `31`

## Step 1: Import the dependency

You can get the latest version of the SDK from Maven. This is the import definition using Gradle:

```
implementation "app.cash.paykit:core:2.5.0"
```

For definitions of other build systems, see [Cash App Pay Android SDK on Maven Central](https://central.sonatype.com/artifact/app.cash.paykit/core/2.5.0/overview).

<Note>
  The size of the Version `v2.5.0` of the SDK is `12.3 kB`.
</Note>

## Step 2: Create an SDK instance

To create a new instance of the SDK, you must pass the  `client ID` . This is a required field.

You should use `CashAppPayFactory` to create an instance of the SDK. When setting up the SDK you'll need to specify the environment you will use, Sandbox or Production.
The function `createSandbox()` will create an SDK instance in the Sandbox environment.

> You should use the Sandbox environment during the development phase and Production environment for your actual production releases.

<br />Creating a Sandbox SDK instance:

```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.createSandbox(sandboxClientID)
```

<br />Creating a Production SDK instance:

```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.create(clientID)
```

<Tip title="Optional">
  We recommend using our [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app) to compare the Sandbox environment of the SDK during your development phase.
</Tip>

## Step 3: Register for state updates

To receive updates from Pay Kit, you’ll need to implement the `CashAppPayListener` interface. The interface exposes a single function, which gets called whenever there’s an internal state change emitted by the SDK:

```kotlin
interface CashAppPayListener {
   fun cashAppPayStateDidChange(newState: CashAppPayState)
}
```

You register with the SDK instance you’ve created above:

```kotlin
cashAppPay.registerForStateUpdates(this)
```

You should also use the `unregister` function when you're done with the SDK:

```kotlin
cashAppPay.unregisterFromStateUpdates()
```

### States

`CashAppPayState` is a sealed class parameter. We suggest that you use a Kotlin `when` statement on it.  Some of these possible states are for information only, but most drive the logic of your integration. The most critical states to handle are in the table below:

| State                      | Description                                                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ReadyToAuthorize`         | Show a Cash App Pay button in your UI and call `authorizeCustomerRequest()` when it is tapped.                                                                                       |
| `Approved`                 | Grants are ready for your backend to use to create a payment.                                                                                                                        |
| `Declined`                 | Customer has declined the Cash App Pay authorization and must start the flow over or choose a new payment method.                                                                    |
| `CashAppPayExceptionState` | The general wrapper state for exceptions. These can range from ***integration*** errors to **network** errors. The exception states are emitted only for unrecoverable error states. |

## Step 4: Handling Deep Linking

The authorization flow will bring Cash App to the foreground on the Customer’s device. After the Customer either authorizes or declines the request, your app must be returned to the foreground. This means that we must call your app from Cash App.  This is accomplished by [declaring an incoming intent filter](https://developer.android.com/training/app-links/deep-linking#adding-filters) on your app's Android Manifest and passing a corresponding redirect URI that uses the SDK when creating a Customer Request (*as can be seen on the next step*).

Here’s an example how this integration looks like for your  `AndroidManifest` :

```xml
<intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <!-- Register the Cash Pay Kit redirect URI or URL. Change this accordingly in your app. -->
    <data
        android:scheme="cashapppay"
        android:host="checkout" />
  </intent-filter>
```

## Step 5: Create a Customer Request

You can create a Customer Request as soon as you know the amount you’d like to charge or if you'd like to create an on-file payment request. We suggest that you create this request as soon as your checkout view controller loads, so that your Customer can authorize the request without delay.

### Example of a One-Time Payment

To charge \$5.00 as a one-time payment, your `createrequest` call might look like this:

```kotlin
val redirectUri = "yourapp://return_path"

val oneTimePayment = OneTimeAction(currency = USD, amount = 123, scopeId = "YOUR SCOPE ID HERE")
cashAppPay.createCustomerRequest(oneTimePayment, redirectUri)
```

**Note**: If you're using Afterpay SDK together with Cash App Pay SDK, the `merchantId` contained within that data is the same as `scopeId` in this context.

### Example of an On-File Payment

```kotlin
val redirectUri = "yourapp://return_path"

val onFilePayment = OnFileAction(scopeId = "YOUR SCOPE ID HERE")
cashAppPay.createCustomerRequest(onFilePayment, redirectURI)
```

## Step 6: Authorize the Customer Request

Once the SDK is in the `ReadyToAuthorize` state, you can display the Cash App Pay button. When the Customer taps the button, you can authorize the Customer Request.

**Example**

```kotlin
cashAppPay.authorizeCustomerRequest()
```

> Currently, the Button provided by the SDK is unmanaged. This means that it's a stylized button which isn't aware of SDK events out-of-the-box. It is the developer's responsibility to call the above method when the button is clicked and also manage any disabled and loading states.

Your app will redirect to Cash App for authorization. When the authorization is completed, your redirect URI will be called to open your app. The SDK will fetch your authorized request and return it to your callback listener as one of 2 states: `Approved` or `Declined`.

## Step 7: Pass Grants to the Backend and Create Payment

The `Approved` state will contain a `Grants` list object associated with it and it can be used with Cash App's [Create Payment API](/cash-app-pay-partner-api/api-reference/network-api/create-payment). Pass these Grants to your backend and call the `CreatePayment` API as a server-to-server call to complete your payment.

***