PassKit allows you to quickly and easily generate URLs (weblinks) to pass records that can include unique data, without having to use the PassKit API.
In addition to not having to use the PassKit API to create unique pass links, you can generate as many SmartPass links without creating a pass record in the PassKit database. Therefore a SmartPass link won't count toward your pass volume subscription. i.e. you can have millions of SmartPass links but not pay for millions of passes. Only when the user clicks on the link will PassKit create and issue the pass.
You can generate these SmartPass links from a CSV, although for a production integration we recommend you automate and trigger from a record being created (in a CRM for example). The SmartPass link can then be distributed in a welcome email from your CRM / email Service provider.
All you need to generate a SmartPass link is the ability to generate a link with a base64 encoded JSON payload, and create a signature HMAC hash off the link to allow PassKit to verify the data integrity.
Below is a high level flow & sample instructions.
Important:
SmartPass links are only supported on the latest PassKit v4 platform: https://app.passkit.com. SmartPass links do not work with older versions of PassKit (Cherry Pie, and the v2/v3 API's).
If you have a CSV of your data you can use our link generator tool, which simplifies the creation and encryption of the links for you (no code knowledge needed!): https://github.com/PassKit/smart-pass-link-from-csv-generator
Generating Hashed Smart Pass Links
1. Define JSON payload with the pass data:
The payload can contain the coupon / member, PII & meta data that needs to go into the pass record:
{
"person.surname": "Kosterman",
"person.forename": "Patrick",
"person.email": "patrick@passkit.com",
"person.displayName": "Patrick Kosterman",
"members.member.profileImage": "https://passkit.com/patrick.png"
}For a full list of supported fields have a look here: https://github.com/PassKit/smart-pass-link-from-csv-generator#available-field-names
2. Base64 URL encode minified JSON payload
For above sample data:
eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9
3. Compose the link to issue the pass
The format of the link is as follows:
https://pub1.pskt.io/c/{programId or campaignId}?data={base64JsonPayload}&sig={signatureHash}So for the sample data it looks like the following:
https://pub1.pskt.io/c/{projectId}?data=eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9
The signature hash is appended in the next step.
4. Generate hash for the link
Each PassKit project has a unique secret that is used for creating a signature HMAC hash of the link. We support the following cryptographic hash functions MD5, SHA1, SHA223, SHA256, SHA384 and SHA512 / SHA3.
For the above sample let's create a SHA256 HMAC of the sample link:
https://pub1.pskt.io/c/{programId or campaignId}?data={base64JsonPayload}with shared secret 'patrick':
69a36c60efdbd6bab822c09553c9602e282b125cf165c6dd64800b00477b16a9
Now we can complete the link by appending the signature to it:
https://pub1.pskt.io/c/{programId or campaignId}?data=eyJwZXJzb24uc3VybmFtZSI6Iktvc3Rlcm1hbiIsInBlcnNvbi5mb3JlbmFtZSI6IlBhdHJpY2siLCJwZXJzb24uZW1haWwiOiJwYXRyaWNrQHBhc3NraXQuY29tIiwicGVyc29uLmRpc3BsYXlOYW1lIjoiUGF0cmljayBLb3N0ZXJtYW4iLCJtZW1iZXJzLm1lbWJlci5wcm9maWxlSW1hZ2UiOiJodHRwczogLy9wYXNza2l0LmNvbS9wYXRyaWNrLnBuZyJ9
&sig=69a36c60efdbd6bab822c09553c9602e282b125cf165c6dd64800b00477b16a9
Encrypted Links
In addition to the hashed link functionality, we have also added the functionality for generating encrypted links.
We recommend this over hashed SmartPass links, since ultimately it is more secure than the signature hash since the whole payload is encrypted. The process for this is similar but instead of generating a signature hash for the link, you encrypt the data payload with AES CBC encryption + random IV.
The encrypted link has the format:
https://pub1.pskt.io/c/{programId or campaignId}?data={encryptedData}&iv={randomIV}If you have a CSV of your data, you can use our link generator tool, which simplify creates and encrypts the links for you (no code knowledge needed!):