Set up express checkout with integrated shipping

Express checkout uses the same APIs as standard checkout. Integrated shipping enhances the experience by embedding your shipping options directly into Afterpay express checkout, streamlining the process. When paired with the Buy Now flag, it creates a one-step checkout.

Complete Get started with express checkout before configuring integrated 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
• addressMode: One of the provided address mode constants
• target: The ID or class of the button that triggers checkout
• Set the buyNow flag to true. This shows customers a “Buy Now” button for one-step checkout.
• 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.
  • onShippingAddressChange: See Listen for Address Changes for details.

function initAfterpay() {
  Afterpay.initializeForPopup({
    countryCode: 'AU',
    onCommenceCheckout: function (actions) {
      /* retrieve the Afterpay token from your server */
      /* then call `actions.resolve(token)` */
    },
    onShippingAddressChange: function (data, actions) {
      /* calculate the shipping options for `data` */
      /* then call `actions.resolve(shippingOptions)` */
    },
    onComplete: function (data) {
      /* handle success or cancellation */
    },
    target: '#afterpay-express-button',
    addressMode: Afterpay.ADDRESS_MODES.ADDRESS_WITH_SHIPPING_OPTIONS,
    buyNow: true,
  });
}

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:

Customer completes checkout

When the customer clicks the Afterpay checkout button, a popup opens. The customer is prompted to log in and review their order details. They can select a payment method, delivery address, and shipping option.

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.

Verify the order details to ensure that the shipping address, shippingOptionIdentifier, and resulting amount are valid and match your records.

Capture payment

Capture payment using the immediate payment flow. For express checkout, the payload must include an amount field.

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

Listen for address changes

The onShippingAddressChange callback lets you dynamically update shipping options and taxes based on the consumer’s shipping address. It receives two arguments: data (the address) and actions (callback functions).

Afterpay calls onShippingAddressChange when the customer first enters the Afterpay summary page, and again whenever they update their shipping address. During these calls, you should:

• Use the address details in data to determine supported shipping options (e.g. by contacting your backend API).
• Use actions.resolve to return the options to the Afterpay express checkout, or
• Use actions.reject to signal any errors, providing an appropriate shipping constant

Data argument

Actions argument

Shipping options model

Retrieve shipping options via API

Afterpay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    fetch('/your-shipping-endpoint', {
      method: 'POST',
      headers: { 'content-Type': 'application/json' },
      body: JSON.stringify(data),
    }).then(function(options) {
      actions.resolve(options)
    }).catch(function(error) {
      // Parse the response and send a Afterpay rejection, e.g.:
      actions.reject(Afterpay.CONSTANTS.SHIPPING_UNSUPPORTED)
    })
  },
})

Calculate shipping options in Afterpay.js

Afterpay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    if (data.countryCode !== 'AU') {
      // Reject any unsupported shipping addresses
      actions.reject(Afterpay.CONSTANTS.SHIPPING_UNSUPPORTED)
    } else {
      // Calc shipping inline
      actions.resolve([ {
        id: '1', name: 'Standard', description: '3 - 5 days',
        shippingAmount: { amount: '0.00', currency: 'AUD'},
        taxAmount: { amount: '3.18', currency: 'AUD'},
        orderAmount: { amount: '34.99', currency: 'AUD'},
      }, {
        id: '2', name: 'Priority', description: 'Next business day',
        shippingAmount: { amount: '10.99', currency: 'AUD'},
        taxAmount: { amount: '4.28', currency: 'AUD'},
        orderAmount: { amount: '47.08', currency: 'AUD'},
      } ])
    }
  },
})

Shipping constants

To indicate error scenarios, call actions.reject() with the appropriate constant. The constants are in the form Afterpay.CONSTANTS.<NAME>, where <NAME> is one of the following:

Optional callbacks

Listen for shipping option changes

The onShippingOptionChange callback is optional, allowing you to track the customer’s chosen shipping option as it changes. It will be called with a single Shipping Option argument each time the customer selects a shipping option.

Afterpay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data) {
    console.log(data)
  },
})

If you need to modify the shipping option amounts after the user has selected a shipping option, use onShippingOptionChange with an additional action argument to update the checkout. When onShippingOptionChange is triggered:

1. Use the shipping option data to perform the required modification (for example, recalculate the tax via your backend API).

2. Once updated, use actions.resolve to return an object containing:

   • id: The same shipping option id from onShippingOptionChange
   • shippingAmount: The updated shipping amount for the selected option
   • taxAmount: The updated tax amount for the selected option
   • orderAmount: The updated order amount for the selected shipping option

3. Use actions.reject to signal any errors.

Afterpay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data, action) {
      fetch('/your-update-shipping-option-endpoint', {
          method: 'POST',
          headers: { 'content-Type': 'application/json' },
          body: JSON.stringify(data),
      }).then(function(options) {
          actions.resolve({
             id: data.id, 
             shippingAmount: { amount: '0.00', currency: 'AUD'},
             taxAmount: { amount: '3.18', currency: 'AUD'},
             orderAmount: { amount: '34.99', currency: 'AUD'},
          })
      }).catch(function(error) {
          // Parse the response and send the error, e.g.:
          actions.reject(error)
      })
  },
})

Listen for error messages

To facilitate handling of log/warning/error messages, you can optionally replace Afterpay.onMessage with a custom function. It receives the following payload:

Afterpay.onMessage = function (payload) {
  console[payload.severity](payload.message)
}

Optional features

Pickup orders

To support pickup orders using integrated shipping, follow these steps:

1. Allow customers to select pickup options (e.g. pickup location and date) that impact shipping costs before launching express checkout.
2. When a customer selects pickup, use the pickup address in the shipping body parameter when creating the order.
3. When calling initializeForPopup, set addressMode to Afterpay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS.

   Afterpay.initializeForPopup({
     // ...
     addressMode: Afterpay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS,
   })
4. Configure onShippingAddressChange to return the name and description of the pickup selection. This typically means returning a single option, for example:

   actions.resolve([ {
     id: 'pickup-store-123', name: 'Click & Collect',
     description: 'Available for next-day pickup',
     shippingAmount: { amount: '0.00', currency: 'AUD'},
     taxAmount: { amount: '3.18', currency: 'AUD'},
     orderAmount: { amount: '34.99', currency: 'AUD'},
   } ])
5. Optionally, you can collect additional pickup information (for example, an alternate pickup person) on your order review page.

Preselect shipping option

If customers can choose a shipping option on your site before launching express checkout, you can send us this information when checkout launches.

1. Set the shippingOptionIdentifier in the body parameter when creating the order. This preselects the option if it’s returned from onShippingAddressChange when checkout loads.
2. Set addressMode in Afterpay.initializeForPopup() to define how the shipping address is handled.
   • To provide a list of shipping options, use Afterpay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS
   • To not provide a list of shipping options, use Afterpay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS
3. Include the shipping address in the shipping parameter when creating the order.

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": {"popupOriginUrl": "https://example.com"}, "shipping": {"name": "Your Store Name", "line1": "123 Store Address", "postcode": "0000"}, shippingOptionIdentifier: “standard”
}}'

Errors

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