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)
• 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.

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.

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:

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, 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:

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

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

1
cashAppPay.registerForStateUpdates(this)

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

1
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:

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 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 :

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

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:

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)

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

1
val redirectUri = "yourapp://return_path"
2
3
val onFilePayment = OnFileAction(scopeId = "YOUR SCOPE ID HERE")
4
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

1
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. 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:

1
<app.cash.paykit.core.ui.CashAppPayButton
2
      style="@style/CAPButtonStyle.Light"
3
      android:layout_height="54dp"
4
      android:layout_width="match_parent"
5
      />

Light-background Button:

1
<app.cash.paykit.core.ui.CashAppPayButton
2
      style="@style/CAPButtonStyle.Dark"
3
      android:layout_height="54dp"
4
      android:layout_width="match_parent"
5
      />

Dark-background Button:

Pay Kit Android: Advanced Operations

This page describes advanced operations for the Cash App Pay Android SDK. For most setups, see Getting Started 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.

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:

1
cashAppPay.startWithExistingCustomerRequest(customerRequestID)

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:

1
fun updateCustomerRequest(
2
    requestId: String,
3
    paymentAction: CashAppPayPaymentAction,
4
)