Integrating Paazl Perfect
Note
If you need help configuring Paazl Perfect, feel free to contact Paazl Customer Support. Due to rapidly changing technologies, the Paazl technology "Paazl Perfect" is "End of Life". This means we will support existing customers using Paazl Perfect, but that it will no longer receive updates or improvements. Instead we recommend you take a look at our Paazl checkout widget.
This article explains how to integrate Paazl Perfect in your webshop's checkout.
To create a Paazl Perfect session in your webshop checkout, you need to do three things:
- Request a Paazl Perfect session
- Populate the Paazl Perfect session with checkout data
- Return the selected delivery option to your checkout
The details of how to perform these steps are explained below.
1. Request a Paazl Perfect session
- Create a new pending order using the orderRequest webservice call
- Start a Paazl Perfect session using the checkoutRequest webservice call. This call includes a reference to the pending order
- Load the URL script returned by checkoutResponse webservice response into your checkout
<script type="text/javascript" src="https://ost.paazl.com/checkout/a34cb32d-d75c-4aab-8166-f4dd272c106a/loader.js"></script>
2. Populate the Paazl Perfect session with checkout data
Use the PaazlCheckoutModuleLoader.show() Javascript function to send checkout data to Paazl.
The PaazlCheckoutModuleLoader.show() function needs to be able to access the values of the fields in listed in Table 1. There are two ways of giving the function access to these values:
- as field-value pairs in a JSON object, for example
PaazlCheckoutModuleLoader.show({consigneeCountryCode: "NL", consigneePostalCode: "1019HD"}); - as name/data-pcm-input attribute pairs in your HTML code, for example:
<select name="country" data-pcm-input="consigneeCountryCode">...</select>
or
<input type="text" name="postal_code" data-pcm-input="consigneePostalCode"/>
Table 1: Paazl Perfect checkout fields
| Field | Type | Required | Description |
|---|---|---|---|
| locale | String(2) | N | The ISO 639-1 Code of the language you want Paazl Perfect to display in (default: NL) |
| consigneeCountryCode | String(2) | N |
The ISO 3166-1 country code of the shipping address |
| consigneePostalCode | String(255) | N |
The postal code of the shipping address Note Although this field is not required by Paazl, we strongly recommend that you make it mandatory on your checkout page |
| deliveryType | Enum | N |
Determines the Paazl Perfect starting tab. Takes one of the following values:
|
| servicePointBasePostalCode | String(255) | N |
The postal code used to look for nearby pick-up locations. |
| preferredDeliveryDate | Date | N |
The customer's preferred delivery date |
| notificationEmailAddress | String(255) | N | The e-mail address for carrier notifications |
| notificationPhoneNumber | String(255) | N |
The mobile phone number for carrier SMS notifications Note To make sure that every carrier accepts the mobile telephone format, please remove all spaces and symbols that have been entered by the custome |
| servicepointAccountNumber | String(255) | N | The customer's account number for opening locker boxes (e.g. at DHL Packstations) |
3. Return the selected delivery option to your checkout
After a customer has chosen a delivery option in Paazl Perfect, there are two ways in which you can store and display this information in your webshop's check-out page.
- Use a Javascript callback function
- Use Paazl's checkoutStatusRequest API call
Javascript callback function
Note
Although this option gives best performance, a customer could theoretically use his/her browser to tamper with the data returned to your checkout.
When a customer confirms his/her choice, your webshop executes
PaazlCheckoutModuleLoader.show(myCallback);
where myCallback is a function you define yourself, and which you ca name whatever you want.
Paazl passes your callback function a HashMap containing the field-value pairs listed in Table 1 above as well as those listed in Table 2 below. Your function then reads the values contained in the HashMap and manipulates the data on your checkout page to reflect your customer's choices.
Sample Callback Function
function myCallback(params) {
alert("User selected " + params.option + " delivery on " + params.preferredDeliveryDate);
}
PaazlCheckoutModuleLoader.show(myCallback, { deliveryType: "home" });
Table 2: Additional Paazl Perfect checkout fields
| Field | Type | Required | Description |
|---|---|---|---|
| option | String(255) | N | Code of the selected shipping option |
| deliveryFeatures | Enum | N |
Characteristics of the selected shipping option. Can take one or more of the following values:
|
| rate | Decimal | N | Rate of the selected shipping option |
| servicePointCode | String(255) | N | Code of the selected pick-up location |
| servicePointName | String(255) | N | Name of the selected pick-up location |
| servicePointAddress | String(255) | N | Address of the selected pick-up location |
| notificationType | Enum | N |
Selected notification method Can take one or both of the following values:
|
checkoutStatusRequest API call
You can also use the Paazl checkoutStatusRequest API call to retrieve and store the selected delivery option when displaying it on your checkout page. This is the safest option, but it might slow performance because it involves an additional API call and response in your check-out.