> 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.
# Add The Button
We provide two buttons, one is a sandbox button for testing. The other is a production button for live use.
## Import the JavaScript
This script tag is used to load Afterpay's button JavaScript SDK into a webpage. Import the `AfterpayButton.js` script as a script tag.
Test your integration with the Sandbox Button. When you're satisfied, switch to the Production Button.
**Sandbox Button**
**`Sandbox`**
```html Sandbox
```
**Production Button**
**`Production`**
```html Production
```
> **Note**
>
> All regions load the same `afterpay-button.js` script URL script The differentiation occurs through the region attribute in the afterpay-button element.
## Add the Afterpay Button Element
Insert the following HTML to initialize the `afterpay-button` element.
You need your merchant public key, provided by Afterpay. Public keys are safe to publish in JavaScript code or mobile applications.
```html
```
### Region Specific Configuration
If you are a merchant based in Australia, or the United Kingdom, include `region="AU"` or `region="UK"`. Merchants in the United States or Canada do not need a regional setting.
### Changing the appearance of the button - optional
See the [Changing the Appearance](/afterpay-button-documentation/guides/afterpay-button/getting-started/changing-the-appearance) page to cutomize the button.
## 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 (US, UK, and Canada) or the virtual Mastercard (Australia)
* `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 (CTA button)
afterpayButton.buyNow = true;
// Custom fields (optional)
afterpayButton.custom = {
"flightDetails":{
"origin":"SFO"
}
}
}, true
);
```
**Buy Now Flag**
Enabling `buyNow = true` shows a **Buy Now** button at checkout. If not set, the button displays **Confirm** instead.
**Increase Conversion Rates**
Providing customer details speeds up checkout by pre-filling name and address fields.
## Object Types
### In-Store Pickup
If the customer chooses in-store pickup, no shipping address is needed. Instead, set `instorePickup = true`.
### Money Object
| Attribute | Type | Description |
| :--------- | :---------------- | :------------------------------------------------------------------------- |
| `amount` | string `required` | Amount formatted as a decimal string, rounded to two places. |
| `currency` | string `required` | The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. |
### Item object
| 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. |
| `givenNames` | string | The customer’s first name and any middle names. |
| `surname` | string | The customer’s last name. |
| `email` | string `required` | The customer’s email address. |
### Contact Object
| Attribute | Type | Description |
| ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
| `name` | string `required` | Full name. |
| `line1` | string `required` | Address line 1. |
| `line2` | string | Address line 2. |
| `region` | string | Region or state. |
| `postcode` | string | [ZIP](https://en.wikipedia.org/wiki/ZIP_Code) or [postal code](https://en.wikipedia.org/wiki/Postal_code). |
| `countryCode` | string `required` | The [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. |
| `phoneNumber` | string | Contact phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format. |
> **Note**
>
> The information on this page also applies to Clearpay (UK).