eVisa Application Widget

Accessing the configurable eVisa application widget via the SDK

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" aynsc></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 <div> 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",
          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.

🚧

Pre-population not currently supported

The Application Widget does not currently support pre-population of fields based on data passed via the applicationConfig object. This is a feature currently in development and will be available soon.

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.

2254

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.

ParameterTypeDescription
selectedProductIdStringThe code of the eVisa product to be applied for, obtained from the /trips endpoint API response.
placementStringName of the page where the widget is being shown.
homePage
discovery (pre-booking marketing page)
mmb ("manage my booking" page)
search
bookingConfirmation
destinationPage (marketing page for a destination)
covidPage
languageStringDefault: en-US
View supported languages
currencyStringDefault: USD
Supported currencies:
USD
CAD
GBP
EUR
intineraryArrayAn array of objects representing the various legs of the itinerary.
See Itinerary Model
travellersArrayAn array of objects representing the traveller(s).
See Traveller Model

Itinerary Model

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

ParameterTypeDescription
originCountryStringISO3 Country Code
e.g. CAN for Canada
originRegionCodeStringalpha3 Region Code
e.g. US-TX for Texas, USA
originAirportCodeStringIATA Airport Code
e.g. YYZ for Pearson International Airport, Toronto, Canada
destinationCountryStringISO3 Country Code
e.g. CAN for Canada
destinationRegionCodeStringalpha3 Region Code
e.g. US-TX for Texas, USA
destinationAirportCodeStringIATA Airport Code
e.g. YYZ for Pearson International Airport, Toronto, Canada
departureDateStringThe date of departure.
YYYY-MM-DD
departureTimeStringThe time of departure.
HH:MM:SS
arrivalDateStringThe date of arrival.
YYYY-MM-DD
arrivalTimeStringThe time of arrival.
HH:MM:SS
durationOfStayNumberThe expected length of stay in the destination country, in days.
travelPurposeStringThe purpose of the trip.
TRANSIT
TOURISM
BUSINESS

Traveller Model

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

ParameterTypeDescription
displayNameStringThe name to be displayed and used to reference the traveller throughout the application.
givenNamesStringThe traveller's given name(s).
surnameStringThe traveller's surname.
isPrimaryBooleanIs this the primary traveller
emailStringThe traveller's email address.
passportNationalityStringThe traveller's nationality as per their passport.
ISO3 Country Code
e.g. CAN for Canada
passportIssuingCountryStringThe country that issued the traveller's passport.
ISO3 Country Code
e.g. CAN for Canada
passportExpiryDateStringThe expiry date of the passport.
YYYY-MM-DD
passportIssueDateStringThe passport's date of issue.
YYYY-MM-DD
dateOfBirthStringThe traveller's date of birth.
YYYY-MM-DD
placeOfBirthStringThe traveller's city of birth.
sexStringThe traveller's sex according to their passport.
MALE
FEMALE
countryOfBirthStringThe traveller's country of birth.
ISO3 Country Code
e.g. CAN for Canada
phoneCountryCodeStringThe country code for the traveller's phone number.
phoneTypeStringThe type of phone number.
WORK
HOME
MOBILE
residenceAddressThe traveller's home address.
See Address Model

Address Model

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

ParameterTypeDescription
cityStringThe municipality this address is located within.
countryStringThe country this address is located within.
ISO3 Country Code
e.g. CAN for Canada
fullAddressStringA single string representation of the address when fully written out.
nameString
postalCodeStringPost code, ZIP code, postal code, etc.
stateStringThe state or province this address is located within.
streetStringThe name of the street for this address.
streetLine2StringThe second line of the address, if applicable.
streetNumberStringThe street number for this address.
unitStringThe unit number for this address.