dev.passkit.netPassKit v2 API Reference

NAV shell java php Introduction API v2 runs on a different engine to v1 ( https://create.passkit.com ), this means the data and API credentials are not interchangeable between v1 and v2. The PassKit API v2 tools serve as the client interface to the latest PassKit web service. Use these tools to create and update your mobile wallet campaigns, templates, and passes. If you cannot find a method to achieve your objective or are struggling to use the API, please contact our support team with any questions you may have. This documentation currently only provides information on how to use the API in shell. Let us know which language you would like us to provide SDKs and documentation for next. ERD The diagram above shows the relationship between different entries. SDK We offically maintain the following SDKs. Java PHP Authorization JSON Web Tokens Your JWT token needs to conform to this structure: { "Header" :{ "alg" : "HS256" , "typ" : "JWT" }, "Payload" :{ "key" : "your_api_key" , "exp" : 1437523200 } } The token must be signed with your API secret PassKit v2 uses JSON web tokens (JWT) to authorize your requests. A number of libraries to help generate your JWT, as well as a JWT debugging tool, can be found at jwt.io . If you use our SDKs then you are able to just add your API Key and Secret to the SDK, which will then handle the authorisation. If there are no suitable SDKs available, the following instructions will help you generate a JWT (JSON Web Token) and attach it to the request. The JWT needs to be encrypted with the HS256 algorithm (which should be noted in the token headers) and it must be signed with your API secret. The JWT payload required in PassKit’s v2 API is: key - This is your API key exp - This the token’s expiry time It is important that the expiry time must be in the Unix time format and no more than one minute in the future, otherwise it will not be accepted as a valid authorisation. You can check the format for generating a JWT for authorization with this helper tool . Authorizing Requests To authorize, use this code: # With shell, you need to provide a valid JSON web token with each request curl "api_endpoint_here" -H "Authorization: PKAuth json_web_token" # Make sure to replace `json_web_token` with your generated token. // Note: Make sure to import the passkitSDK package PassKit pk = new PassKit ( "apiKey" , "apiSecret" ); // Make sure to replace `apiKey` and `apiSecret` with you own credentials. // Note: Make sure to import the passkitSDK package $pk = new PassKit("apiKey","apiSecret"); // Make sure to replace `apiKey` and `apiSecret` with you own credentials. All requests to the API need to be authorised. This means that you will need to generate a new JWT with each shell request. Once the JWT is generated it needs to be added as a header with the prefix PKAuth . The full http header looks like: Authorization: PKAuth json_web_token For shell users, you must replace json_web_token with your generated JWT. For SDK users, you must replace apiKey and apiSecret with your own credentials. Campaigns Campaigns are an important new feature of PassKit v2. They allow for much more flexibility in the relationship between passes and templates. Before you create templates and passes, you must create a campaign to link them all together. Create a Campaign Create a campaign curl https://api-pass.passkit.net/v2/campaigns -X POST -H "Authorization:PKAuth json_web_token" -H "Content-Type: application/json" Campaign c1 = new Campaign (); c1 . name = "MyCampaign" ; c1 . passbookCertId = "MyPassbookCertId" ; c1 . startDate = "2016-01-01T00:00:00Z" ; String createdCampaignName = pk . createCampaign ( c1 ); $data = array('name' => 'MyCampaign','passbookCertId' => 'MyPassbookCertId','startDate' => '2016-01-01T00:00:00Z'); $result = $pk->CreateCampaign($data); Payload example { "name" : "campaignName" , "passbookCertId" : "Poxgb4dEJa" , "status" : "ACTIVE" , "displayName" : "Campaign Name" , "description" : "Campaign Description" , "startDate" : "2016-01-01T00:00:00Z" , "maxIssue" : 0 , "meta" :{ "myKey" : 123 , "myKey2" : "myData" }, "callbackUrl" :{ "onIssueCallbackUrl" : "https://passkit.com/createhook" , "onUpdateCallbackUrl" : "https://passkit.com/updatehook" , "onRegisterCallbackUrl" : "https://passkit.com/registerhook" , "onDeregisterCallbackUrl" : "https://passkit.com/deregisterhook" } } On success the api will respond with the Campaign Name in JSON format: { "name" : "campaignName" } HTTP Request POST https://api-pass.passkit.net/v2/campaigns JSON Body Parameters Parameter Data Type Description name (required) string Your campaign’s unique identifier. The name must only contain letters, numbers or the underscore character. and cannot contain any spaces (e.g. Happy_birthday_2018) . Please note, this identifier cannot be changed after the campaign is created. passbookCertId (required) string This is the certificate ID that is generated by PassKit when you upload a certificate , you can check which certificates you have uploaded with the list certificates endpoint . Please note, the Certificate ID cannot be changed after the campaign is created. status string The value must be either ACTIVE , FROZEN , or INVALID . Default is ACTIVE . The campaign status controls whether passes can be issued or not. ACTIVE - Enables passes to be issued. FROZEN - Passes cannot be issued, existing passes are not affected and this value can be changed back to ACTIVE . INVALID - Passes cannot be issued and all existing passes will be set to invalid. Once the INVALID value is set, it cannot be changed. displayName string This is the human friendly version of your campaign name, this will be displayed to customers when they are looking to download their pass. description string This is your campaign description. The description will be displayed when customers are downloading their pass. This value should detail the campaign offers and customer benefits. startDate (required) ISO8601 datetime The campaign start date. Passes cannot be issued before this time and date. meta JSON Object Metadata to store in campaign level. This data is invisiable to users. endDate ISO8601 datetime The campaign end date. Passes cannot be issued after this date and time, and all existing passes will be set to voided. maxIssue integer This is the maximum number of passes that can be issued within the campaign and can be used to limit the issued passes to a specific amount. Setting the value to 0 will allow an unlimited number off passes that can be issued for the campaign. Default is set at 0. callbackUrl object An object to define event webhooks for pass activities. We will send a POST request to the URL defined in the object. Please see the detail here onIssueCallbackUrl - An event will fire when a pass is created. onUpdateCallbackUrl - An event will fire when a pass is updated onRegisterCallbackUrl - An event will fire when a pass is installed on the Phone onRegisterCallbackUrl - An event will fire when a pass is uninstalled the on the Phone (only available for iOS, Pass2U and mWallet App) Update a Campaign Update a campaign curl https://api-pass.passkit.net/v2/campaigns/campaignName -X PUT -H "Authorization:PKAuth json_web_token" -H "Content-Type: application/json" Campaign c4 = new Campaign (); c4 . displayName = "MyCampaignDisplayName" ; c4 . discription = "MyCampaignDescription" ; String updatedCampaignName = pk . updateCampaign ( "nameOfTargetCampaign" , c4 ); $data = array('displayName' => 'MyCampaignDisplayName'); $result = $pk->UpdateCampaign('MyCampaign',$data); Payload example { "displayName" : "New Display Name" , "description" : "New Campaign Description" , "startDate" : "2016-01-01T00:00:00Z" , "endDate" : "2017-01-01T00:00:00Z" , "maxIssue" : 0 , "meta" :{ "myKey" : 123 , "myKey2" : "myData" }, "callbackUrl" :{ "onIssueCallbackUrl" : "https://passkit.com/createhook" , "onUpdateCallbackUrl" : "https://passkit.com/updatehook" , "onRegisterCallbackUrl" : "https...