> This page is for Cash App Pay Partner API.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers-beta.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers-beta.cash.app/_mcp/server.
# 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`.
## 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.
\
Creating a Sandbox SDK instance:
```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.createSandbox(sandboxClientID)
```
\
Creating a Production SDK instance:
```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.create(clientID)
```
> **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.
## 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
```
## 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.
---
# UI Components
The SDK provides an unmanaged custom view deriving from `Button`. There are separate Light and Dark versions to best match your particular UI, and the component is designed to allow for some flexibility in sizing (on both axes).
## CashAppPayButton
Developers are allowed to change the size of `CashAppPayButton` to suit their design, as long as they fall within certain limits.
These limits are:
`CashAppPayButton` should be:
* at least `34dp` tall
* at least `122dp` wide
* at most `54dp` tall
The light and dark variants of the `CashAppPayButton` can be defined using the style parameter, as follows:
**`title= "Light Button"`**
```xml title= "Light Button"
```
\
**Light-background Button:**
\
**`title= "Dark Button"`**
```xml title= "Dark Button"
```
\
**Dark-background Button:**
> **Note**
>
> Due to its unmanaged nature, the button is merely a stylized button, it's up to developers to trigger the correct action on button press, as well as manage any visibility states of the button accordingly.
> **Note**
>
> You can use Android's Resource Qualifiers, such as `values-night`, to easily provide a button variation that follows the system's theme.
## Pay Kit Android: Advanced Operations
This page describes advanced operations for the Cash App Pay Android SDK. For most setups, see [Getting Started](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-android) first, which should contain most of the relevant information for your needs.
### Start with an existing customer request
When you use `createCustomerRequest` you get a `CustomerResponseData` object returned to you. This object contains an `id` field which is the `Request ID`.
> **Note**
>
> If required, you can save this ID to retrieve the request at a later time.
Since you are starting with an existing customer request, you'd start the SDK by calling `startWithExistingCustomerRequest` and pass the `Request ID`.
\
This is how it would look:
```kotlin
cashAppPay.startWithExistingCustomerRequest(customerRequestID)
```
\
> **Note**
>
> * You must call this function *only* when you start on a new SDK instance.
> * You must register for state updates before calling this function.
### Update an existing customer request
You can update an existing customer request by calling `updateCustomerRequest` and passing in the `Request ID` and a new `CashAppPayPaymentAction` object.
\
This is the signature of the function:
```kotlin
fun updateCustomerRequest(
requestId: String,
paymentAction: CashAppPayPaymentAction,
)
```
\
> **Note**
>
> You would typically use this function only after you've already started the SDK with a customer request.