Integrating Paazl Perfect

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:

  1. Request a Paazl Perfect session
  2. Populate the Paazl Perfect session with checkout data
  3. 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

  1. Create a new pending order using the orderRequest webservice call
  2. Start a Paazl Perfect session using the checkoutRequest webservice call. This call includes a reference to the pending order
  3. 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:

  • home
  • servicePoint
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:

  • cod
  • insurance
  • signatureRequired
  • directDeliveryOnly
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:

  • email
  • sms

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.

Was this article helpful?