API DevelopmentAdditional Features

Display the checkout widget

Use the checkout widget to display the Cash App Afterpay payment schedule on your website. There are three ways to use the widget:

  • Connected: Displayed after the checkout process, using an order token. If the order amount changes post-checkout, use the connected widget to update the payment schedule

  • Unconnected: Displayed before the customer starts the checkout process, with no order token—just an amount

  • With on file grant: Displayed before the customer places the order, using an alias from a grant

The widget is responsive and can fit into any container with a minimum width of 300px. You can render the widget into a target container on your page using JavaScript.

Connected widget

Use the connected widget on your checkout page after a customer completes the Cash App Afterpay checkout flow. This widget serves several purposes:

  • Ensures that the customer sees and agrees to an accurate payment schedule.
  • Verifies that the final amount charged matches what the customer was shown during checkout.
  • Provides the merchant with important information, like the first payment amount.
  • Informs the merchant if there are any barriers to purchase, such as exceeding the Cash App Afterpay payment limit.
Connected Widget.png

Important
Only show the connected widget after the customer has successfully completed the Cash App Afterpay checkout (when the onComplete status is SUCCESS). You must display the connected widget during the Deferred Shipping flow.
The connected widget requires:

  • The Cash App Afterpay checkout token to retrieve and render the payment schedule.
  • The final order amount
1<html>
2 <body>
3   <div id="afterpay-widget-container"></div>
4   <script>
5     // Ensure this function is defined before loading afterpay.js
6     function createAfterpayWidget () {
7       window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8         token: 'YOUR_TOKEN', // required
9         amount: { amount: "123.45", currency: "USD" }, // required, amount of the total order post checkout, must be a positive value
10         target: '#afterpay-widget-container',
11         locale: 'en-US', 
12         onReady: function (event) {
13           // Fires when the widget is ready to accept updates.
14           // An initial call to "update" must be made here.
15         },
16         onChange: function (event) {
17           // Fires after each update and on any other state changes.
18           // See "Getting the widget's state" for more details.
19         },
20         onError: function (event) {
21           // See "Handling widget errors" for more details.
22         },
23       })
24     }
25   </script>
26   <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
27   </script>
28 </body>
29</html>

Capturing payment with the connected widget

Because you can update the order after checkout has completed, the connected widget has unique considerations. When calling the /v2/payments/capture API, the payload must contain the required amount field plus additional properties. This allows Cash App Afterpay to verify that the final order amount and payment schedule match the calculated values from the corresponding order details. These properties are:

  • isCheckoutAdjusted: Indicates whether any changes have been made to the order since the initial creation
  • items: The list of order items if it has changed
  • shipping: The shipping address if it has changed
  • paymentScheduleChecksum: The latest paymentScheduleChecksum retrieved from your widget’s onChange call (see ‘Getting the widget’s state’).
1curl --request POST  
2  --url <https://api-sandbox.afterpay.com/v2/payments/capture>  
3  --header 'accept: application/json'  
4  --header 'content-type: application/json'  
5  --data '{"token":"YOUR_TOKEN", "amount":{"amount":"10.00", “currency”: USD},  "isCheckoutAdjusted":true, "shipping":{"name":"Joe Customer","line1":"123 Fake Street", "postcode":"12345", "region":"NY", "countryCode":"US"}, "items":[{"price":{"amount":"10.00", "currency":"USD"}, "name":"item1", "quantity":1}], "paymentScheduleChecksum":"YOUR_PAYMENT_SCHEDULE_CHECKSUM" }'
Important
If the final amount doesn’t match the calculated amount (including shipping, taxes, etc.), or if the paymentScheduleChecksum doesn’t match the calculated payment schedule, the capture request will be rejected.
PropertyTypeDescription
tokenString (required)The token returned in the Create Checkout request.
amountMoney (required)Amount to be checked against the amount including shipping and taxes. If the amounts do not match, the request is rejected.
merchantReferenceStringOrder ID or reference this order corresponds to.
isCheckoutAdjustedBooleanWhether there have been changes to the order since the initial order creation.
paymentScheduleChecksumStringA unique value representing the payment schedule that must be provided when there has been changes since the initial order creation.
itemsItemAn array of order items that have been updated to be provided if it has changed since the initial order creation.
shippingContactThe shipping address for this order to be provided if it has changed since the initial order creation.

Getting the widget’s state

After each update and on any other state changes, the onChange callback is called with an HTML event argument. At this point the widget’s state is retrieved from event.data, which will have the properties in the table:

PropertyTypeDescription
isValidBooleanWhether the order is okay to proceed. If false, the order should be prevented from completing.
amountDueTodayMoneyThe amount owing today. Displaying this value in your Order Summary will give your customer more confidence when they place their order. amountDueToday.format() returns a formatted string that you can easily display in your UI.
paymentScheduleChecksumStringA unique value representing the payment schedule that must be provided when capturing the order.
errorErrorThe current error state, if any.

We recommend using the isValid and amountDueToday states to update your checkout UI as described above, and persisting the paymentScheduleChecksum on your backend to be used when capturing. The widget itself informs customers what has gone wrong when isValid is false.

In addition to the onChange callback, these states are exposed as properties on the widget and can be accessed directly at any time, for example:

var isValid = afterpayWidget.isValid
var amountDueToday = afterpayWidget.amountDueToday
var paymentScheduleChecksum = afterpayWidget.paymentScheduleChecksum
var error = afterpayWidget.error

Handling widget errors

PropertyTypeDescription
errorErrorRepresenting the current error state, if any.

Any errors on the widget trigger the onError callback with an HTML event (see table below), and have a false isValid status.

