Important Note: CherryPie is no longer supported.
PassKit released the all new PassKit Platform in early 2020. This platform incorporates decades of experience designing, developing and implementing world class mobile wallet solutions for some of the biggest international brands. And at the same time, working with small businesses all over the world to help them access the cool capabilities of Apple Wallet and Google Pay passes. We have combined these rich learnings, proven best practices and ever growing knowledge, to deliver you the very best mobile wallet management platform. A platform where you can extend your mobile reach by quickly integrating Apple Wallet and Google Pay Passes into your business. Into your processes. Into your systems. And most importantly into your customer experience.
PassKit now delivers dedicated modules to solve your specific business use cases. No longer do you need to waste time learning about ‘passes’ language. No longer do you need to study mobile wallet terminology. You now work with Mobile Wallet API’s designed around your business processes; your language. A language you are already familiar with. The latest platform currently covers:
TRY THE NEW PASSKIT PLATFORM FOR FREE – UNLIMITED TEST PASSES
Click here for the latest documentation and details on using Postman with the PassKit API.
———
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.
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:
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)
Launch Postman and you should be redirected to the following sign-up/access page.
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.
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.
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.
Step 5) After entering your password, CherryPie will respond the Key and Secret, which users will need in order to generate the token.
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.
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.
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.
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.
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.
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:
And this is how it should look after you added {{jwt}} in the ‘Value section’:
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).
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.
In the example below, you can see an example of the pass before and after redemption via 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]
Important Note: CherryPie is no longer supported.
PassKit released the all new PassKit Platform in early 2020. This platform incorporates decades of experience designing, developing and implementing world class mobile wallet solutions for some of the biggest international brands. And at the same time, working with small businesses all over the world to help them access the cool capabilities of Apple Wallet and Google Pay passes. We have combined these rich learnings, proven best practices and ever growing knowledge, to deliver you the very best mobile wallet management platform. A platform where you can extend your mobile reach by quickly integrating Apple Wallet and Google Pay Passes into your business. Into your processes. Into your systems. And most importantly into your customer experience.
PassKit now delivers dedicated modules to solve your specific business use cases. No longer do you need to waste time learning about ‘passes’ language. No longer do you need to study mobile wallet terminology. You now work with Mobile Wallet API’s designed around your business processes; your language. A language you are already familiar with. The latest platform currently covers:
