Implement the Afterpay Express Checkout

Documentation here

Currently Afterpay supports:

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.

Integrated Shipping	Deferred Shipping
Less than 5 shipping options	More than 5 shipping options
Simple shipping options (i.e. single optionfor whole order)	Complex shipping options (e.g. individual options at SKU level)
Simple tiered shipping options (e.g. standard, express, rush)	Time Slot Booking
Pickup in-store option before checkout entry	Mixed in-store pickup and home delivery

and I think we should start with the integrated shipping first.

Integrated Shipping

This feature improves the user experience by embedding your shipping options directly into the Afterpay Express Checkout flow. It streamlines the checkout process and can be combined with the buyNow flag to create a one-stop checkout that immediately precedes the order confirmation page.

Integrated Shipping is configured in the call to initializeForPopup triggered by the Express Checkout button.

It requires shippingOptionRequired to be true (enabled by default) and an onShippingAddressChange callback must be defined:

AfterPay.initializeForPopup({
  countryCode: 'US',
  onCommenceCheckout: function(actions) {
    /* retrieve afterpay token from your server */
    /* then call `actions.resolve(token)` */
  },
  onShippingAddressChange: function (data, actions) {
    /* required for Integrated Shipping  */
    /* address in `data` */
    /* calc options, then call `actions.resolve(options)` */
  },
  onShippingOptionChange: function (data) {
    /* optional - chosen option in `data` */
  },
  onComplete: function (data) {
    /* handle success/failure of checkout */
  },
  target: '#afterpay-express-button',
  buyNow: false,
  pickup: false,
  shippingOptionRequired: true
})

Listening for Address Changes

The Shipping Address Change callback is a feature of the Express Checkout. This callback allows a merchant to dynamically update shipping options and taxes based on the shipping address chosen by the consumer.

The shipping address change callback is required:

If you intend to update the order total based on a chosen shipping address.
To validate that you can ship to the selected address.

To set up the Shipping Address Change callback, implement the onShippingAddressChange function. This function will be passed two arguments: data and actions.

How the shipping options are calculated is entirely managed by the merchant. They can be calculated in Javascript or by handing off to an internal API.

If shipping options are available for the given address, they can be returned to Afterpay using the resolve action as shown in the code example below. Similarly, the reject action is used when shipping is unavailable.

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 an AfterPay rejection, e.g.:
      actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
    })
  },
})

Afterpay calls your onShippingAddressChange function when:

The consumer first enters the Afterpay summary page
The consumer makes a change to their shipping address on the Afterpay summary page

Afterpay provides the following parameters to your onShippingAddressChange function:

data parameter: This contains the consumer’s selected address with fields:

suburb, state, postcode, and countryCode

action parameter: This object is used to return your response to the Afterpay checkout. It consists of the following methods:

resolve : Call this method to provide the shipping options applicable to the consumers address. Takes an array of Shipping Option objects.
reject : Call this method when you are unable to handle the request. Do not throw an error, instead call this method with a Shipping Constant as the first argument to indicate a status, e.g.:
```
actions.reject(AfterPay.CONSTANTS.SHIPPING_UNSUPPORTED)
```

Shipping Option model

Attribute	Type	Description
id	String (required)	A shipping option identifier. Max length 128
name	String (required)	The name of the shipping options
shippingAmount	Money (required)	The shipping amount (without tax, if including taxAmount)
taxAmount	Money (optional)	The tax amount
orderAmount	Money (required)	The total amount for the order including shipping and taxes
description	String	A description for this shipping option

solidusio-contrib / solidus_afterpay