GuidesAPI Reference

Adding the Express Checkout Button

You must show an Afterpay checkout button on your cart and/or product pages to enable Express Checkout. When clicked, the Afterpay checkout button will start the checkout process in a popup flow (the redirect flow can optionally be used with Deferred Shipping).

Options for the Afterpay Button

There is a selection of buttons available for each stage of checkout – each clearly indicating the following action to the consumer.

Click to enlarge


📘

Integration assets are available here, or contact your Afterpay merchant services representative.


Standard Afterpay Checkout Flow

The customer proceeds through the checkout process on your site as normal, selecting Afterpay as a payment option and confirming the transaction before order placement.

Click to enlarge


Express Checkout Flows (Cart and/or Product Pages)

Integrated Shipping:​ Delivery options are displayed to users in real time, with the ability to confirm the order within Afterpay.

Deferred Shipping:​ The user returns to the retailer site to finalize delivery options and complete the order.

Click to enlarge

Configure the Afterpay Button

Afterpay can be launched from different entry points in the consumer journey. To enable a smart checkout flow, create an Afterpay checkout button on your web page, assign an ID, and set the afterpay-entry-point data attribute on the button to one of the following:

  • product-page
  • mini-cart
  • cart

For example, a button that renders on the mini-cart:

 <button id="afterpay-button" data-afterpay-entry-point="mini-cart">
      Checkout with Afterpay
 </button>

Load afterpay.js

To launch Afterpay 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 initialization of the popup. The contents of this function are detailed in the next section Initialize 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 (Express Checkout - Product/Cart Pages)

Inside your own onload function (e.g. initAfterpay), use afterpay.js to initialize the popup window by invoking initializeForPopup. The following properties will then need to be configured:

    • Set countryCode 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 consumer within the Express Checkout flow (i.e. Integrated Shipping). This is the default value

    • Set target to the ID (or class if multiple buttons need to be targeted on the same page) assigned to your button that will trigger the checkout process

    • Handle lifecycle events:

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

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


Full Example with Deferred Shipping

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

During Afterpay Express Checkout

When the user clicks the Afterpay checkout button, a popup will launch and they will be prompted to login and review their order details. They can choose a payment method and delivery address, and, if you are using Integrated Shipping, they will also be presented with shipping options for that address.

Once they confirm their details on Afterpay, the popup will close and they will return to your site. Your page will be notified of the completion via the onComplete callback.

The onComplete Callback

When the consumer completes the Express Checkout flow, a call is made to the onComplete Javascript function. This function is passed an event argument with a data field event.data, which has the following properties:

PropertyTypeDescription
statusStringThe order status: "SUCCESS" or "CANCEL"
orderTokenStringThe order token provided when initializing the checkout
merchantReferenceString (optional)The merchant's ID or reference number for the order
AfterPay.initializeForPopup({
          // ...
          onComplete: function (event) {
            /* handle success/failure of checkout */
            
            if (event.data.status == "SUCCESS") {
              // The consumer has confirmed the payment schedule.
              // Call your server here to retrieve the order details
              
            } else {
              // The consumer cancelled the payment or closed the popup window.
              
            }
          },
        })

Retrieve the Express Checkout Order Details

Retrieve all transaction details using the Afterpay Get Checkout API:

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

Verify the Transaction

A transaction integrity check must be performed to ensure that the transaction is valid. After receiving the onComplete callback, call your server to validate the transaction:

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

PropertyTypeDescription
amountMoneyTotal amount to be charged to consumer.
consumerConsumerContains the user's givenNames, surname, and email. Note that phoneNumber will not be included here.
shippingContactContains the user's shipping address with full details.
shippingOptionIdentifierStringIntegrated Shipping only. The ID corresponding to the shipping option chosen by the user.

This should be used as the “source of truth” for the order, and will include the consumer 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 Afterpay to perform its own validation.


Complete the Express Checkout Process

After retrieving the order details, you may choose to either capture payment immediately or continue the checkout on a review page. To capture payment and complete the transaction immediately, make use of Integrated Shipping with the Buy Now feature.

If you intend to continue the checkout on your site, you should:

  • Pre-fill your review page using the Afterpay order details
  • Allow the user to select a delivery method (unless using Integrated Shipping)
  • Optionally offer the ability to change order details and enter promo codes
  • Display the Afterpay checkout widget on the final review page or at all steps of your checkout

❗️

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