Client API & events

Client API

Suspend

When making modifications to the iframe such as updating the cart, we want to make sure the user is not making changes in the iframe at the same time. In order to avoid this bad user experience we provide the following tools to lock the iframe while changes are being made:

// suspend will dim the checkout and show a spinner
window.ledyer.api.suspend();

// make changes to the iframe such as updating cart or delivery address etc.

Resume

When the modifications are completed, call the API-method resume. This will remove the spinner from the Checkout and unlock the application.

window.ledyer.api.resume();

Client validation

If settings.requireClientValidation was set to true when the order session was created, Ledyer's checkout client will pause after the end user has pressed the complete purchase button, in order to give the merchant an opportunity to perform any kind of validation before the order is submitted to Ledyer, for a maximum duration of 10 seconds.

The result of the validation is communicated to Ledyer via Ledyer's client validation API, after receiving the waiting for client validation event.

The merchant can use the API to control whether the order submission should proceed or not, and optionally send a message with a body and a title.

If no validation has been received after the duration of 10 seconds has ended, the order submission will proceed anyway.

If shouldProceed is set to false as validation is passed to Ledyer within the duration, the purchase will not complete and an error message will be displayed in the checkout. If no message is passed via the client validation API, a default error message will be rendered in the checkout,

window.ledyer.api.clientValidation({
  shouldProceed: false,
  message: {
    title: "Something went wrong"
    body: "Oops"
  }
});

If shouldProceed is set to true the order submission will proceed after the next brief polling interval, and no message is necessary to send in that case.

window.ledyer.api.clientValidation({
  shouldProceed: true,
});

Client side events

Shipping address updates

When a customer updates the shipping address in Ledyer checkout a custom event will be sent out containing the new postalCode and country.

Register event listener changes

document.addEventListener("ledyerCheckoutShippingUpdated", (event) => {
	console.log("event from ledyer checkout", event.detail);
});

Payload example

event.detail = {
	country: 'SE',
	postalCode: '11111'
}

Based on the information received, the session object might need to be updated, in that case you can now make use of the suspend and resume functions above.

The event is meant to be used as a hook for third-party clients/plugins that handle shipping. The event is not meant to be used as a base for updating the order. The actual shippingAddress information should always be taken by requesting Get order session.

Customer details updates

When a customer updates their personal details (such as phone, email, name) in the Ledyer checkout a custom event will be dispatched.

Register event listener changes

document.addEventListener("ledyerCheckoutCustomerUpdated", (event) => {
	console.log("Customer updated their details!");
});

Payload example

event.detail = {}

Order Complete

This event will dispatch when a customer has successfully completed the checkout and an order has been created in Ledyer. A notification will be sent out shortly after and the order can now be fetched via Get order.

important

This event will not be sent out if the session contains a confirmation url, if you wish to receive this event and redirect to customer to a thank you page, you will have to make the redirect by yourself after receiving it.

Register event listener

document.addEventListener("ledyerCheckoutOrderComplete", (event) => {
	console.log("customer has passed the checkout!");
});

Payload example

event.detail = {}

Order Pending

important

When an order is pending there is something more that needs to be done before a full order can be created in Ledyer.

This event will dispatch when a customer has completed the checkout but an order has not yet been created in Ledyer, an example would be when the individual placing the order is not allowed to purchase for the buying company. In practice the session will be locked and an order might be created later on when in this case, the purchase is signed by a signatory.

Register event listener

document.addEventListener("ledyerCheckoutOrderPending", (event) => {
	console.log("customer has passed the checkout but further action is required for an order to be created");
});

Payload example

event.detail = {}

Waiting for client validation

This event will be dispatched after the end user has clicked the complete purchase button in the checkout and if settings.requireClientValidation was set to true when the order session was created. The merchant should then use the Client Validation API to communicate to Ledyer whether the order submission should proceed or not.

important

This event will not be dispatched if settings.requireClientValidation was set to false when the order session was created.

Register event listener

document.addEventListener("ledyerCheckoutWaitingForClientValidation", (event) => {
  console.log("Ledyer is now waiting for merchant validation for 10 seconds!");
  // ...Later on, somewhere else, after validation was successful:
  window.ledyer.api.clientValidation({
    shouldProceed: true
  });
});

Payload example

event.detail = {}