If the onChange callback is activated and fails due to an error, the onError event is also triggered for convenience. In this case, a response to onError events is not needed, provided all onChange events are handled.

onError event.data properties table

PropertyTypeDescription
isValidBooleanWhether the order is okay to proceed. For the onError event this will be false so prevent the order from completing.
typeStringFor an onError event, the type is set to the value of error.
errorErrorRepresents the current error state.

If you are getting errors during the rendering of the widget, open the browser console. The console may display some additional error loggings to help identify some common integration misconfigurations.

Unconnected widget

Use the unconnected widget on your checkout page before the customer starts the Cash App Afterpay checkout flow. This version of the widget displays an estimated payment schedule based on the initial order amount; this is only an approximation based on the initial order total.

The unconnected widget requires a defined positive amount to calculate the estimated payment schedule.

Unconnected Widget.png

If the order total changes (due to shipping method, promo code, or cart contents), the widget must be notified of the new amount. Only call the update function after the widget’s onReady callback has been triggered.

1<html>
2 <body>
3   <div id="afterpay-widget-container"></div>
4   <script>
5     // Ensure this function is defined before loading afterpay.js
6     function createAfterpayWidget () {
7       window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8         amount: { amount: "123.45", currency: "USD" }, // required, must be a positive value
9
10         target: '#afterpay-widget-container',
11         locale: 'en-US', 
12         onReady: function (event) {
13           // Fires when the widget is ready to accept updates.
14           // An initial call to "update" must be made here.
15         },
16         onChange: function (event) {
17           // Fires after each update and on any other state changes.
18           // See "Getting the widget's state" for more details.
19         },
20         onError: function (event) {
21           // See "Handling widget errors" for more details.
22         },
23       })
24     }
25   </script>
26   <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
27   </script>
28 </body>
29</html>

With on file grant

You can use the widget when customers place an order with an existing Cash App Afterpay On File grant. This is helpful for customers, allowing them to see their payment schedule despite not going through the Cash App Afterpay checkout flow.

To display the widget:

  1. First, call the Create Grant Alias endpoint (/v2/grants/alias) to retrieve the payment schedule token.
  2. Pass the token to the widget.
  3. If there are changes to the order total, call the updateAmount function to update the widget.
Considerations for cross-border trade

Always ensure that the currency is consistent throughout the entire checkout flow. For Cross Border Trade orders, the checkout widget displays the payment schedule and ‘Due today’ amounts in the customer’s currency, which may be different from the currency on your site. The capture amount must be in the same currency in which the checkout is initiated.

For example, you are an American merchant displaying a 100 USD order in AUD for an Australian customer on your site. When you start the Cash App Afterpay checkout, if you start the checkout by sending us the order amount in USD (e.g. 100 USD), then at capture the final order amount must also be in USD.

Likewise, if you initiate checkout by sending us the order amount in AUD post currency conversion on your side (e.g. 150 AUD), ensure that the capture amount is sent in AUD.

Styling the checkout widget

Standard widget

The default version of the widget displays accurate payment schedule information, the payment amount due today, and the legal disclaimer.

Here’s an example of how to initialize the standard widget, and a sample function for updating the amount to a new value.

1<html>
2  <body>
3    <div id="afterpay-widget-container"></div>
4    <script>
5      // Ensure this function is defined before loading afterpay.js
6      function createAfterpayWidget () {
7        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8          target: '#afterpay-widget-container',
9          locale: 'en-US',
10          amount: {
11            amount: "1338.00",
12            currency: "USD"
13          },
14          // Use your payment schedule token to reflect an accurate payment schedule to your customers
15          paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
16        })
17      }
18
19      function updateAmount() {
20        window.afterpayWidget.update(
21            amount: { amount: "1000.00", currency: "USD" }
22        )
23      }
24
25
26    </script>
27    <script src="https://portal.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
28    </script>
29
30    <button onclick="updateAmount()">Update amount</script>
31  </body>
32</html>

Compact widget

This is a more compact version of the widget. It presents the same information as the standard widget, but takes up less space.

Here’s an example:

1<html>
2  <body>
3    <div id="afterpay-widget-container"></div>
4    <script>
5      // Ensure this function is defined before loading afterpay.js
6      function createAfterpayWidget () {
7        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
8          target: '#afterpay-widget-container',
9          locale: 'en-US',
10          amount: {
11            amount: "1338.00",
12            currency: "USD"
13          },
14          style: {
15             theme: "TIMELINE"
16          },
17          // Use your payment schedule token to reflect an accurate payment schedule to your customers
18          paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
19        })
20      }
21    </script>
22    <script src="https://portal.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
23    </script>
24  </body>
25</html>

Style attributes

There is an optional style attribute that you can use to toggle particular features on or off in the widget. The current styles are:

  • border - If false, the border around the widget container is removed. Default: true
  • heading - If false, the heading “Your 4 interest-free payments” is removed. Default: true
  • logo - If false, the Cash App Afterpay logo is removed. Default: true
  • theme (string) - allows you to customize the look of the widget. Following themes are available ‘CLASSIC’ | ‘TIMELINE’ | ‘COLLAPSIBLE’ | ‘MODAL’. Default: ‘CLASSIC’

Here are some theme examples:

Timeline Timeline.png

Collapsible collapsible.png

Collapsible (extended) collapsible-expanded.png

Modal Modal.png

Modal (open) ![Modal open.png](../../assets/images/Modal open.png)

Code example:

window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
  // ...
    style: {
        border: true, 
        heading: true, 
        logo: true,
        theme: ‘TIMELINE’, // ‘COLLAPSIBLE’‘MODAL’
   }
  // ...
});