Setup

To use Clearpay Express Checkout, you must show a Clearpay checkout button on your cart and/or product pages. When clicked, the Clearpay checkout button starts the checkout process in either a popup or a redirect flow.

Options for the Express Checkout button

There is a selection of buttons available for each stage of the checkout. Each button clearly shows the customer what the next action will be. These buttons are:

Product Page/Shopping Cart

Order Placement

📘

Note

Contact your Clearpay merchant services representative to get integration assets, like the buttons above, for Express checkout.

Create the Clearpay Express Checkout Button

Do the following:

1. Render an Clearpay checkout button on your web page.
2. Assign an ID (for multiple checkout buttons on the same page see Targeting multiple checkout buttons.

<button id="afterpay-express-button">
  Checkout using Clearpay Express
</button>

Add data attributes to the checkout button

To enable a smart Express checkout flow and increase the chance of conversion, add the following data attributes:

Add an Express Checkout Entry Point

Express Checkout can start from different entry points depending on where the customer is in their journey. Set the data-afterpay-entry-point attribute on the button to one of the following:

• product-page
• mini-cart
• cart

For example, to render a button for Express that sets the entry point to mini-cart:

<button id="afterpay-express-button"                     
        data-afterpay-entry-point="mini-cart”>
  Checkout using Clearpay Express
</button>

Add an Express Checkout Button Label

Customers can start Express Checkout from multiple buttons on your page. Set the data-afterpay-checkout-button-label attribute on the button with the label name for that button. For example:

<button id="afterpay-express-button"                     
        data-afterpay-checkout-button-label="Checkout using Clearpay Express”>
  Checkout using Clearpay Express
</button>  

Targeting Multiple Checkout Buttons

If you have multiple checkout buttons on the same page, you can target these by adding a common class to each of these buttons. For example:

<button class="afterpay-express-button”>
  Button 1 - Checkout using Clearpay Express
</button>
<button class="afterpay-express-button”>
  Button 2 - Checkout using Clearpay Express
</button>

Then set the target in the afterpay.js initialise function with that common class.

For example, set target in initializeForPopup:

AfterPay.initializeForPopup({
  // ...
  target: ".afterpay-express-button",
});

Load afterpay.js

To launch Clearpay Express Checkout you will need to add the afterpay.js script on your page.

You will also need to set the onload attribute to point to your own function (e.g. initAfterpay) where you will perform the initialisation of the popup. The contents of this function are detailed in the next section Initialise the Popup Window.

For example, loading the sandbox afterpay.js script:

<script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload=initAfterpay()"></script>

Initialize the Popup Window or Redirect flow

Inside your own onload function (e.g. initAfterpay), use afterpay.js to initialize the:

• Popup window by invoking initializeForPopup (Integrated Shipping)
• The redirect flow by invoking initializeForRedirect (Deferred Shipping)

Then you must configure the following properties:

• Set countryCode to the two-character ISO 3166-1 country code of the merchant account

• Set the addressMode to one of the provided address mode constants (see address mode for options). For Deferred Shipping, select an option that does not contain shipping options

• Set target to the ID (or class) assigned to your button that triggers the checkout process

• Handle lifecycle events:

  • onCommenceCheckout: This is where the retrieval of the Clearpay token from your server happens. Once retrieved, to start the checkout process you must call actions.resolve(TOKEN)

  • onComplete: see The onComplete Callback section below for more details

initializeForPopup

<html>
  <head>
    <script>
      // ensure this function is defined before loading afterpay.js
      function initAfterpay () {
        AfterPay.initializeForPopup({
          countryCode: 'AU',
          onCommenceCheckout: function (actions) {
            /* retrieve afterpay token from your server */
            /* then call `actions.resolve(token)` */
          },
          onComplete: function (data) {
            /* handle success/failure of checkout */
          },
          target: '#afterpay-express-button',
          addressMode: AfterPay.ADDRESS_MODES.ADDRESS_WITH_SHIPPING_OPTIONS,
        })
      }
    </script>
    <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="initAfterpay()">
    </script>
  </head>
  <body>
    <button id="afterpay-express-button" 
    data-afterpay-entry-point="mini-cart"
    data-afterpay-checkout-button-label="Checkout using Clearpay Express">
      Checkout using Clearpay Express
    </button>
  </body>
</html>

initializeForRedirect

<html>
  <head>
    <script>
      // ensure this function is defined before loading afterpay.js
      function initAfterpay () {
        AfterPay.initializeForRedirect({
          countryCode: 'AU',
          onCommenceCheckout: function(actions) {
            /* retrieve clearpay token from your server */
            /* then call `actions.resolve(token)` */
          },
          target: '#afterpay-express-button',
          addressMode: AfterPay.ADDRESS_MODES.ADDRESS_WITHOUT_SHIPPING_OPTIONS,
        })
      }
    </script>
   <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="initAfterpay()">
   </script>
  </head>
  <body>
    <button id="afterpay-express-button" 
    data-afterpay-entry-point="mini-cart"
    data-afterpay-checkout-button-label="Checkout using Clearpay Express">
      Checkout using Clearpay Express
    </button>
  </body>
</html>

During Clearpay Express Checkout

When the customer clicks the Clearpay checkout button, a popup launches. The customer is prompted to login and review their order details. The customer can choose a payment method and delivery address, and, if you use Integrated Shipping, shipping options appear for the customer's address.

Once the customer confirms their details on Clearpay, the popup closes and the customer returns to your site. The onComplete callback notifies your page of the completion.

The onComplete Callback

When the customer completes the Express Checkout flow, a call is made to the onComplete JavaScript function. This JavaScript function is passed an event argument with a data field called event.data that has the following properties:

The orderInfo data properties table

AfterPay.initializeForPopup({
          // ...
          onComplete: function (event) {
            /* handle success/failure of checkout */
            
            if (event.data.status == "SUCCESS") {
              // The customer has confirmed the payment schedule.
              // Call your server here to retrieve the order details
              
            } else {
              // The customer cancelled the payment or closed the popup window.
              
            }
          },
        })

Retrieve the Express Checkout Order Details

Use the Clearpay Get Checkout API to retrieve all transaction details.

curl --request GET \
  --url https://api-sandbox.afterpay.com/v2/checkouts/YOUR-TOKEN \
  --header 'accept: application/json'

Verify the Transaction

The server must do a transaction integrity check to ensure that the transaction is valid. After receiving the onComplete callback, call your server to validate the transaction:

Compare the Clearpay order returned by the Get Checkout API with your own records.

Use this information as the “source of truth” for the order, and include the customer's name, email address, delivery address, and order total.

Additional Verification

Passing the total order amount when you call the Auth (or Capture if using the Immediate Payment Flow) endpoint allows Clearpay to do its own validation.

Complete the Express Checkout Process

When the Express checkout is complete, begin by handling The onComplete callback and getting the order details.

Before going any further, you must verify the order details. Confirm that the shipping address, shippingOptionIdentifier, and the resulting amount are all valid and match your records. This prevents any potential frontend errors or miscommunication during the integrated shipping process.

Once verified, you can either:

• Capture payment immediately (for Integrated Shipping)

or

• Continue the checkout on your site (for Deferred Shipping).

🚧

Warning

The Clearpay Checkout Widget is mandatory if your checkout process makes any changes to the order total after returning to your site.

Capturing payment

To capture the payment use either the immediate payment flow or the deferred payment flow.

Along with the APIs, for Express Checkout we need an amount field in the payload. This required amount field is used to check that the final amount matches the amount including the shipping and taxes.

curl --request POST \
  --url https://api-sandbox.afterpay.com/v2/payments/capture \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"token": "YOUR_TOKEN", "amount":{"amount":"10.00", “currency”: “AUD”}}'

Note

This section uses code examples from the immediate payment flow capture API but the same changes can also be used for V2 deferred payment.

📘

Note

This section uses code examples from the immediate payment flow capture API but the same changes can also be used for V2 deferred payment.