Display the checkout widget

Use the checkout widget to display the Clearpay payment schedule on your website. There are two ways to use the widget:

Connected: Displayed after the checkout process, using an order token. If the order amount changes post-checkout, use the connected widget to update the payment schedule
Unconnected: Displayed before the customer starts the checkout process, with no order token—just an amount

The widget is responsive and can fit into any container with a minimum width of 300px. You can render the widget into a target container on your page using JavaScript.

Use the connected widget on your checkout page after a customer completes the Clearpay checkout flow. This widget serves several purposes:

Ensures that the customer sees and agrees to an accurate payment schedule.
Verifies that the final amount charged matches what the customer was shown during checkout.
Provides the merchant with important information, like the first payment amount.
Informs the merchant if there are any barriers to purchase, such as exceeding the Clearpay payment limit.

Important: Only show the connected widget after the customer has successfully completed the Clearpay checkout (when the onComplete status is SUCCESS). You must display the connected widget during the Deferred Shipping flow.

The connected widget requires:

The Clearpay checkout token to retrieve and render the payment schedule.
The final order amount

1 <html>
2  <body>
3    <div id="clearpay-widget-container"></div>
4    <script>
5      // Ensure this function is defined before loading afterpay.js
6      function createAfterpayWidget () {
7        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8          token: 'YOUR_TOKEN', // required
9          amount: { amount: "123.45", currency: "GBP" }, // required, amount of the total order post checkout, must be a positive value
10          target: '#clearpay-widget-container',
11          locale: 'en-GB', 
12          onReady: function (event) {
13            // Fires when the widget is ready to accept updates.
14            // An initial call to "update" must be made here.
15          },
16          onChange: function (event) {
17            // Fires after each update and on any other state changes.
18            // See "Getting the widget's state" for more details.
19          },
20          onError: function (event) {
21            // See "Handling widget errors" for more details.
22          },
23        })
24      }
25    </script>
26    <script src="https://global-api-sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
27    </script>
28  </body>
29 </html>

Updating the Order Total

Any time the order total changes (e.g. a change of shipping option, promo code, or cart contents), the widget must be notified of the new amount. An initial update must also be performed in the onReady callback to initialize the widget.

1 afterpayWidget.update({
2  amount: { amount: "123.45", currency: "GBP" },
3 })

Because you can update the order after checkout has completed, the connected widget has unique considerations. When calling the /v2/payments/capture API, the payload must contain the required amount field plus additional properties. This allows Clearpay to verify that the final order amount and payment schedule match the calculated values from the corresponding order details. These properties are:

isCheckoutAdjusted: Indicates whether any changes have been made to the order since the initial creation
items: The list of order items if it has changed
shipping: The shipping address if it has changed
paymentScheduleChecksum: The latest paymentScheduleChecksum retrieved from your widget’s onChange call (see ‘Getting the widget’s state’).

1 curl --request POST  
2   --url https://global-api-sandbox.afterpay.com/v2/payments/capture  
3   --header 'accept: application/json'  
4   --header 'content-type: application/json'  
5   --data '{"token":"YOUR_TOKEN", "amount":{"amount":"10.00", "currency": "GBP"},  "isCheckoutAdjusted":true, "shipping":{"name":"Joe Customer","line1":"123 Fake Street", "postcode":"SW1A 1AA", "region":"London", "countryCode":"GB"}, "items":[{"price":{"amount":"10.00", "currency":"GBP"}, "name":"item1", "quantity":1}], "paymentScheduleChecksum":"YOUR_PAYMENT_SCHEDULE_CHECKSUM" }'

Important: If the final amount doesn’t match the calculated amount (including shipping, taxes, etc.), or if the paymentScheduleChecksum doesn’t match the calculated payment schedule, the capture request will be rejected.

Property	Type	Description
`token`	String (required)	The token returned in the Create Checkout request.
`amount`	Money (required)	Amount to be checked against the amount including shipping and taxes. If the amounts do not match, the request is rejected.
`merchantReference`	String	Order ID or reference this order corresponds to.
`isCheckoutAdjusted`	Boolean	Whether there have been changes to the order since the initial order creation.
`paymentScheduleChecksum`	String	A unique value representing the payment schedule that must be provided when there has been changes since the initial order creation.
`items`	Item	An array of order items that have been updated to be provided if it has changed since the initial order creation.
`shipping`	Contact	The shipping address for this order to be provided if it has changed since the initial order creation.

Getting the widget’s state

After each update and on any other state changes, the onChange callback is called with an HTML event argument. At this point the widget’s state is retrieved from event.data, which will have the properties in the table:

Property	Type	Description
`isValid`	Boolean	Whether the order is okay to proceed. If false, the order should be prevented from completing.
`amountDueToday`	Money	The amount owing today. Displaying this value in your Order Summary will give your customer more confidence when they place their order. `amountDueToday.format()` returns a formatted string that you can easily display in your UI.
`paymentScheduleChecksum`	String	A unique value representing the payment schedule that must be provided when capturing the order.
`error`	Error	The current error state, if any.

We recommend using the isValid and amountDueToday states to update your checkout UI as described above, and persisting the paymentScheduleChecksum on your backend to be used when capturing. The widget itself informs customers what has gone wrong when isValid is false.

In addition to the onChange callback, these states are exposed as properties on the widget and can be accessed directly at any time, for example:

var isValid = afterpayWidget.isValid
var amountDueToday = afterpayWidget.amountDueToday
var paymentScheduleChecksum = afterpayWidget.paymentScheduleChecksum
var error = afterpayWidget.error

Property	Type	Description
error	Error	Representing the current error state, if any.

