Pay Kit Android: Getting Started

Prerequisites

• All integrations require a Client ID provided by Cash App (see Deliverables: Cash App Pay Partner Engineering)
• To authorize payments for a specific Merchant or Brand, you’ll need to create a Merchant or create a Brand using the Cash App REST APIs.

General SDK information

• Minimum Android supported SDK: 21
• Target Android SDK: 36

Step 1: Import the dependency

Get the latest version of the SDK from Maven.

Gradle

implementation "app.cash.paykit:core:X.Y.Z"

Gradle version catalogs

paykit-core = { group = "app.cash.paykit", name = "core", version.ref = "paykit" }

For the latest released version, check GitHub Releases or Cash App Pay Android SDK on Maven Central.

Step 2: Create an SDK instance

Use CashAppPayFactory to create an instance of the SDK.

• During setup, specify the development environment you will use: Sandbox or Production.
• To create a new instance of the SDK, pass client ID. This is a required field.
• The function createSandbox() will create an SDK instance in the Sandbox environment.

Creating a Sandbox SDK instance:

1
val cashAppPay : CashAppPay = CashAppPayFactory.createSandbox(sandboxClientID)

Creating a Production SDK instance:

1
val cashAppPay : CashAppPay = CashAppPayFactory.create(clientID)

Step 3: Register for state updates

To receive updates from Pay Kit, implement the CashAppPayListener interface.

1. The interface exposes a single function, which gets called whenever there’s an internal state change emitted by the SDK.

1
interface CashAppPayListener {
2
   fun cashAppPayStateDidChange(newState: CashAppPayState)
3
}

2. Register with the SDK instance you’ve created above:

1
cashAppPay.registerForStateUpdates(this)

3. Use the unregister function after you have finished using the SDK:

1
cashAppPay.unregisterFromStateUpdates()

States

CashAppPayState is a sealed class parameter. We recommend that you use a Kotlin when statement when integrating with the SDK. The following are examples of critical states:

Step 4: Handling Deep Linking

The authorization flow brings 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.

To call your app back to the foreground, declare an incoming intent filter on your app’s Android Manifest. When creating a customer request, pass a corresponding redirect URI that uses the SDK.

Example integration

AndroidManifest

1
<intent-filter>
2
    <action android:name="android.intent.action.VIEW" />
3
4
    <category android:name="android.intent.category.DEFAULT" />
5
    <category android:name="android.intent.category.BROWSABLE" />
6
7
    <!-- Register the Cash Pay Kit redirect URI or URL. Change this accordingly in your app. -->
8
    <data
9
        android:scheme="cashapppay"
10
        android:host="checkout" />
11
  </intent-filter>

Step 5: Create a Customer Request

Create a Customer Request as soon as you know the amount you want to charge or if you want to create an on-file payment request. We recommend that you create this request as soon as your checkout view controller loads, so that the Customer can authorize the request immediately.

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 a One-Time Payment

To charge $5.00 as a one-time payment, the create request call might look like this:

1
val redirectUri = "yourapp://return_path"
2
3
val oneTimePayment = OneTimeAction(currency = USD, amount = 123, scopeId = "YOUR SCOPE ID HERE")
4
cashAppPay.createCustomerRequest(oneTimePayment, redirectUri)

Example of an On-File Payment

1
val redirectUri = "yourapp://return_path"
2
3
val onFilePayment = OnFileAction(scopeId = "YOUR SCOPE ID HERE")
4
cashAppPay.createCustomerRequest(onFilePayment, redirectURI)

Example of a Payout

With payouts you can send money to a user’s Cash App account. For mobile development the Pay Kit SDK, the payout workflow is identical to the two above.

1
val redirectUri = "yourapp://return_path"
2
3
val onFilePayout = OnFileAction(scopeId = "YOUR SCOPE ID HERE")
4
cashAppPay.createCustomerRequest(onFilePayout, redirectUri)

Step 6: Authorize the Customer Request

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

Example

1
cashAppPay.authorizeCustomerRequest()

Your app will redirect to Cash App for authorization. When the authorization is completed, your redirect URI is called to open your app. The SDK fetches your authorized request and returns 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 contains a Grants list object associated with it and it can be used with the Cash App Create Payment API. Pass these grants to your backend and call the CreatePayment API as a server-to-server call to complete your payment.