Using the Clearpay API

The Clearpay checkout widget

The Checkout Widget is a component that needs to be placed on your site if the order value is subject to change after the Express Checkout flow. It displays the customer payment schedule and can be updated as the total changes (e.g. in response to shipping costs and promo codes).

It can be used to enable dynamic order total updates on a review page for both Express Checkout and standard Clearpay Checkout.

It serves several purposes:

  • To ensure the customer has seen and agreed to an accurate payment schedule.
  • To verify that the final amount captured matches what the customer has seen.
  • To provide information to the merchant such as the first payment amount for display purposes.
  • To inform the merchant of any barriers to purchase, for instance the customer having gone over their payment limit with Clearpay.

Rendering the Checkout Widget

The widget can be rendered into a target container on your page using Javascript. It is responsive and will fit any container with a minimum width of 300 pixels.

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',
9         target: '#clearpay-widget-container',
10         locale: 'en-GB', 
11         onReady: function (event) {
12           // Fires when the widget is ready to accept updates.  
13         },
14         onChange: function (event) {
15           // Fires after each update and on any other state changes.
16           // See "Getting the widget's state" for more details.
17         },
18         onError: function (event) {
19           // See "Handling widget errors" for more details.
20         },
21       })
22     }
23   </script>
24   <script src="https://portal.sandbox.clearpay.co.uk/afterpay.js?merchant_key=YOUR-PUBLIC-KEY" async onload="createAfterpayWidget()">
25   </script>
26 </body>
27</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.

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

Getting the Widget’s State

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

PropertyTypeDescription
isValidBooleanWhether the order is okay to proceed. If false, the order should be prevented from completing.
amountDueTodayMoneyThe amount owing today. Displaying this value in your Order Summary will give the customer more confidence when placing their order.

amountDueToday.format() will return a formatted string which can easily be displayed in your UI.
paymentScheduleChecksumStringA unique value representing the payment schedule that must be provided when capturing the order.
errorStringA string representing 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 calling Confirm Checkout. The widget itself informs the customer 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, e.g.:

1var isValid = afterpayWidget.isValid
2var amountDueToday = afterpayWidget.amountDueToday
3var paymentScheduleChecksum = afterpayWidget.paymentScheduleChecksum
4var error = afterpayWidget.error

Handling Widget Errors

Any errors on the widget will trigger the onError callback with an HTML event as described above, and will have an isValid state of false. This event is in addition to the onChange callback, and is provided for convenience - it is not necessary to respond to onError events as long as all onChange events are handled.

Standard Checkout - Tokenless Mode

If the Checkout Widget loads before the customer completes the Clearpay checkout flow, problems can occur. The solution is to launch the Checkout Widget in “Tokenless mode” - which is a standard checkout.

To start the Checkout Widget in tokenless mode, do the following:

  1. Define an amount property in the initialisation configuration.

  2. Do not define a token property in the initialisation configuration.

  3. Place an initial amount update in the onReady callback to initialise the widget. For example:

1new AfterPay.Widgets.PaymentSchedule({
2 //token: "",
3 amount: { amount: "50", currency "USD"},
4 target: '#afterpay-widget-container',
5 // ...Rest of configuration...
6 })
7 afterpayWidget.update({
8 amount: { amount: "50.00", currency: "USD"},
9 })
Example Code Snippet

Click here for a working example code snippet.

  1. The rest of the Checkout Widget is the same as described on this page.

Style options for the checkout widget

Afterpay provides an optional style attribute that you can use to toggle widget features on or off. The styles that can currently be toggled are as follows:

  • border: if false, the border around the widget container will be removed. Default: true
  • Heading: if false, the heading “Your 4 interest-free payments” will be removed. Default: true
  • logo: if false, the Afterpay logo will be removed. Default: true
1window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
2  // ...
3    style: {
4        border: true, 
5        heading: true, 
6        logo: true, 
7   }
8  // ...
9});