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

# Adding the Express Checkout Button

You must show an Afterpay or Clearpay (UK) checkout button on your cart and/or product pages to enable Express Checkout. When clicked, the checkout button starts the checkout process in a popup flow.

## Options for the Express Checkout Buttons

There is a selection of buttons available for each stage of the checkout. Each button clearly shows the customer what the following action is. Examples of these buttons are:

**Product Page/Shopping Cart**

\


**Order Placement**

\


**Product Page/Shopping Cart - US Only**

\


**Order Placement - US Only**

\


**Product Page/Shopping Cart - UK Only**

\


**Order Placement - UK Only**

\


## Changing the Appearance

| Attribute | Value   | Preview |
| :-------- | :------ | :------ |
| text      | Buy-now |         |
| text      | Pay-now |         |

### Examples

```html
<afterpay-button text="buy-now" merchantpublickey="..." ></afterpay-button>
```

```html
<afterpay-button text="pay-now" merchantpublickey="..." ></afterpay-button>
```

---

> **Default values**
>
> When the `text` attribute is not provided, the button displays the "Buy now with Afterpay" option.

## 1. Import the JavaScript

Import the AfterpayButton.js script as a script tag.

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

## 2. Add the Afterpay Button Element

Insert the following HTML to initialize the afterpay-button element.\
You will need your merchant public key, which is provided by Afterpay. Your public key is used solely to identify your account with Afterpay. They aren’t secret. In other words, they can safely be published in places like your JavaScript code, or in an Android or iPhone app.

```javascript
<afterpay-button 
merchantPublicKey="d2da7000bb4811eb85290242ac130003"></afterpay-button>
```

## 3. Configure the Afterpay Button Element for Express Checkout

Afterpay can be launched from different entry points (product-page, mini-cart, cart) in the customer journey. To enable the express checkout flow, set the following attributes:

```javascript
<afterpay-button
  type="express" // determines checkout type
  afterpayEntryPoint="cart" // options include "product-page", "mini-cart", and "cart"
  afterpayCheckoutButtonLabel="Express Checkout"                
merchantPublicKey="d2da7000bb4811eb85290242ac130003"
  >
    Express Checkout
</afterpay-button>
```

## 3. Set Order Attributes

Before a customer can checkout with Afterpay, we need to know, at a minimum:

* `Merchant Reference` - The merchant’s unique order id/reference that this payment corresponds to. This is used to reconcile orders in the Afterpay merchant portal.
* `Amount` - The total amount of the order to be charged to the customer. This includes any shipping and tax, minus any discounts. This is the maximum amount that you can charge to the virtual Visa Card.
* `Currency` - The currency in ISO 4217 format. The value provided must correspond to the currency of the Merchant account making the request.
* `Consumer details` - The customer's phone number, name, and email address
* `Shipping details` - The shipping name and shipping address
* `Items` - This contains information about the line items in the order.

```javascript
const afterpayButton = document.getElementsByTagName('afterpay-button')[0];
afterpayButton.addEventListener('click', 
    function (e) {
        afterpayButton.merchantReference= "";
        //Money Object 
        afterpayButton.amount= "";
        afterpayButton.currency= "";
        //Item Object
        afterpayButton.items= JSON.stringify(lineItems);
        //Consumer Object 
        afterpayButton.consumerPhoneNumber= "";
        afterpayButton.consumerGivenNames= "";
        afterpayButton.consumerSurname= "";
        afterpayButton.consumerEmail= "";
        //Contact Object 
        afterpayButton.shippingName= "";
        afterpayButton.shippingLine1= "";
        afterpayButton.shippingLine2= "";
        afterpayButton.shippingArea1= "";
        afterpayButton.shippingArea2= "";
        afterpayButton.shippingRegion= "";
        afterpayButton.shippingPostcode= "";
        afterpayButton.shippingCountryCode= "";
        afterpayButton.shippingPhoneNumber= "";
        // In-Store Pickup
        afterpayButton.instorePickup = false;

        //Contact Object 
        afterpayButton.billingName= "";
        afterpayButton.billingLine1= "";
        afterpayButton.billingLine2= "";
        afterpayButton.billingArea1= "";
        afterpayButton.billingArea2= "";
        afterpayButton.billingRegion= "";
        afterpayButton.billingPostcode= "";
        afterpayButton.billingCountryCode= "";
        afterpayButton.billingphoneNumber = "";
  
        // Buy Now Flag (Changes the button text displayed in the Afterpay Checkout)
        afterpayButton.buyNow = true; 
    }, true
);
```

> **Buy Now Flag**
>
> This shows the customer a “Buy Now” button at the end of the Afterpay checkout flow
>
> <details>
>   <summary>
>     View Example
>   </summary>
>
>   When this flag is not set the button displays "Confirm"
> </details>
>
> **Increase Conversion Rates**
>
> Providing customer details allows new customers to speed through checkout with prepopulated name and address fields.

## Object Types

