> This page is for Afterpay.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

# Checkout widget

`AfterpayWidgetView` shows the customer's payment schedule: the four installment amounts, when each one is due, and the amount due today. For US merchants, it shows Cash App Afterpay branding.

Use the widget on your order review screen when the order total can still change after checkout, for example because of shipping costs or promo codes. The widget also reports when the customer can't complete the purchase, for example because the order exceeds their Afterpay limit.

The widget is a `WebView` that loads its content from Afterpay, so the device needs an internet connection.

## Before you begin

Set the merchant configuration before you initialize the widget. If the configuration isn't set, the widget throws an `IllegalStateException` when it finishes loading, or when you call `update`. See [UI components](/cash-app-afterpay/guides/sdk/android-sdk/ui-components#configure-the-sdk-first).

## Add the widget

Add the widget to a layout or create it in code:

#### XML

```xml
<com.afterpay.android.view.AfterpayWidgetView
  android:id="@+id/afterpay_widget"
  android:layout_width="match_parent"
  android:layout_height="wrap_content" />
```

#### Kotlin

```kotlin
val widget = AfterpayWidgetView(context)
container.addView(widget)
```

The widget has no XML attributes. It doesn't display anything until you call one of its `init` methods.

The widget resizes to fit its content. Don't constrain it to a smaller size, so that the content stays legible.

## Initialize the widget

Call `init` with one of the following:

* A checkout token: use the token returned by a successful [Built-in UI](/cash-app-afterpay/guides/sdk/android-sdk/present-checkout/built-in-ui) checkout. The widget shows the details of that order.
* An amount: if the customer hasn't completed checkout, or your app doesn't use Built-in UI, pass the order total as a `BigDecimal`.

#### Checkout token

```kotlin
findViewById<AfterpayWidgetView>(R.id.afterpay_widget).init(
  token,
  ::onWidgetExternalLink,
  ::onWidgetUpdate,
  ::onWidgetError,
)
```

#### Amount

```kotlin
findViewById<AfterpayWidgetView>(R.id.afterpay_widget).init(
  BigDecimal("100.00"),
  ::onWidgetExternalLink,
  ::onWidgetUpdate,
  ::onWidgetError,
)
```

If the token is blank, `init` throws an `IllegalStateException`.

### Handle the callbacks

Both `init` methods take three callbacks:

| Parameter           | Signature                                      | Called when                                                  |
| ------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| `onExternalRequest` | `(externalUrl: Uri) -> Unit`                   | The widget tries to open a link. Open the URL in a browser.  |
| `onUpdate`          | `(dueToday: Money, checksum: String?) -> Unit` | The widget loads, and whenever the total changes.            |
| `onError`           | `(error: String) -> Unit`                      | A problem occurs. Don't let the customer complete the order. |

```kotlin
private fun onWidgetExternalLink(url: Uri) {
  startActivity(Intent(Intent.ACTION_VIEW, url))
}

private fun onWidgetUpdate(dueToday: Money, checksum: String?) {
  Log.d(TAG, "Due today: ${dueToday.amount}, checksum: $checksum")
}

private fun onWidgetError(error: String) {
  Log.e(TAG, error)
  // Prevent the customer from completing the order.
}
```

`Money` has two properties: `amount`, a `BigDecimal`, and `currency`, a `java.util.Currency`. The `checksum` identifies the payment schedule that the widget displays.

## Hide the logo or heading

The widget shows the logo and a heading by default. To hide either one, pass `showLogo` or `showHeading` to `init`:

```kotlin
widget.init(
  BigDecimal("100.00"),
  ::onWidgetExternalLink,
  ::onWidgetUpdate,
  ::onWidgetError,
  showLogo = true,
  showHeading = false,
)
```

## Update the total

When the order total changes, for example after the customer picks a shipping option, pass the new total to `update`:

```kotlin
widget.update(BigDecimal("112.50"))
```

The widget calls `onUpdate` with the new amount due today, or `onError` if the new total isn't valid.

## Visibility

The widget hides itself when the SDK isn't enabled for the current configuration. It checks when you call `init` or `update`. See [When components are hidden](/cash-app-afterpay/guides/sdk/android-sdk/ui-components#when-components-are-hidden).

> **The widget manages its own WebView clients**
>
> `AfterpayWidgetView` sets its own `WebViewClient` and `WebChromeClient`. Calls to `setWebViewClient` and `setWebChromeClient` have no effect.