Listeners | Qliro devportal

For developers

By Qliro

Select search filters:

Listeners

Listeners the Merchant frontend application can subscribe to for notifications from the checkout frontend.

Define q1Ready

After rendering the Checkout, the variable q1 – a frontend communication endpoint – will be defined automatically in the global scope of the browser. This variable will provide the frontend application with a set of functions to communicate with the Qliro One iframe and to set listeners (optional).

To ensure that the checkout is rendered before the listeners are registered, you should define a function q1Ready in the global scope of the browser. Add all the listeners inside the body of the function. q1Ready will be invoked after the checkout has been rendered.

Implementation Example

1
2
3
4
window.q1Ready = function(q1) {
q1.onPaymentDeclined(paymentDeclinedListener);
   // ...
}

onCheckoutLoaded()

A callback for when Qliro One is fully loaded, which is when the interface has loaded and the order has been successfully fetched from server. Note that the spinner might still be visible for the user and user cannot yet interact with the checkout.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function without parameters	Yes

Implementation example


1
2
3
q1.onCheckoutLoaded(function callback() {
   //the checkout has been loaded successfully
})

onCustomerInfoChanged()

This callback activates when a customer updates their contact information (email, mobile number, address or personal/organization number). Useful to save customer information in the case of an abandoned cart.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function that takes a customer (object). If the address is masked the object will only contain isMasked set to true and if there is no address yet the address object will be null.	Yes

Implementation example

1
2
3
q1.onCustomerInfoChanged(function callback(customer)  {
  // Save customer info
})

Customer example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "email": "test@qliro.com",
  "mobileNumber": "0123456789",
  "personalNumber": "0987654321",
  "address": {
    "firstName": "FirstName",
    "lastName": "LastName",
    "street": "Street",
    "city": "City",
    "careOf": "",
    "postalCode": "12345",
    "isMasked": false
  }
}

onOrderUpdated()

Requires q1.lock() to have been called first. Initiates the order sync process towards the checkout frontend. Should call q1.unlock() as soon as the orders match.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function that takes an order (object) argument and calls unlock if the order is updated.	Yes

Implementation example

1
2
3
4
5
6
7
8
q1.onOrderUpdated(function (order) {
// if order reflects the local cart, use q1.unlock()
if (order.totalPrice === localCart.totalPrice) {
// exampel of how the order can be verified
q1.unlock()
}
// else, don't do anything
})

Customer example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "totalPrice": 350,
  "orderItems": [
    {
      "merchantReference": "RedHat",
      "pricePerItemIncVat": 100,
      "quantity": 3
    },
    {
      "merchantReference": "BlackHat",
      "pricePerItemIncVat": 50,
      "quantity": 1
    }
  ]
}

onCustomerDeauthenticating()

This callback activates if a customer clicks the "Not you?" option, or chooses to re-authenticate using their personal number during checkout.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function without parameters.	Yes

Implementation example

1
2
3
q1.onCustomerDeauthenticating(function callback()  {
  // The customer has chosen to deauthenticate
})

onPaymentMethodChanged()

Called when the user changes payment method or subtype. Use this for applying payment method based discounts.

Implementation

Arguments

Parameters	Type	Description	Mandatory
callback	function	A function that takes a paymentMethod (object) argument. The paymentMethod object will contain method (string), subtype (string), price (number) and priceExVat (number).	Yes

Implementation Example

1
2
3
q1.onPaymentMethodChanged(function callback(paymentMethod) {
  // For example: Apply payment based discounts
})

onPaymentDeclined()

If the customer tries to complete the purchase but the payment is declined because of a negative response on the call to MerchantOrderValidationUrl specified in the order creation, callback will be executed with the DeclineReason as an argument. This is to give the merchant frontend a way to react on the changed state if there is no open socket to their backend.

If the merchant wants their frontend to react to a custom error message, a DeclineReasonMessage can be sent from ValidateOrder and will be passed in this function.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function that will be executed if the payment is declined by the merchant backend. A declineReason (string) and possibly declineReasonMessage (string) will be passed as an argument and will reflect the response of the merchant backend.	Yes

Implementation Example

1
2
3
q1.onPaymentDeclined(function callback(declineReason, declineReasonMessage) {
  // Depending on the declineReason, inform the customer what to do next
})

Available declineReasons

declineReason	Description
OutOfStock	One or more of the items in the cart is now out of stock.
PostalCodeNotSupported	The merchant does not deliver to the shipping address provided by the customer.
ShippingIsNotSupportedForPostalCode	The selected shipping method does not support the shipping address provided by the customer.

onPaymentProcess()

When the customer completes the purchase and Qliro One is processing the payment, changing the order in some way might lead to unexpected behaviour for the customer. If the merchant wants to lock their interface or in some other way react to these events, this function can be used.

Implementation

Arguments

Parameter	Type	Description
onStart	function	A callback that will be executed when the payment process starts.
onEnd	function	A callback that will be executed when the payment process ends.

Implementation Example

1
2
3
4
5
q1.onPaymentProcess(function onStart() {
  // Lock the interface to prevent the customer from changing the order
}, function onEnd() {
  // Unlock the interface to open up for order changes again
})

onSessionExpired()

If the authorization token expires during a session, the customer will be informed inside Qliro One. When the customer closes the dialog, the top window will be refreshed. Using onSessionExpired is optional and overrides this behavior, replacing it with the execution of updateToken.

A session in the checkout is valid for 90 minutes. After that the order needs to be updated to create a new session, and here is where onSessionExpired should be implemented. An order is active for a maximum of 24 hours, after that a new order will have to be created.

Implementation

Arguments

Parameter	Type	Description	Mandatory
updateToken	function	A function that will be executed when the customer acknowledges the session expiration. This function will replace the default behavior.	Yes

Implementation Example

1
2
3
q1.onSessionExpired(function updateToken() {
  // Implement a way to update the token
})

onShippingMethodChanged()

This functionality will be activated if shipping options are provided in the createOrder request and the shipping functionality is used in Qliro One. This callback is called when the customer changes shipping method, secondary option or additional shipping services.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function that takes a shipping (object) argument. The shipping object will contain method (string), secondaryOption (string), additionalShippingServices (array of strings), price* (number), priceExVat (number), totalShippingPrice* (number) and totalShippingPriceExVat (number).	Yes

* price represents the price of the shipping method selected and totalShippingPrice represents the price of the shipping method selected plus any additionalServices that might cost extra.

Implementation Example

1
2
3
q1.onShippingMethodChanged(function callback(shipping) {
  // For example: Apply discounts based on shipping method and options
})

onShippingPriceChanged()

This functionality will be activated if shipping options are provided in the createOrder request and the shipping functionality is used in Qliro One. When the customer changes shipping option so that the shipping fee is affected, the callback will be executed with the new shipping price and new total price for shipping as arguments. The total price includes amounts for the selectred additional shipping services. This way the merchant is able to apply amount based discounts that take the shipping price into account.

Implementation

Arguments

Parameter	Type	Description	Mandatory
callback	function	A function that takes a newShippingPrice (number) and newTotalShippingPrice (number) arguments.	Yes

Implementation Example

1
2
3
4
q1.onShippingPriceChanged(function callback(newShippingPrice, newTotalShippingPrice) {
  // For example: Apply discounts based on amount including shipping price
  // newTotalShippingPrice includes costs for both shipping and selected additional shipping services
})

Next up is Enable scrolling