Any errors on the widget trigger the onError callback with an HTML event (see table below), and have a false isValid status.

If the onChange callback is activated and fails due to an error, the onError event is also triggered for convenience. In this case, a response to onError events is not needed, provided all onChange events are handled.

`onError` event.data properties table

Property	Type	Description
`isValid`	Boolean	Whether the order is okay to proceed. For the `onError` event this will be false so prevent the order from completing.
`type`	String	For an `onError` event, the type is set to the value of error.
`error`	Error	Represents the current error state.

If you are getting errors during the rendering of the widget, open the browser console. The console may display some additional error loggings to help identify some common integration misconfigurations.

Use the unconnected widget on your checkout page before the customer starts the Clearpay checkout flow. This version of the widget displays an estimated payment schedule based on the initial order amount; this is only an approximation based on the initial order total.

The unconnected widget requires a defined positive amount to calculate the estimated payment schedule.

If the order total changes (due to shipping method, promo code, or cart contents), the widget must be notified of the new amount. Only call the update function after the widget’s onReady callback has been triggered.

1 <html>
2  <body>
3    <div id="clearpay-widget-container"></div>
4    <script>
5      // Ensure this function is defined before loading afterpay.js
6      function createAfterpayWidget () {
7        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8          amount: { amount: "123.45", currency: "GBP" }, // required, must be a positive value
9          target: '#clearpay-widget-container',
10          locale: 'en-GB', 
11          onReady: function (event) {
12            // Fires when the widget is ready to accept updates.
13            // An initial call to "update" must be made here.
14          },
15          onChange: function (event) {
16            // Fires after each update and on any other state changes.
17            // See "Getting the widget's state" for more details.
18          },
19          onError: function (event) {
20            // See "Handling widget errors" for more details.
21          },
22        })
23      }
24    </script>
25    <script src="https://global-api-sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
26    </script>
27  </body>
28 </html>

The default version of the Standard Payment Schedule widget displays accurate payment schedule information, the payment amount due today, and the legal disclaimer. Note that the below images show the widget used with a grant.

Here’s an example of how to initialize the standard widget, and a sample function for updating the amount to a new value.

1 <html>
2   <body>
3     <div id="clearpay-widget-container"></div>
4     <script>
5       // Ensure this function is defined before loading afterpay.js
6       function createAfterpayWidget () {
7         window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8           target: '#clearpay-widget-container',
9           locale: 'en-GB',
10           amount: {
11             amount: "1338.00",
12             currency: "GBP"
13           },
14           // Use your payment schedule token to reflect an accurate payment schedule to your customers
15           paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
16         })
17       }
18 
19       function updateAmount() {
20         window.afterpayWidget.update(
21             amount: { amount: "1000.00", currency: "GBP" }
22         )
23       }
24     </script>
25     <script src="https://global-api.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
26     </script>
27 
28     <button onclick="updateAmount()">Update amount</script>
29   </body>
30 </html>

This is a more compact version of the Payment Schedule widget. It presents the same information as the standard widget, but takes up less space.

Here’s an example:

1 <html>
2   <body>
3     <div id="clearpay-widget-container"></div>
4     <script>
5       // Ensure this function is defined before loading afterpay.js
6       function createAfterpayWidget () {
7         window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8           target: '#clearpay-widget-container',
9           locale: 'en-GB',
10           amount: {
11             amount: "1338.00",
12             currency: "GBP"
13           },
14           style: {
15              theme: "TIMELINE"
16           },
17           // Use your payment schedule token to reflect an accurate payment schedule to your customers
18           paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
19         })
20       }
21     </script>
22     <script src="https://global-api.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
23     </script>
24   </body>
25 </html>

Style attributes

There is an optional style attribute that you can use to toggle particular features on or off in the widget. The current styles are:

border - If false, the border around the widget container is removed. Default: true
heading - If false, the heading “Your 4 interest-free payments” is removed. Default: true
logo - If false, the Clearpay logo is removed. Default: true
theme (string) - allows you to customize the look of the widget. Following themes are available ‘CLASSIC’ | ‘TIMELINE’ | ‘COLLAPSIBLE’ | ‘MODAL’. Default: ‘CLASSIC’

Here are some theme examples:

Timeline A compact timeline view of the payment schedule.

Collapsible A collapsed view that can be expanded to show full details.

Collapsible (extended) The expanded view showing all payment details.

Modal A modal trigger that opens payment details in an overlay.

Modal (open) The opened modal displaying the full payment schedule.

Code example:

window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
  // ...
    style: {
        border: true, 
        heading: true, 
        logo: true,
        theme: 'TIMELINE', // 'COLLAPSIBLE''MODAL'
   }
  // ...
});

Property	Type	Description
error	Error	Representing the current error state, if any.

Any errors on the widget trigger the onError callback with an HTML event (see table below), and have a false isValid status.

`onError` event.data properties table

Property	Type	Description
`isValid`	Boolean	Whether the order is okay to proceed. For the `onError` event this will be false so prevent the order from completing.
`type`	String	For an `onError` event, the type is set to the value of error.
`error`	Error	Represents the current error state.

Connected widget

Updating the Order Total

Capturing payment with the connected widget

Getting the widget’s state

Handling widget errors

`onError` event.data properties table

Unconnected widget

Styling the checkout widget

Standard widget

Compact widget

Style attributes

Handling widget errors

`onError` event.data properties table

Connected widget

Updating the Order Total

Capturing payment with the connected widget

Getting the widget’s state

Handling widget errors

onError event.data properties table

Unconnected widget

Styling the checkout widget

Standard widget

Compact widget

Style attributes

Handling widget errors

onError event.data properties table

`onError` event.data properties table

`onError` event.data properties table