### In-Store Pickup

If the customer has chosen to pick up the order in a store, no shipping address is required, instead, set `instorePickup` to true.

### Money object

| Attribute  | Type              | Description                                                                                                                                                                                                                            |
| :--------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`   | string `required` | The amount is a string representation of a decimal number rounded to 2 decimal places.                                                                                                                                                 |
| `currency` | string `required` | The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported values include "AUD", "USD", and "CAD". However, the value provided *must* correspond to the currency of the Merchant account making the request. |

### Item object

This contains information about a line item in the order. The value given to the `afterpayButton.items`  is a string. To pass line item details an array of item objects should be provided using JSON.stringify.\
`afterpayButton.items= JSON.stringify(itemsArray);`

**`Example Item Object`**

```javascript Example Item Object
{
  "name": "Blue Carabiner",
  "sku": "12341234",
  "quantity": 1,
  "pageUrl": "https://merchant.example.com/carabiner-354193.html",
  "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
  "price": {
    "amount": "40.00",
    "currency": "USD"
  },
  "categories": [
    ["Sporting Goods", "Climbing Equipment", "Climbing", "Climbing Carabiners"],
    ["Sale", "Climbing"]
  ],
  "estimatedShipmentDate": "2021-03-01"
}
```

| Attribute               | Type                               | Description                                                                                                                                                                                             |
| :---------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                  | string `required`                  | Product name. Limited to 255 characters.                                                                                                                                                                |
| `sku`                   | string                             | Product SKU. Limited to 128 characters.                                                                                                                                                                 |
| `quantity`              | integer `required`                 | The quantity of the item, stored as a signed 32-bit integer.                                                                                                                                            |
| `pageUrl`               | string                             | The canonical URL for the item's Product Detail Page. Limited to 2048 characters.                                                                                                                       |
| `imageUrl`              | string                             | A URL for a web-optimised photo of the item, suitable for use directly as the `src` attribute of an `img` tag. Limited to 2048 characters.                                                              |
| `price`                 | [Money](#money-object)  `required` | The unit price of the individual item. Must be a positive value.                                                                                                                                        |
| `categories`            | \[]\[]                             | An array of arrays to accommodate multiple categories that apply to the item. Each array represents a hierarchical path to a category, with the left-most category being the top-level parent category. |
| `estimatedShipmentDate` | string                             | The estimated date when the order is shipped, in `YYYY-MM` or `YYYY-MM-DD` format.                                                                                                                      |

### Consumer object

| Attribute     | Type              | Description                                                                |
| :------------ | :---------------- | :------------------------------------------------------------------------- |
| `phoneNumber` | string            | The customer’s phone number. Limited to 32 characters.                     |
| `givenNames`  | string            | The customer’s first name and any middle names. Limited to 128 characters. |
| `surname`     | string            | The customer’s last name. Limited to 128 characters.                       |
| `email`       | string `required` | The customer’s email address. Limited to 128 characters.                   |

### Contact Object

| Attribute     | Type              | Description                                                                                                                           |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string `required` | Full name of contact. Limited to 255 characters                                                                                       |
| `line1`       | string `required` | First line of the address. Limited to 128 characters                                                                                  |
| `line2`       | string            | Second line of the address. Limited to 128 characters.                                                                                |
| `area1`       | string            | US: City CA: City Limited to 128 characters                                                                                           |
| `area2`       | string            | UK: village or local area Limited to 128 characters                                                                                   |
| `region`      | string            | US: State CA: Province or Territory Limited to 128 characters                                                                         |
| `postcode`    | string            | [ZIP](https://en.wikipedia.org/wiki/ZIP_Code) or [postal code](https://en.wikipedia.org/wiki/Postal_code). Limited to 128 characters. |
| `countryCode` | string `required` | The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. Limited to 2 characters                                      |
| `phoneNumber` | string            | The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format. Limited to 32 characters.                                   |

## 5. Set express checkout attributes

Within the listener event, attach an expressCheckout object attribute with the following configurations:

* Set `region` to the two-character ISO 3166-1 country code of the Merchant account

* Set the flag `shippingOptionRequired` to:
  * `false`: if shipping options are not required to be displayed in the Express Checkout flow
  * `true`: if you intend to provide shipping options to to the customer within the Express Checkout flow (i.e. Integrated Shipping). This is the default value

* Handle lifecycle events:
  * onComplete: see The onComplete Callback section below for more details

**`Example with Deferred Shipping`**

```javascript Example with Deferred Shipping
const afterpayButton = document.getElementsByTagName('afterpay-button')[0];
afterpayButton.addEventListener('click', 
    function (e) {
         // ...all attributes listed in step 4 above,
         afterpayButton.expressCheckout = {
           region: 'US',
           onComplete: function (data) {
            /* handle success/failure of checkout */
           },
           shippingOptionRequired: false
         }

    }, true
);
```

> **Note**
>
> The information on this page also applies to Clearpay (UK).