eVisa Application Widget

Introduction

The Application Widget can be leveraged in conjunction with the sherpa° Requirements API and launched via the sherpa° SDK on your website when a traveller wishes to apply for an eVisa product offered by sherpa°.

Preparing the SDK

To access the Application Widget, you need to include the sherpa° SDK by adding the script tag to the head of your HTML file and including your unique APP_ID.

🚧

APP_ID is required

You will receive a unique APP_ID during onboarding.

<script src="https://sdk.joinsherpa.io/widget.js?appId=APP_ID" defer></script>

The next step is to create a simple function that sets a flag once the SDK is fully loaded by waiting of the sdkLoaded event.

<script>
  isSDKReady = false;
  function onSherpaEvent(event) {
    if (event.type === 'sdkLoaded') {
      isSDKReady = true;
    }
  }
</script>

We also recommend placing an empty element on the page to act as the mount point for the Application Widget.

<div id="sherpa-application"></div>

Configuring the Application Widget

To begin the configuration of the Application Widget and to pass traveller/itinerary details, you'll need to create a function that can be run when you want the Application Widget to launch.

<script>
  function applyVisa(productId) {
    // Checking if SDK is ready
    if (isSDKReady) {
      // Configs to be passed
      const applicationConfig = {
        selectedProductId: productId,
       	/* Include configuration parameters here.
           See the Configuration Model for more information. */
      	language: "en-US",
        currency: "CAD",
        itinerary: [{
        	originCountry: "CAN",
          destinationCountry: "EGY",
          departureDate: "2022-12-10",
          departureTime: "01:00:00",
          departureFlightNumber: "AB123",
          arrivalFlightNumber: "XY4321",
          arrivalDate: "2022-12-10",
          arrivalTime: "12:00:00",
          durationOfStay: 10,
          travelPurpose: "TOURISM"
      	}],
        travellers: [{
          displayName: "John",
          givenNames: "John",
          surname: "Smith",
          /* Additional traveller details like contact, passport, and residency information
             can be passed here to simplify application process. */
        }]
      };
      // Create and mount the new element
      $sherpa.V2.createElement('application', applicationConfig).mount('#sherpa-application');
    // If the SDK is not loaded
    } else {
      console.error('SDK is not ready yet');
    }
  }
</script>

The applicationConfig object is where you'll pass any configuration options as well as traveller and itinerary information into the Application Widget.

See the Configuration Model for more information about what parameters can be included within the applicationConfig object.

Obtaining the Product Code

Before you can launch the Application Widget, you will need to know whether the traveller is eligible for an eVisa from sherpa°. To do that, you can make a request to our /trips endpoint via the sherpa° Requirements API by providing the details of the traveller and their itinerary.

In the response, you'll need to check whether an eVisa product offered by sherpa° is required for the trip by parsing the included array for an object where:
type = "PROCEDURE"
attributes.documentType = "E_VISA" or "ETA"
documentLinks.provider = "sherpa"

That procedure will also include a product code at attributes.documentLinks.productId.

Below is a snippet of a procedure returned by an API request to the /trips endpoint for a trip from Canada to Egypt with a Canadian passport.

In this example, the product code we get is EGY_EVISA.

{
  "id": "490639a9-effe-47f4-8c0c-839d46fc8529",
  "type": "PROCEDURE",
  "attributes": {
    "country": "EGY",
    "title": "Electronic visitor visa",
    "description": "Travelers need a visa to visit Egypt for Business or Tourism.\n\nAn eVisa is the fastest and easiest way of obtaining a visa for Egypt because travelers can submit their application and supporting documents online. Once the application is approved, travelers receive their eVisa confirmation electronically. \n\nA valid visa is required to board the flight. If the visa is expired or doesn’t match the traveler’s passport information, travelers will not be able to board their flight.",
    "more": [],
    "enforcement": "MANDATORY",
    "documentType": [
      "E_VISA"
    ],
    "documentLinks": [
    {
      "type": "LINK",
      "url": "https://sherpa-widget.joinsherpa.io/applications/products/EGY_EVISA?affiliateId=sherpa",
      "title": "Apply online",
      "intent": "apply-product",
      "provider": "sherpa",
      "productId": "EGY_EVISA"
     }

Launching the Application Widget

Once you have confirmed that the traveller will require an eVisa offered by sherpa° and have obtained the product code, you can present them with an option to start the application.

An example is included below for how to start an application for a Egyptian eVisa via a simple HTML button by passing the appropriate product code to our application function.

<button onClick="applyVisa('EGY_EVISA')">Apply for Egyptian eVisa</button>

You will need to implement some custom logic to only display the button to the user if an eVisa product is available through sherpa° and pass the product code obtained from the API response into the function.

Configuration Model

The applicationConfig object accepts various parameters that you can use to customize it as well as pass traveller and/or itinerary information on to the eVisa application.

See the tables below for all accepted parameters, their format, as well as a short description.

Itinerary Model

Each object included in the itinerary array represents a single leg of a trip and can have the following parameters.

Traveller Model

Each object in the travellers array represents a single traveller and can have the following parameters.

Address Model

An Address object represents a single residential address and can have the following parameters.