Android SDK

The Afterpay Android SDK presents Afterpay checkout in your Android app and provides prebuilt UI components, such as the payment button and price breakdown. It also lets you accept Cash App Pay through your Afterpay merchant account.

This guide covers installation, configuration, the available checkout integrations, and how to test with the sample app. For the complete SDK reference, see the Android SDK documentation.

Requirements

• Android 7.0 (API level 24) or later

Install the SDK

Add the SDK to your module’s build.gradle.kts or build.gradle file. The SDK uses Java 8+ APIs, so also enable core library desugaring:

android {
  compileOptions {
    isCoreLibraryDesugaringEnabled = true
  }
}
dependencies {
  implementation("com.afterpay:afterpay-android:4.9.0")
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.2")
}

R8 applies the SDK’s shrinking and obfuscation rules automatically. If you use ProGuard, apply the rules in consumer-rules.pro manually.

Configure the SDK

The SDK uses your merchant configuration to render UI components with the correct branding, terms, and currency formatting. Web Redirect, Built-in UI, and Cash App Pay require it. The Afterpay Button uses its own configuration, described in Afterpay Button.

Your server fetches the configuration from the Get Configuration endpoint and passes it to your app:

val configuration = api.getConfiguration()
Afterpay.setConfiguration(
  minimumAmount = configuration.minimumAmount?.amount,
  maximumAmount = configuration.maximumAmount.amount,
  currencyCode = configuration.maximumAmount.currency,
  locale = Locale.US,
  environment = AfterpayEnvironment.SANDBOX,
  consumerLocale = Locale.ENGLISH, // Optional. Overrides the device language.
)

• Call setConfiguration on the main thread, before you start a checkout or initialize any UI component.
• Use AfterpayEnvironment.SANDBOX for development and AfterpayEnvironment.PRODUCTION for release builds. The environment must match the environment your server uses to create checkouts.
• Refresh the configuration about once a day, because your merchant configuration can change.
• A UK locale displays Clearpay branding, terms, and currency formatting.

Present checkout

After you configure the SDK, present checkout in one of four ways:

• Web Redirect: your server creates a checkout, and the SDK loads its redirect URL. The SDK calls this Checkout V1.
• Built-in UI: the SDK opens Afterpay’s checkout right away and asks your app for a token. Supports express checkout. The SDK calls this Checkout V2.
• Afterpay Button: the SDK creates the checkout from your app and returns a one-time virtual card. No server integration. The SDK calls this Checkout V3.
• Cash App Pay: the customer approves the payment in Cash App.

To compare the options, see Present checkout.

UI components

The SDK includes prebuilt components that follow Afterpay brand guidelines. In the US, they show Cash App Afterpay branding.

• Payment button: AfterpayPaymentButton starts an Afterpay checkout.
• Logo: Shows the Afterpay logo.
• Price breakdown: AfterpayPriceBreakdown shows the installment amounts for a price.
• Checkout widget: AfterpayWidgetView shows the payment schedule and keeps it in sync with the order total.

For branding, color schemes, and accessibility, see Android UI components.

Security

To reduce the risk of a man-in-the-middle attack during checkout, pin the certificate for the Afterpay portal with an Android network security configuration. Add a domain configuration to res/xml/network_security_config.xml, and reference the file from your manifest with <application android:networkSecurityConfig="@xml/network_security_config">:

<network-security-config>
  <domain-config cleartextTrafficPermitted="false">
    <domain>portal.afterpay.com</domain>
    <pin-set expiration="YYYY-MM-DD">
      <pin digest="SHA-256">YOUR_PIN_BASE64</pin>
    </pin-set>
  </domain-config>
</network-security-config>

Keep the pins and the expiration date up to date. When the certificate rotates, outdated pins block checkout until the expiration date passes.

Test with the sample app

The sample app uses the example server, which creates sandbox checkouts with your merchant credentials. It includes separate screens for Built-in UI, the Afterpay Button, Cash App Pay with the Afterpay Button, and the UI components.

1. Start the example server. It requires Node.js and listens on http://localhost:3000. In .env, set AFTERPAY_MERCHANT_ID and AFTERPAY_SECRET_KEY to your sandbox credentials, and set AFTERPAY_REGION, for example en-US.

   git clone https://github.com/afterpay/sdk-example-server.git
   cd sdk-example-server
   cp .env.example .env
   npm install
   npm run build
   npm run start

2. Clone the SDK and add your merchant ID to local.properties in the project root. The sample uses it as the shopDirectoryMerchantId for the Afterpay Button.

   merchantId="your_merchant_id"

3. Run the sample module on an Android emulator. The sample connects to the example server at http://10.0.2.2:3000, which is the emulator’s address for your computer. To use a different address, change MERCHANT_API_BASE_URL in sample/src/main/java/com/example/api/MerchantApi.kt.

4. Start a checkout and log in with a sandbox customer account. For details, see Test environments.