Set up express checkout with deferred shipping

Express checkout uses the same APIs as standard checkout. Complete Get started with express checkout before configuring deferred shipping.

Initialize the popup window

Define the initAfterpay() function that is called when Afterpay.js loads. This function uses Afterpay.initializeForPopup() to configure the express checkout behavior. Configure the following properties:

• countryCode: Your merchant account’s two-character ISO 3166-1 code
• target: The ID or class of the button that triggers checkout
• Set the flag shippingOptionRequired to false
• Handle lifecycle events:
  • onCommenceCheckout: Retrieve the Afterpay token from your server, then call actions.resolve(TOKEN) to start checkout.
  • onComplete: See “finalize the order” for details.

function initAfterpay() {
  Afterpay.initializeForPopup({
    countryCode: 'US',
    onCommenceCheckout: function (actions) {
      /* retrieve the Afterpay token from your server */
      /* then call `actions.resolve(token)` */
    },
    onComplete: function (data) {
      /* handle success or cancellation */
    },
    target: '#afterpay-express-button',
    shippingOptionRequired: false,
  });
}

Customer completes checkout

When the customer clicks the Afterpay checkout button, a popup opens or they’re sent to your redirect link. The customer is prompted to log in and review their order details. They can select a payment method and delivery address.

After confirming their order, the popup closes and the customer returns to your site. Checkout completion is communicated via the onComplete callback.

Finalize the order

When the customer completes Afterpay express checkout, the onComplete Javascript function is called. It receives an event argument with a data field containing the following properties:

orderInfo data properties

Afterpay.initializeForPopup({
  // ...
  onComplete: function (event) {
    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.
    }
  },
});

Get order details

Retrieve the transaction details by calling the Get Checkout endpoint. This is the source of truth for the order. It includes the user’s name, email address, delivery address, phone number, and order total.

Continue the checkout process

After getting the order details, continue the checkout on your site. To continue:

• Prefill your checkout using the Afterpay order details
• Have the customer select a delivery method
• Optionally, offer promo codes and allow changes to the order details
• Display the Afterpay checkout widget on the final review page or at all steps of your checkout. We recommend setting up the checkout widget before continuing.

Capture payment

You can capture payment using either the immediate payment flow or the deferred payment flow. For express checkout, the payload must include an amount field, which verifies that the final amount matches the amount including the shipping and taxes.

For deferred shipping, in addition to the required amount field, include these additional fields in the payload. These are required to verify that the final order amount and payment schedule match the submitted order details.

• isCheckoutAdjusted: Indicates whether changes were made since order creation
• items: Updated list of order items (if changed)
• shipping: Updated shipping address (if changed)
• paymentScheduleChecksum: Latest value from your widget’s onChange call (see Getting the widget’s state)

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”},  "isCheckoutAdjusted":true, "shipping":{"name":"Joe Consumer","line1":"123 Fake Street", "postcode":"3000", "region":"VIC", "countryCode":"AU"}, "items":[{"price":{"amount":"10.00", "currency":"AUD"}, "name":"item1", "quantity":1}], "paymentScheduleChecksum":"YOUR_PAYMENT_SCHEDULE_CHECKSUM" }'

If the final amount (including shipping and taxes) or the paymentScheduleChecksum doesn’t match the expected values, the request will be rejected.

Once payment is captured, the express checkout order is complete.

Data payload properties

Optional features

Use a redirect flow

With deferred shipping, you can also use a redirect flow with express checkout. There are a few main differences when setting up the button for redirect, including:

• Creating an order token for redirect
• Using the initializeForRedirect method
• Redirecting the customer to finalize the order

To set up your redirect flow, first create an Afterpay order token using the Create Checkout API. Make sure to set the mode to express.

curl --request POST \
  --url https://api-sandbox.Afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant":{"redirectConfirmUrl":"https://example.com/checkout/confirm", "redirectCancelUrl":"https://example.com/checkout/cancel"}}'

Then, start by creating the Afterpay express checkout button, adding an entry point, and loading Afterpay.js. This is similar to the popup flow.

In your onload function, initialize the redirect flow by calling initializeForRedirect and configure the following:

• countryCode: The two-character ISO 3166-1 code for your merchant account
• addressMode: Use a mode without shipping options, as integrated shipping isn’t supported for redirect flows.
• target: The ID or class of the button that initiates checkout
• Handle lifecycle events:
  • onCommenceCheckout: Retrieve the Afterpay token from your server, then call actions.resolve(TOKEN) to start the checkout process.

<html>
  <head>
    <script>
      // ensure this function is defined before loading Afterpay.js
      function initAfterpay () {
        Afterpay.initializeForRedirect({
          countryCode: 'AU',
          onCommenceCheckout: function(actions) {
            /* retrieve Afterpay 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">
      Checkout using Afterpay Express
    </button>
  </body>
</html>

Address mode

To support different shipping types in the checkout, configure the addressMode property using one of the provided constants in the format Afterpay.ADDRESS_MODES.<NAME>, where <NAME> is one of the following:

Next, finalize the order. When you created the Afterpay order token for redirect, you defined the properties redirectConfirmUrl and redirectCancelUrl. After the customer completes Afterpay express checkout, these properties are used to direct them to the specified URL:

• If successful, they are redirected to redirectConfirmUrl
• If cancelled, they are redirected to redirectCancelUrl

Once the customer returns to your site, follow the steps to get the order details.

Errors

The following errors can occur during Afterpay express checkout with deferred shipping: