How to use PassKit API – Tips and Instructions

Tweet about this on Twitter0Share on Facebook0Share on Google+0Share on LinkedIn0Pin on Pinterest0

PassKit online tools allow to comfortably perform a wide range of actions and operations without the need of having technical knowledge about programming. The vast majority of use cases are covered within our product features, however for some specific and custom solutions there might be the need to use the PassKit API. In this post we’ll cover the basics of PassKit API and provide the tools and methods to perform some of these actions.

Basics of API

An API (Application Programming Interface) is a set of definitions, protocols, and tools for building softwares and applications. An API service is delivered in the same way as a webpage, so to access the API users need a URL. When visiting a website for instance, users keep sending API calls to the server where that webpage is hosted. This makes the interaction between the human and the machine possible. So for example when you go to Facebook on your browser, you are sending a GET request to the Facebook server to retrieve the website. Every action performed on the web is related to a different API call. The way APIs interact and exchange data is via HTTP requests. The most used HTTP requests in the PassKit API are GET, POST and PUT.

NOTE: For PassKit API methods, please refer to our API documentation which can be found here.

Installing Postman to send API requests

Postman is an app which allows users to send API requests to the server. Postman can be downloaded from the Chrome Web Store. In this demo we will show how to add Postman to Google Chrome.

Postman Chrome Web Store

Once you get to the Postman page (as shown above), you should click on the top right ‘ADD TO CHROME’ blue button. The next screen should look like this:

Postman passkit

At this point simply click on ‘Add app’ and you should be able to see the orange Postman icon ready to be launched. (in the picture below, the last one at the bottom)

Screen Shot 2016-11-23 at 10.37.45 AM

Launch Postman and you should be redirected to the following sign-up/access page.

Screen Shot 2016-11-23 at 10.38.12 AM

NOTE: you don’t need to sign up for Postman, at this point you can just click on ‘Skip this and go straight to the app’.

Whether you signed up or not, you will eventually end up on this page where you can send the actual HTTP requests.

passkit api postman

Generating an Authentication Token

When someone makes a request to the PassKit API, we need to verify who the user is and make sure he or she has permission to access the data. In the same way as websites require authentication (ex. need to login to Facebook), APIs need the user to be authenticated. Authentication in the PassKit API takes place through the Authorisation Header (accessible in Postman) by using an authorisation token. In order to generate a token, users need two credentials called Key and Secret.

How to get Key and Secret

Step 1) Login to CherryPie

Step 2) Click on ‘Clients’ on the left tab.

passkit api cherrypie

Step 3) On the client of your choice, click on the arrow located by the right-hand side by the client name. This will prompt a drop down menu with two options: ‘Edit’ and ‘Get API Keys’. You want to click on Get API Keys.

Step 4) You will be required to re-enter your password as shown below.

Screen Shot 2016-11-24 at 11.37.30 AM

Step 5) After entering your password, CherryPie will respond the Key and Secret, which users will need in order to generate the token.

passkit api key and secret

Step 6) Make sure you keep your Key and Secret in a safe place. Also consider that the session containing your Key and Secret expires in 30 seconds for security reasons, so credentials should be used by then.

Use Key and Secret to Generate the Token

In this section we’ll see how to use the Key and Secret to send API requests via Postman. In the past we used to suggest generating tokens through JWT website (it’s still possible), but we would recommend using the following script by pasting it into the ‘Pre-request Script‘ section within Postman:

 

var apiKey = "passkit_api_key",
    apiSecret = "passkit_api_secret";

var jwtBody = {
    "key": apiKey,
    "exp": Math.floor(new Date().getTime() / 1000) + 30,
    "iat": Math.floor(new Date().getTime() / 1000),
    "url": request.url,
    "method": request.method
};

if (request.hasOwnProperty("data") && request.data !== null && request.data.length > 0) {
    jwtBody.signature = CryptoJS.SHA256(request.data).toString(CryptoJS.enc.Hex);
}

postman.setEnvironmentVariable('jwt', "PKAuth " + generateJWT(jwtBody, apiSecret));

function generateJWT(body, secret) {
    header = {
        "alg": "HS256",
        "typ": "JWT"
    };
    var token = [];
    token[0] = base64url(JSON.stringify(header));
    token[1] = base64url(JSON.stringify(body));
    token[2] = genTokenSign(token, secret);

    return token.join(".");
}

