Integrating the Paazl checkout widget step by step
Integrating the Paazl checkout widget step by step
This article provides detailed explanations of the various steps involved in implementing the Paazl checkout widget. About the Paazl checkout widget provides an overview of the steps.
Disclaimer
While we do not facilitate modification of the widget's code, such modification is allowed.
Although we allow modification, please be aware that if you modify the widget's code and it subsequently malfunctions, Paazl will only provide support on a best effort basis.
It is important to test a modified widget's behavior in multiple scenarios in order to make sure that it still provides an attractive display of shipping options without artifacts.
Environment variables
When integrating the Paazl Checkout widget, you may want to set particular environment variables at run time for local development purposes.
Custom API URL
This is the URL pf Paazl's REST API server.
npm run dev --env.apiUrl=http://localhost:8082
Custom resource URL
This is the URL of Paazl's widget server. The widget uses it to retrieve CSS and image files.
npm run dev --env.resourceUrl=http://localhost:3000
Google Maps API key
The Paazl Checkout widget requires a Google Maps API key for its pickup location and store location maps. There is a separate API key for each environment so you need to specify the one for your development environment.
npm run dev --env.googleMapApiKey="AIzaSyCVWGcx8iXWEgjyV_nDMuIKYVsq11ZPXIA"
Note
In production, we recommend that you use Paazl's own Google Maps API key. You will then need to send a list of the URLs concerned to Paazl Customer Support. This will enable Paazl to whitelist them in its Google API account.
Note
The default Google Maps API key for development environments is Paazl's own key.
Step 1. Implement Paazl authorization request
An example of the Curl code for the request is:
curl -X POST "https://api-acc.paazl.com/v1/checkout/token" -H "accept: application/json;charset=UTF-8" -H "Authorization: Bearer 8ZNFYdd8gFUrgiyoIEeXpTsPB:cFBgHQ8h3CxBchF31Wa3Ba2pkmhbph2BG4tTYn9PZpKFv1z4tC" -H "Content-Type: application/json;charset=UTF-8" -d "{ \"reference\": \"200000150\"}"
An example of the JSON response is:
{
"token": "fb5371ba-76bf-416e-b3fe-5da9a9721063"
}
See the REST API reference to try it out.
Step 2. Add HTML code to load widget
Add one of the following code snippets to the <head> section of your checkout page.
Staging environment
<script type="text/javascript"src="https://widget-acc.paazl.com/v1/checkout.js"></script>
Production environment
<script type="text/javascript"src="https://widget.paazl.com/v1/checkout.js"></script>
Note
In your HTML, the code to load the widget should be placed before the initialization code given in step 3.
Step 3. Add HTML code to initialize widget
Add the initialization code snippet below to the <head> section of your checkout page. Alternatively, you could store the script in a Javascript (.js) file.
Note
In your HTML, the initialization code should be placed after the code to load the widget given in step 2.
See Initializing the Paazl checkout widget for an explanation of the various parameters used in the code snippet.
When it is initialized, the Paazl widget immediately requests shipping options based on the value you assign to consigneeCountryCode. The country can be determined from your customer's account, or from the IP address of his/her browser.
Note
If your webshop uses require.js for its own code libraries, you can also use it to integrate the Paazl checkout widget. See The Paazl checkout widget and require.js for an explanation of how to do this.
The parameters that you are required to assign a value are: apiKey, token, consigneeCountryCode and consigneePostalCode.
All the other parameters are optional. In the code snippet below, optional parameters have been assigned example values.
PaazlCheckout.init({
mountElementId: "paazl-checkout",
apiKey: "12345",
token: "0a9g8ddhkj883kgfs890sh7s7gg",
loadPaazlBasedData: true,
loadCarrierBasedData: false,
availableTabs: ["DELIVERY", "PICKUP", "STORE"],
defaultTab: "DELIVERY",
headerTabType: ["BUTTON","TAB"],
style: "GREEN",
nominatedDateEnabled: false,
consigneeCountryCode: "NL",
consignorCountryCode: "NL",
consigneePostalCode: "1019HD",
consignorPostalCode: "1020HD",
customerNumber: 123456789,
numberOfProcessingDays: 5,
tags: ["CASH_ON_DELIVERY"],
deliveryDateOptions: {
startDate: "2018-10-25",
numberOfDays: 5
},
language: "eng",
currency: "EUR",
isPricingEnabled: true,
isShowAsExtraCost: true,
deliveryRangeFormat: "DATE",
deliveryOptionDateFormat: "ddd DD MMM",
deliveryEstimateDateFormat: "dddd DD MMMM",
pickupOptionDateFormat: "ddd DD MMM",
pickupEstimateDateFormat: "dddd DD MMMM",
sortingModel: {
orderBy: "PRICE",
sortOrder: "ASC"
distributor: "TNT",
},
shipmentParameters: {
totalWeight: 3.14,
totalVolume: 100,
totalPrice: 14.77,
numberOfGoods: 2,
startMatrix: "AA",
goods: [
{
quantity: 2,
weight: 3.1,
length: 12,
width: 10,
height: 88,
volume: 1.33,
price: 213.14
},
{
quantity: 1,
weight: 3.1,
length: 12,
width: 10,
price: 113.14
}
]
},
shippingOptionsLimit: 3,
pickupLocationsPageLimit: 10,
pickupLocationsLimit: 20,
initialPickupLocations: 3
});
Step 4. Add HTML code to display widget
Assign an id attribute with the value "paazl-checkout" to an empty block element where you want to display the widget on your checkout page. For example:
<div id="paazl-checkout"></div>
You can also use the mountElementId initialization parameter to identify the block element concerned.
Step 5. (Optional) Add HTML code to style widget
Modify the look and feel of the widget by adding the following snippet to the <head> section of your checkout page. See Styling the Paazl checkout widget for examples of how each parameter in the snippet will affect your widget's look. The values you give each parameter are the same as those you use for CSS properties.
Note
We strongly recommend you either specify a predefined style using the style initialization parameter or the style code snippet below to brand your widget. If you use neither, your widget will be given the default Paazl style.
Note
You have to place the HTML style code after the HTML code to display the widget, otherwise your custom styles will be overridden.
The parameters that you are required to assign a value are: apiKey, token, consigneeCountryCode and consigneePostalCode.
All the other parameters are optional. In the code snippet below, optional parameters have been assigned their default values.
:root {
/* Global */
--brand-global-radius: 20px;
/* Colors */
--brand-color-background: #FFF;
--brand-color-secondary: #e9e9ef;
--brand-color-border: #282364;
--brand-color-body: #222;
--brand-color-primary: #ff463c;
--brand-color-focus: #282364;
/* Fonts */
--brand-font-family-title: "Quicksand", sans-serif;
--brand-font-family-body: "Quicksand", sans-serif;
--brand-font-weight-regular: 400;
--brand-font-weight-bold: 700;
/* Title */
--brand-title-weight: 700;
--brand-title-transform: uppercase;
--brand-title-spacing: 0;
/* Input */
--brand-input-border-width: 1px;
--brand-input-border-color: #282364;
/* Button */
--brand-button-radius: 20px;
--brand-button-border-size: 0;
--brand-button-border-color: transparent;
--brand-button-font-color: #FFF;
--brand-button-font-size: 14px;
--brand-button-font-weight: 400;
--brand-button-font-transform: uppercase;
--brand-button-font-spacing: 1px;
--brand-button-method-background: #FFF;
--brand-button-background: #FFF; }
</style>
Step 6. Implement widget method calls
The Paazl checkout widget offers a number of methods you can call when your customer changes information such as country, city or postal code. The methods return new shipping options to the widget, which automatically displays them.
An example of such a call, setting the country of the delivery address, would be:
PaazlCheckout.setConsigneeCountryCode("GB");
See Using Paazl checkout widget methods for a full list of the methods you have at your disposal.
Step 7. Get checkout details
In order to display delivery options and rates to a customer in your checkout, you will want to get the latest delivery details of that customer's purchase from Paazl. The Paazl REST API provides the GET checkout method to retrieve those details.
The Curl code for the request is:
curl -X GET "https://api-acc.paazl.com/v1/checkout?reference=200000150" -H "accept: application/json;charset=UTF-8" -H "Authorization: "Bearer 8ZNFYdd8gFUrgiyoIEeXpTsPB:cFBgHQ8h3CxBchF31Wa3Ba2pkmhbph2BG4tTYn9PZpKFv1z4tC""
Where "200000150" is the order reference.
An example of the JSON response is:
{
"consigneeCountryCode":"NL",
"consigneePostalCode": "1018PE",
"deliveryType": "HOME",
"notificationEmailAddress": "fred@grint.com",
"notificationPhoneNumber": "+31(0)201234567",
"pickupDate": "01-04-2019",
"preferredDeliveryDate": "07-04-2019",
"reference": "200000150",
"selectedPickupLocation": {
"accountNumber": "XX123",
"address": {
"city": "Amsterdam",
"country": "NL",
"postalCode": "8813XZ",
"province": "Noord-Holland",
"street": "Weteringschans",
"streetNumber": 1,
"streetNumberSuffix": "bg"
},
"code": "SIRGALAHAD",
"coordinates": {
"latitude": 52.234,
"longitude": 04.123
},
"distance": 0.1,
"name": "Afhaal Xpress",
"openingTimes": [{
"alwaysOpen": true,
"businessHours": [{
"from": "08:30",
"to": "18:00"
}],
"day": "MONDAY"
}]},
"selectedShippingOption": {
"carrier": {
"description": "PostNL",
"name": "AVG"
},
"deliveryDates": [ {
"deliveryDate": "07-04-2019",
"pickupDate": "01-04-2019",
"timeRange": {
"end": "13:00"
"start": "17:00"
}}],
"deliveryWindow": {
"end": "13:00",
"start": "17:00"
},
"description": "PostNL",
"estimatedDeliveryRange": {
"earliestDate": "02-04-2019",
"latestDate": "09-04-2019",
"max": 2,
"min": 7
},
"identifier": "431359",
"name": "AVG",
"rate": 5,
"tags": ["ID_CHECK"]
},
"token": "fb5371ba-76bf-416e-b3fe-5da9a9721063",
"webshopId": 804
}
See the REST API reference to try it out.
Step 8. (Optional) Configure "Stores" tab
If you decide to display your company's brick & mortar stores where your webshop customers can pick up their purchases, you will need to configure how the Checkout widget displays the stores concerned. See Configuring stores for an explanation of how to configure this tab.