> This page is for Afterpay Button Documentation.

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

# Getting Started

Cash App Pay is a supported payment method through Afterpay.

> **Note**
>
> Cash App Pay is currently **only** available in the United States. If you are an Australian, Canadian, or United Kingdom merchant, ignore this Cash App Pay section of the guide.

## Differences between Cash App Pay and Afterpay

It is important to understand the distinction between Cash App Pay and Afterpay.

Key Differences:

* Cash App Pay allows customers to pay in a single transaction

* Afterpay enables customers to split payments into installments

**Cash App Pay**

A digital payment feature that allows customers to make secure, contactless payments in stores or online from their Cash App balance or linked bank accounts.

**Afterpay**

A buy now, pay later service that allows customers to split payments into four interest-free installments every six weeks.

## Implement Cash App Pay

To enable Cash App Pay, do the following:

1. Ensure that you are using the latest`afterpay-button.js`.

   [Production](https://static.afterpay.com/afterpay-button.js) | [Sandbox](https://static-us.afterpay.com/javascript/button/afterpay-button.js)

   ```html
   <script src="https://static-us.afterpay.com/javascript/button/afterpay-button.js" type="text/javascript"></script>
   ```

2. Add a Cash App Pay Button Element.

   Identical to the Afterpay Button but with an additional `isCashAppPay` parameter:

   ```html
   <afterpay-button isCashAppPay merchantPublicKey="abaa2250913d4db38..."></afterpay-button>
   ```

3. Bind the same order attributes for both Afterpay and Cash App Pay

   a. Managed UI:\*\*\
   [Bind the attributes](/afterpay-button-documentation/guides/afterpay-button/getting-started/add-the-button#3-set-order-attributes) then call `afterpayButton.initializeForCashAppPay`.

   or

   b. [Advanced Rendering Controls](/afterpay-button-documentation/guides/cash-app-pay/advanced-rendering-control):\*\*\
   [bind the attributes on the click event or within](/afterpay-button-documentation/guides/afterpay-button/getting-started/add-the-button#3-set-order-attributes) `afterpayButton.renderCashAppPayButton`.

```javascript
const afterpayButtons = document.querySelectorAll('afterpay-button');
afterpayButtons.forEach(afterpayButton => {
  /* a.) Managed UI */
  if (afterpayButton.hasAttribute("isCashAppPay")) {
    bindAttributesToButton(afterpayButton);
    afterpayButton.initializeForCashAppPay({
      // button style configurations
      button: {
        size: 'small', // "medium" | "small"
        width: 'full', // "full" | "static"
        theme: 'dark', // "dark" | "light"
        shape: 'round' // "round" | "semiround"
      },
      // mobile redirect
      redirectConfirmUrl: 'https://appsp-sandbox.afterpay-test.repl.co/button',
      // error callback handler
      onError: function(event) {
        console.log(`onError: ${JSON.stringify(event.data, null, 4)}`);
      },
      // event.data includes the same virtual card object + the customer's cashtag
      onComplete: function(event) {
          const { status, virtualCard, token, cashtag } = event.data;
        },
      eventListeners: {
        CUSTOMER_INTERACTION: ({ isMobile }) => {
          if (isMobile) {
            console.log(`Customer is on mobile`);
          } else {
            console.log(`Customer is not on mobile`);
          }
        },
        CUSTOMER_REQUEST_DECLINED: () => {
          console.log(`CUSTOMER_REQUEST_DECLINED`);
        },
        CUSTOMER_REQUEST_APPROVED: () => {
          console.log(`CUSTOMER_REQUEST_APPROVED`);
        },
        CUSTOMER_REQUEST_FAILED: () => {
          console.log(`CUSTOMER_REQUEST_FAILED`);
        },
        CUSTOMER_DISMISSED: () => {
          console.log(`CUSTOMER_REQUEST_FAILED`);
        }
      }
    });
  }
  /* b.) Advanced Rendering Controls */
  // bind the attributes on click for both Afterpay Button and Cash App Pay Button
  afterpayButton.addEventListener('click', bindAttributesToButton(afterpayButton), true);
  afterpayButton.hasAttribute("isCashAppPay") && renderCashAppPayButton(afterpayButton);
})
```

## Process the Credit Card using `onComplete`

Process the credit card using the `onComplete` callback, which returns the [virtual card object](/afterpay-button-documentation/guides/afterpay-button/getting-started/process-the-credit-card) and the customer's cashtag.

## Handling Customer Request Changes

Customer Requests may fail due to premature exits or risk-based declines. Use `eventListeners` to manage state changes on your frontend.

> **Note**
>
> If a request fails or is declined, dispay an error message such as: `Could not link Cash App Pay. Please try again or choose a different payment method.`

```javascript
afterpayButton.initializeForCashAppPay({
  // All other configurations
  eventListeners: {
    CUSTOMER_INTERACTION: (CustomerInteractionData) => {
      const { isMobile } = CustomerInteractionData;
      console.log("CUSTOMER_INTERACTION is on mobile: ", isMobile);
    },
    CUSTOMER_REQUEST_DECLINED: () => {
      console.log(`CUSTOMER_REQUEST_DECLINED`);
    },
    CUSTOMER_REQUEST_APPROVED: (CustomerRequestData) => {
      console.log(`CUSTOMER_REQUEST_APPROVED`);
      console.log("Customer Request Approved Data: ", CustomerRequestData);
    },
    CUSTOMER_REQUEST_FAILED: () => {
      console.log(`CUSTOMER_REQUEST_FAILED`);
    },
    CUSTOMER_DISMISSED: () => {
      console.log(`CUSTOMER_REQUEST_FAILED`);
    }
  }
});
```

### Event Listener Parameters

| Name   | Type                                                                                                                                            | Description |
| :----- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
| `type` | `"CUSTOMER_INTERACTION"` \| `"CUSTOMER_DISMISSED"` \| `"CUSTOMER_REQUEST_APPROVED"` \| `CUSTOMER_REQUEST_DECLINED` \| `CUSTOMER_REQUEST_FAILED` | event type  |

##### Customer Interaction Data

| Name       | Type      | Description                                   |
| :--------- | :-------- | :-------------------------------------------- |
| `isMobile` | `boolean` | `true` if the customer is on a mobile device. |

##### CustomerRequestData

| Name              | Type                                          | Description                             |
| :---------------- | :-------------------------------------------- | :-------------------------------------- |
| `customerProfile` | `Customer`                                    | Customer details.                       |
| `grants`          | `Partial<Record<keyof Actions, GrantDetail>>` | Payment grant details.                  |
| `referenceId`     | `string`                                      | A reference to the checkout identifier. |

##### Customer

The Cash App customer who approved the request.

| Name      | Type     | Description                          |
| :-------- | :------- | :----------------------------------- |
| `cashtag` | `string` | Public Cash App identifier.          |
| `id`      | `string` | Unique identifier for this customer. |

##### Grants

| Name        | Type     | Description            |
| :---------- | :------- | :--------------------- |
| `expiresAt` | `Date`   | Grant expiration date. |
| `grantId`   | `string` | Grant ID for payment.  |

## Payment reversals with Cash App

Cash App sales support the standard Afterpay payment reversal process.

## Settlement with Cash App

Afterpay handles all payment resolutions, with settlement information available as usual.