function genTokenSign(token, secret) {
    if (token.length != 2) {
        return;
    }
    var hash = CryptoJS.HmacSHA256(token.join("."), secret);
    var base64Hash = CryptoJS.enc.Base64.stringify(hash);
    return urlConvertBase64(base64Hash);
}


function base64url(input) {
    var base64String = btoa(input);
    return urlConvertBase64(base64String);
}

function urlConvertBase64(input) {
    var output = input.replace(/=+$/, '');
    output = output.replace(/\+/g, '-');
    output = output.replace(/\//g, '_');

    return output;
}

or

Find the script HERE >>> Click for the script

Once you copied the script, go to Postman and click on ‘Pre-request Script’ (underlined in orange with a blue dot in the image below) and paste it into the box as shown.

Screen Shot 2016-11-24 at 11.44.27 AM

Within the first two lines of the script you want to change “passkit_api_key” and “passkit_api_secret” with the actual Key and Secret you got from CherryPie. Make sure the two values are between quotation marks.

Screen Shot 2016-11-24 at 11.46.10 AM

Postman needs an environment to store your variables, so you should create one. In order to do so, click on the ‘gear icon’ on the top right side within postman. You will find a drop-down menu containing an option called ‘manage environments’. Click on it.

Screen Shot 2016-11-24 at 12.01.06 PM

This will open a new window that allows users to create new environments. Create a new one by clicking on the orange ‘Add’ button. NOTE: you won’t need to add any extra detail here.

passkit api postman environment

Once you created the environment, just close the window and go back to Postman. You will now be able to select your newly created environment from the top-right bar as shown below. Once you find it, click on it.

Screen Shot 2016-11-24 at 12.06.30 PM

The next step is to click on ‘Headers’ and create an authorisation (type Authorization) header with the following text in the ‘Value’ field:

{{jwt}}

This is how it should look like when you are doing it:

Screen Shot 2016-11-24 at 12.11.39 PM

And this is how it should look after you added {{jwt}} in the ‘Value section’:

Screen Shot 2016-11-23 at 4.39.52 PM

At this point the setup process in Postman is finalised and users can start sending HTTP requests to the server without having to worry about creating tokens.

How to redeem a pass through the API [Screens]

Now that Postman is setup and ready to send API requests, let’s see how to perform a simple pass redemption.

Step 1) Refer to our API documentation to find which HTTP request is needed to redeem a pass. In this case it’s a PUT request.

Step 2) Make sure you use the correct URL for the request, followed by the pass ID of the pass you want to redeem (image below: URL+pass ID). On the left side of the URL, double check you selected the correct HTTP request (in this case PUT).

passkit api call

Step 3) Go to the ‘Body’ tab in postman and set it on ‘Raw’ + ‘JSON’ (application/json). In the actual body section insert the following parameter (which you can also find in the API documentation):

{

“isRedeem”: true

}

Step 4) Make sure you are operating in the environment you previously created by checking the environment name on the top right side.

Step 5) Send the HTTP request.

Step 6) Depending on how you’ve set up your template in CherryPie, you should see your pass updated. Please note that you can create your redeemed design within CherryPie by ticking the ‘Change the design after redemption’ box as shown below.

Screen Shot 2016-11-24 at 12.27.31 PM

In the example below, you can see an example of the pass before and after redemption via the API.

 

Screen Shot 2016-11-23 at 5.24.43 PM
Example of Pass before (on the left) and after (on the right) redemption through the API.

NOTE: redemption can also be performed with a barcode scanner + scanning app. Please check out this link to find out more.

Conclusions

With the PassKit API it is possible to execute every action within CherryPie, together with a wide range of custom solutions.

If you need support in using the PassKit API or if you would like to ask something related to your specific situation, please get in touch with us. We’ll be happy to help.

Also, if you have any feedback or question, please feel free to leave a comment in the comment section below.

NOTE: You might be interested in How To Setup Apple Pay on your Website [through Stripe]

Tweet about this on Twitter0Share on Facebook0Share on Google+0Share on LinkedIn0Pin on Pinterest0