NAV
passkit-logo
shell java php

Introduction

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

ERD



The diagram above shows the relationship between different entries.

SDK

We offically maintain the following SDKs.

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:

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

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://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

PUT https://api-pass.passkit.net/v2/campaigns/{campaignName}

URL Parameters

Parameter Data Type Description
campaignName string This is the reference name that you gave your campaign when you created it.

JSON Body Parameters

Parameter Data Type Description
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 ISO8601 datetime The campaign start date. Passes cannot be issued before this date/time. This is a required parameter which can be set at a date in the past or in the future. The value must be set using the ISO8601 datetime format.
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. he value must be set using the ISO8601 datetime format.
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)

Retrieve a Campaign

Retrieve a Campaign

curl https://api-pass.passkit.net/v2/campaigns/campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"
Campaign c2 = null;
c2 = pk.retrieveCampaign("nameOfTargetCampaign");
$result = $pk->GetCampaign('MyCampaign');

Example of server response:

{
  "index":"OABd6Q4X",
  "name":"campaignName",
  "passbookCertId":"Poxgb4dEJa",
  "status":"ACTIVE",
  "startDate":"2016-01-01T00:00:00Z",
  "endDate":"2017-01-01T00:00:00Z",
  "createdAt":"2016-03-09T06:31:02.792548789Z",
  "updatedAt":"2016-03-09T07:10:49.350777006Z",
  "displayName":"Campaign Name",
  "description":"Campaign Description",
  "whiteLabel":{},
  "maxIssue":0,
  "issued":0,
  "meta":{
    "myKey":123,
    "myKey2":"myData"
  }
}

HTTP Request

GET https://api-pass.passkit.net/v2/campaigns/{campaignName}

URL Parameters

Parameter Data Type Description
campaignName string This is the reference name that you gave your campaign when you created it.

JSON Response

Parameter Data Type Description
index string This is the index reference of your campaign.
name string This is the reference name that you gave your campaign when you created it.
passbookCertId string This is the Certificate ID of the certificate you chose for this campaign, you can check the specific certificate details with the retrieve certificate endpoint.
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.
startDate ISO8601 datetime The campaign start date. Passes cannot be issued before this time and date. Although this is a required parameter, you can always set the start date to be in the past.
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.
createdAt ISO8601 datetime This is when your campaign was created.
updatedAt ISO8601 datetime This is when your campaign was last updated.
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.
meta JSON Object Metadata to store in campaign level. This data is invisiable to users.
whiteLabel WhiteLabelObject This is used to customise the campaign landing page. At the moment this feature is only available via a custom implementation. Please contact us with any enquiries.
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.
issued integer This is total number of passes that have currently been issued for this campaign.
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)

Retrieve all Campaigns

Retrieve all Campaigns

curl https://api-pass.passkit.net/v2/campaigns
  -X GET
  -H "Authorization:PKAuth json_web_token"
Campaign[] c3 = null;
c3 = pk.retrieveAllCampaign();
$result = $pk->ListCampaigns();

Example of server response:

[
  {
    "index":"OABd6Q4X",
    "name":"campaignName",
    "passbookCertId":"Poxgb4dEJa",
    "status":"ACTIVE",
    "startDate":"2016-01-01T00:00:00Z",
    "endDate":"2017-01-01T00:00:00Z",
    "createdAt":"2016-03-09T06:31:02.792548789Z",
    "updatedAt":"2016-03-09T07:10:49.350777006Z",
    "displayName":"Campaign Name",
    "description":"Campaign Description",
    "whiteLabel":{},
    "maxIssue":0,
    "issued":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"
    }
  },
  {
    "index":"OABd6Q4X",
    "name":"campaignName2",
    "passbookCertId":"Poxgb4dEJa",
    "status":"ACTIVE",
    "startDate":"2016-01-01T00:00:00Z",
    "endDate":"2017-01-01T00:00:00Z",
    "createdAt":"2016-03-09T06:31:02.792548789Z",
    "updatedAt":"2016-03-09T07:10:49.350777006Z",
    "displayName":"Second Campaign Name",
    "description":"Second Campaign Description",
    "whiteLabel":{},
    "maxIssue":0,
    "issued":0
  }
]

HTTP Request

GET https://api-pass.passkit.net/v2/campaigns

This endpoint will return an array of all of your available campaigns. The structure of each array entry is the same as for a single campaign.

Apple Certificates

When issuing passes for Apple Wallet they must be signed with a Pass Certificate (generated from a Pass Type ID) which are used by Apple to verify the data that is being sent to them. To generate a certificate you will need an Apple Developer Account (why?) and a CSR supplied by PassKit.

For detailed instructions regarding generating and uploading your own Pass Certificates, please see our help centre topic. When using the API to upload a Pass Certificate you will need to download a CSR file via the API, and then uploaded with the API using the API when finished.

Generate CSR

Generating CSR

$result = $pk.GenerateCSR();
curl https://api-pass.passkit.net/v2/passbookCsrs
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -o /path/to/download.csr

# Using -o with cURL to download the csr file to a specific location and name.

HTTP Request

POST https://api-pass.passkit.net/v2/passbookCsrs

Upload Certificate

To upload a certificate, the request must be sent via multipart form

$data = array('name' => 'MyCertificate','description' => 'MyCertificateDiscription');
$result = $pk->UploadCertificate($data, 'path/to/certificate.cer');
curl https://api-pass.passkit.net/v2/passbookCerts
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -F "passbookCER=@certificate.cer"
  -F "jsonBody=$jsonBody"

Example of jsonBody payload

{
  "name":"My Certificate",
  "description":"The certificate I created"
}

The above request will return the Certificate ID (generated by PassKit) in JSON format:

{
  "id": "Poxgb4dEJa"
}

HTTP Request

POST https://api-pass.passkit.net/v2/passbookCerts

Multipart Form Parameters

A Pass Certificate is uploaded using a Multipart Form, the attachments are:

Parameter Type Description
passbookCER CER file This is the certificate file, it needs to be in CER format
jsonBody JSON string This field is optional and contains the name and description for the certificate

JSON Body Parameters

Parameter Data Type Description
name
(optional)
string This is the name of your certificate, this is only used to help you identify the certificate
description
(optional)
string This is the description of your certificate, this is only used to help you identify the certificate

Renew Certificate

To new a certificate, the request must be sent via multipart form

curl https://api-pass.passkit.net/v2/passbookCerts/{certificateID}
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -F "passbookCER=@certificate.cer"
  -F "jsonBody=$jsonBody"

Example of jsonBody payload

{
  "name":"My Certificate",
  "description":"The certificate I created"
}

The above request will return the Certificate ID (generated by PassKit) in JSON format:

{
  "id": "Poxgb4dEJa"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passbookCerts/{certificateID}

Multipart Form Parameters

A Pass Certificate is uploaded using a Multipart Form, the attachments are:

Parameter Type Description
passbookCER CER file This is the certificate file, it needs to be in CER format
jsonBody JSON string This field is optional and contains the name and description for the certificate

JSON Body Parameters

Parameter Data Type Description
name
(optional)
string This is the name of your certificate, this is only used to help you identify the certificate
description
(optional)
string This is the description of your certificate, this is only used to help you identify the certificate

Retrieve Certificate Information

Retrieving Certificate

$result = $pk.GetCertificateDetails('MyCertificateId');
curl https://api-pass.passkit.net/v2/passbookCerts/{certificateID}
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return the certificate information in JSON format:

{
  "id":"Poxgb4dEJa",
  "passTypeId":"pass.com.example.app",
  "name":"My Certificate",
  "description":"The certificate I created",
  "validFrom":"2015-08-06T05:19:21Z",
  "validUntil":"2016-08-05T05:19:21Z",
  "teamName":"YourCompany",
  "teamCode":"YourCompanyCode",
  "createdAt":"2016-01-08T11:32:52.57531013Z",
  "updatedAt":"2016-01-08T11:32:52.575311554Z"
}

HTTP Request

GET https://api-pass.passkit.net/v2/passbookCerts/{certificateId}

URL Parameters

Parameter Data Type Description
certificateId string This is the Certificate ID returned when you uploaded a certificate

JSON Response

Parameter Data Type Description
id string This is the Certificate ID returned when you uploaded a certificate
passTypeId string This is the the Pass Type ID that you registered with Apple
name string This is the name of your certificate, this is only used to help you identify the certificate
description string This is the description of your certificate, this is only used to help you identify the certificate
validFrom ISO8601 datetime This is date that your certificate is valid from.
validUntil ISO8601 datetime This is date that your certificate is valid until.
teamName string This is your Apple developer account team name.
teamCode string This is your Apple developer account team code.
createdAt ISO8601 datetime This is the date/time your certificate was uploaded
updatedAt ISO8601 datetime This is the date/time your certificate was last updated.

List Your Certificates

Retrieving All Certificate

$result = $pk.ListCertificates();
curl https://api-pass.passkit.net/v2/passbookCerts
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return an array of certificate information in JSON format:

[
  {
    "id":"Poxgb4dEJa",
    "passTypeId":"pass.com.example.app",
    "name":"My Certificate",
    "description":"The certificate I created",
    "validFrom":"2015-08-06T05:19:21Z",
    "validUntil":"2016-08-05T05:19:21Z",
    "teamName":"YourCompany",
    "teamCode":"YourCompanyCode",
    "createdAt":"2016-01-08T11:32:52.57531013Z",
    "updatedAt":"2016-01-08T11:32:52.575311554Z"
  }
]

HTTP Request

GET https://api-pass.passkit.net/v2/passbookCerts

JSON Response

The response is similar to the one for retrieving a single certificate, but will list an array of this information, one object for each Pass Certificate.

Templates

Make Your Pass Dynamic

Pass issuers often need to offer passes where the data contained in the pass is unique for a particular pass, and which can be updated only for that one pass. This can be demonstrated with stored value passes, ticketing details and membership details. Please see below for details on enabling dynamic data in your pass.

  1. Dynamic Placeholder
  2. Editable or not
  3. Collect user information via web form

1) Dynamic Placeholder

Example of using dynamic placeholder

{
  "passbook":{
    "header":[
      {
        "defaultLabel":"Points",
        "defaultValue":"#{memberPoints}"
      }
    ]
  }
}

We provide two placeholders that can define dynamic data, they are ${data_key} and #{data_key} (please see section 2 for distinction).

You can add these two placeholders in your template record (e.g text or beacon messages) and our API will loop through the object dynamicData in each pass record replacing all the placeholders in the template one by one. Please see the example in the right column.

You can combine static text with dymamic placeholder as well.

2) User Editable or Not

Dynamic placeholders are classified into two categories and differ slightly to allow identification. One placeholder allows the user add data (for example, adding their name via a web form), and the other prevents the user from adding data, but the field remains dynamic (for example, stored value). These are the standard placeholders used by v2 API, using your own placeholders could cause issues with future v2 API releases.

3) Collecting user information via a web form

Sometimes there is a need to collect information from the user to be shown on the pass when it is issued. To enable this we provide a web form that can be used to collect data during the pass issue process, for example, the users name and telephone number. This information is stored in the Pass Record and can be used to populate fields on the pass creating a more personalised experience. You can see a demo here

This feature can be enabled by using the parameter dynamicKeys in the template record. In addition, you can define some of the data is from your system instead of end-user (e.g. balance, boarding gateway). For more detail, please see dynamicKeys in JSON body parameter.

Dynamic Key Structure

Example json:

{
  "key":"points",
  "type":"number",
  "defaultValue":100,
  "isEditable":false
}
Parameter Type Description
key
(required)
string A key used to define a field shown on the landing page web form during the pass issue process. This value determines the label value of the web form. For example, firstName will become a label First Name on the web form.
type
(required)
string This can be either “dateTime”, “string” or a “number”. This determines data type you need to collect from web form. For example, if the data type is “number”, the user data will be recorded as a number instead of string.
defaultValue string or integer This is the default value used if no data is provided in the web form field.
isEditable boolean This defines whether a field is displayed on the webform. Set to true to display it, otherwise, set to false. Default is false

Dynamic Image Keys

This enables the images on the pass to dynamic. You can use these keys to allow the images to be changed at an individual or specific pass level, and allow users to upload their own images from the pass issue web form. For example, you may want your customers to be able to upload their own profile image to be used on a membership pass.

You can find a live demo here

Dynamic Image Key - Apple Wallet (Passbook)

Apple Wallet (Passbook) images settings MUST be contained inside an object key called “passbook”. There are 5 valid keys for this object, background, footer, logo, strip and thumbnail. For further details regarding images positions, please see Apple Wallet Image Position

Example json:

{
  "passbook":{
    "background":{
      "isDynamic":false,
      "isEditable":false
    },
    "footer":{
      "isDynamic":false,
      "isEditable":false
    },
    "logo":{
      "isDynamic":false,
      "isEditable":false
    },
    "strip":{
      "isDynamic":false,
      "isEditable":false
    },
    "thumbnail":{
      "isDynamic":false,
      "isEditable":false
    }
  }
}
Parameter Type Description
isDynamic bool This enables the image as dynamic. This is achieved by allowing an image ID stored in the pass record to override the default image ID stored in the template record. If set to true, the image of the pass record will always override the template default image. Set to false, the default image ID set in the template will be used.
isEditable bool This enables the user to upload their own image to be used on the pass using the web form. Set as true the user will be directed to a web form to upload an image before the pass is issued. Set at false, the image upload option will not display on the web form. Default is false.

You can find a live demo here

Create a Template

Create a Template

$data_passbook = array('type' => 'storeCard','desc' => 'Description of the template');
$data = array('name' => 'MyTemplate','campaignName' => 'MyCampaign','language' => 'en','startDate' => '2016-01-01T00:00:00Z', 'passbook' => $data_passbook);
$image_files = array('passbook-IconFile' => 'path/to/image.png');
$result = $pk->CreateTemplate($data,$image_files);
Template t1 = new Template();
t1.name = "MyTempalate";
t1.campaignName = "MyCampaign";
t1.language = "en";
t1.startDate = "2016-01-01T00:00:00Z";
t1.passbook = new Passbook();
t1.passbook.type = "storeCard";
t1.passbook.desc = "Description of the template";
HashMap <String,Object> imageHolder1 = new HashMap<String, Object>();
imageHolder1.put("passbook-IconFile", new File("iconFile.png"));
String createdTemplateName = pk.createTemplate(t1, imageHolder1);
# To create a template, image files are required, therefore this request must be sent via **multipart form**
curl https://api-pass.passkit.net/v2/templates
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -F "passbook-IconFile=@icon.png"
  -F "passbook-StripFile=@strip.png"
  -F "passbook-fr-StripFile=@strip-fr.png"
  -F "jsonBody=jsonBody"

Example of jsonBody payload

{
  "name":"templateName",
  "campaignName":"campaignName",
  "status":"ACTIVE",
  "language":"en",
  "startDate":"2010-08-01T00:00:00Z",
  "maxIssue":0,
  "meta":{
    "key1":123,
    "key2":"value"
  },
  "dynamicKeys":[
    {
      "key":"memberPoints",
      "type":"string",
      "defaultValue":null,
      "isEditable":false
    },
    {
      "key":"memberName",
      "type":"string",
      "defaultValue":null,
      "isEditable":true
    }
  ],
  "dynamicImageKeys":{
    "passbook":{
      "background":{
        "isDynamic":false,
        "isEditable":false
      },
      "footer":{
        "isDynamic":false,
        "isEditable":false
      },
      "logo":{
        "isDynamic":false,
        "isEditable":false
      },
      "strip":{
        "isDynamic":false,
        "isEditable":false
      },
      "thumbnail":{
        "isDynamic":false,
        "isEditable":false
      }
    }
  },
  "passbook":{
    "type":"generic",
    "orgName":"Organisation Name",
    "desc":"Basic description of the template.",
    "assoStoreId":[
      967907684
    ],
    "bgColor":"#FFFFFF",
    "labelColor":"#000000",
    "fgColor":"#AAAAAA",
    "header":[
      {
        "changeMsg":"Your new point balance is %@",
        "defaultLabel":"Points",
        "defaultValue":"#{memberPoints}",
        "textAlign":"right",
        "format":{
          "type":"number",
          "numberFormat":"decimal"
        }
      }
    ],
    "secondary":[
      {
        "defaultValue":"Hello ${memberName}",
        "textAlign":"left",
        "format":{
          "type":"text"
        }
      }
    ],
    "back":[
      {
        "defaultValue":[
          {
            "defaultLabel":"Find us",
            "defaultValue":"contact.example.com",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Customer Service Number",
            "defaultValue":"1234567",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "dynamicBackfieldKey":"personalisedOffers",
        "defaultValue":[
          {
            "defaultLabel":"Default Offer A",
            "defaultValue":"Default Offer A information",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Default Offer B",
            "defaultValue":"Default Offer B information",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Default Offer C",
            "defaultValue":"Default Offer C information",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "defaultValue":[
          {
            "defaultLabel":"Terms & Conditions",
            "defaultValue":"These are the terms and conditions for using this pass...",
            "format":{
              "type":"text"
            }
          }
        ]
      }
    ]
  },
  "passbookLang":{
    "fr":{
      "text":{
        "Hello":"Bonjour"
      }
    }
  }
}

A successful call will result with a response including the Template Name in JSON format:

{
  "name": "templateName"
}

HTTP Request

POST https://api-pass.passkit.net/v2/templates

Multipart Form Parameters

To create a template, image files are required, therefore this request must be sent via multipart form. The parameters required are as follows

Parameter Type Description
passbook-{imageType}
(required)
image file These are the image files for the default Apple Wallet template and any alternate languages, see the Image Type section for a list of possible image types and their required format. Only the passbook-IconFile is required to create a template, other images are optional.

The valid values are : passbook-IconFile, passbook-LogoFile, passbook-StripFile, passbook-FooterFile and passbook-ThumbFile.
passbookRedeem-{imageType} image file These are the image files for the redeemed design of the Apple Wallet template and any alternate languages, see the Image Type section for a list of possible image types and their required format. Only the passbookRedeem-IconFile is required to create a redeemed template, other images are optional.

The valid values are : passbookRedeem-IconFile, passbookRedeem-LogoFile, passbookRedeem-StripFile, passbookRedeem-FooterFile and passbookRedeem-ThumbFile.
jsonBody
(required)
string This is the json object defining the template, see the JSON Body Parameters below for information on the structure.

JSON Body Parameters

Parameter Data Type Description
name
(required)
string A unique identifier for your templates. The name must be alpha-numeric and cannot contain spaces. Please note, this cannot be changed after the template is created.
campaignName
(required)
string The uniques identifier you assigned your campaign when it was created using the Create Campaign Method. Please note, this cannot be changed after the template is created.
language
(required)
string This defines the template’s default language. For a list of supported languages please see the Languages List.
startDate
(required)
ISO8601 datetime The template start date. Passes cannot be issued before this time and date.
endDate ISO8601 datetime The template end date. Passes cannot be issued after this date and time, and all existing passes will be set to voided.
status string The value must be either ACTIVE, FROZEN, or INVALID. Default is ACTIVE.

The template 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.
maxIssue integer This is the maximum number of passes that can be issued within the tamplate 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.
timezone float The timezone format should be a number such as -10, 5.5, etc (-10 = -10:00, 5.5 = +05:30). Default is 0.
meta JSON Object Metadata to store in template level. This data is invisiable to users.
dynamicKeys an array of Dynamic Keys You can define what kind of information you want to collect from the end-user during the pass issue process. Once this value is specified, the end-user will be redirected to a landing page containing a web form which is used to collect user information during the pass issue process. For example, specifying email as a key will enable the landing page to show a web form field to collect the user’s email address. This data is stored in a field called dynamicData which held in the pass record when a pass is successfully issued. For more details regarding pass records, please see pass JSON.

You can see a live web form demo here
dynamicImageKeys JSON object A list of flags to control images in the pass. Please see Dynamic Image Keys
passbook
(required)
Apple Wallet Template This holds the design features of this template, for example, pass colours and images. Please see the Apple Wallet Template section for more detail.
passbookRedeem Apple Wallet template When you use the Redeem Method or the Update Pass Method to redeem a pass, the design features of the redeemed template will be applied. For more details regarding the use of the redeem pass method, please see Redeem Pass Method

This option provides an efficient way to apply template design changes after redemption, rather than updating each pass individually via the Update Pass Method.
passbookLang Passbook Language Object This field to defines the different language translations the template supports, please see multiple languages for more information. Please see the Passbook Language Section for details on the structure used and a basic example in the example json side section.
passbookLangRedeem Passbook Language Object This field to defines the different language translations the template supports for the redeemed version of your pass, please see multiple languages for more information. The Passbook Language Section provides details on the structure, which is the same as for the passbookLang parameter.

Retrieve a Template

Retrieve a Template

$result = $pk->GetTemplate('MyTemplate');
Template t2 = null;
t2 = pk.retrieveTemplate("nameOfTargetTemplate");
curl https://api-pass.passkit.net/v2/templates/my_template_name
  -X GET
  -H "Authorization:PKAuth json_web_token"

Response example

{
  "index":"789oyiu",
  "name":"GREATNAME",
  "campaignName":"nameoftheCampaign",
  "status":"ACTIVE",
  "language":"en",
  "startDate":"2010-08-01T00:00:00Z",
  "createdAt":"2016-03-01T03:43:17.918425687Z",
  "updatedAt":"2016-03-01T03:43:17.918426641Z",
  "timezone":0,
  "maxIssue":0,
  "meta":{
    "mykey":"myValue",
    "mykey2":"myValue2"
  },
  "dynamicKeys":[
    {
      "key":"memberPoints",
      "type":"number",
      "defaultValue":null,
      "isEditable":false
    },
    {
      "key":"memberName",
      "type":"string",
      "defaultValue":null,
      "isEditable":true
    }
  ],
  "dynamicImageKeys":{
    "passbook":{
      "background":{
        "isDynamic":false,
        "isEditable":false
      },
      "footer":{
        "isDynamic":false,
        "isEditable":false
      },
      "logo":{
        "isDynamic":false,
        "isEditable":false
      },
      "strip":{
        "isDynamic":false,
        "isEditable":false
      },
      "thumbnail":{
        "isDynamic":false,
        "isEditable":false
      }
    }
  },
  "passbook":{
    "type":"generic",
    "orgName":"Your amazing rewards",
    "desc":"\"Add\" to Wallet \u003e\u003e",
    "bgColor":"#FFFFFF",
    "labelColor":"#000000",
    "fgColor":"#AAAAAA",
    "iconFile":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
    "logoFile":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "header":[
      {
        "changeMsg":"Your new point balance is %@. Thanks for choosing us",
        "defaultLabel":"Points",
        "defaultValue":"${memberPoints}",
        "textAlign":"left",
        "format":{
          "type":"number",
          "numberFormat":"decimal"
        }
      }
    ],
    "primary":[
      {
        "defaultLabel":"Name",
        "defaultValue":"${memberFirstName} ${memberLastName}",
        "format":{
          "type":"text"
        }
      }
    ],
    "auxiliary":[
      {
        "changeMsg":"You're doing great!",
        "defaultLabel":"mylabel",
        "defaultValue":"myvalue",
        "textAlign":"",
        "format":{
          "type":"text"
        }
      }
    ],
    "back":[
      {
        "defaultValue":[
          {
            "defaultLabel":"Find us",
            "defaultValue":"contact.example.com",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Customer Service Number",
            "defaultValue":"1234567",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "dynamicBackfieldKey":"personalisedOffers",
        "defaultValue":[
          {
            "defaultLabel":"Default Offer A",
            "defaultValue":"Default Offer A information",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Default Offer B",
            "defaultValue":"Default Offer B information",
            "format":{
              "type":"text"
            }
          },
          {
            "defaultLabel":"Default Offer C",
            "defaultValue":"Default Offer C information",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "defaultValue":[
          {
            "defaultLabel":"Terms & Conditions",
            "defaultValue":"These are the terms and conditions for using this pass...",
            "format":{
              "type":"text"
            }
          }
        ]
      }
    ]
  },
  "passbookLang":{
    "de":{
      "text":{
        "GREATNAME":"GREATNAME",
        "Company":"Firma",
        "Corporate Account ID":"Firmenkonto",
        "Customer Care":"Kundenservice",
        "Find a Shop":"Ladenverzeichnis",
        "Member ID":"Mitgliedsnummer",
        "Member Since":"Mitglied seit",
        "Partner":"Partner",
        "Platinum":"Platinum",
        "Points":"Punkte",
        "Program":"Programm",
        "Tier":"Status",
        "You are doing great!":"!",
        "Your new point balance is %@. Thanks for choosing Us!":"Sie tun ehrfürchtig!"
      }
    }
  },
  "issued":105677,
  "pushed":34690,
  "passbookDevices":10546,
  "androidPayDevices":11815
}

HTTP Request

GET https://api-pass.passkit.net/v2/templates/{templateName}

To retrieve a specific template you need to send a GET request to the server with the template name. The JSON body response will contain the whole template, comprehensive of every value and attribute related to it.

In the column on the right there is an example of a retrieved pass in English and German, you can identify some features such as the footer and icon image, as well as how many devices have that specific template.

Retrieve all Templates (by Campaign Name)

Retrieve all Templates (by Campaign Name)

$result = $pk->ListTemplatesByCampaign('MyCampaign');
Template[] t3 = null;
t3 = pk.retrieveAllTemplate("nameOfTargetCampaign");
curl https://api-pass.passkit.net/v2/campaigns/campaignName/templates
  -X GET
  -H "Authorization:PKAuth json_web_token"

HTTP Request

GET https://api-pass.passkit.net/v2/campaigns/{campaignName}/templates

This endpoint will return an array of all templates for a campaign. The structure of each array entry is the same as for a single template.

URL Parameters

Parameter Data Type Description
campaignName string This is the reference name that you gave your campaign when you created it.

Update a Template

Update a Template

$data = array('language' => 'de');
$result = $pk->UpdateTemplateData('MyTemplate',$data);
Template t4 = new Template();
t4.language = "de";
String updatedTemplateName = pk.updateTemplate("nameOfTargetTemplate", t4);
curl https://api-pass.passkit.net/v2/templates/templateName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "passbook":{
    "bgColor":"#FFFFFF",
    "labelColor":"#000000"
  }
}

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

This endpoint is used to update all the template attributes apart from images. Changes to the template made using this endpoint are not immediately updated on all passes. To send a template push update please use the Create Template Method

To update template images, please see the Update Template With Images Method

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}

URL Parameters

Parameter Data Type Description
templateName string This is the reference name that you gave your template when you created it.

JSON Body Parameters

The JSON parameters are the same as Create Template Method

Update a Template With Images

Update a Template With Images

$data = array('language' => 'fr');
$update_image_list = array('passbook-LogoFile' => 'path/to/image.png');
$delete_image_list = array('passbook-StripFile');
$result = $pk->UpdateTemplateDataImages('TestTemplate_1',$data,$update_image_list,$delete_image_list);
// Note: Set arguments to null if they are not required to update. 
Template t5 = new Template();
t5.language = "fr";
// refer to `https://dev.passkit.net/#update-a-template-with-images` for a complete attribute list.
HashMap <String,Object> updateImage = new HashMap<String, Object>();
updateImage.put("passbook-IconFile", new File("path/to/image.png"));
String[] deleteImage = {"passbook-LogoFile"}
String updatedTemplateName = pk.updateTemplate("nameOfTargetTemplate", t5, updateImage, deleteImage);
curl https://api-pass.passkit.net/v2/templates/templateName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -F "passbook-IconFile=@icon-new.png"
  -F "jsonBody=$jsonBody"
  -F "updateMultipart=$jsonArray"
# Notes:
# 1 - To update an image file, upload file through curl command and add the respective image field to the jsonArray.
# 2 - To delete an image file, add the respective image field to the jsonArray.

Example of jsonBody payload

{
  "passbook":{
    "bgColor":"#FFFFFF",
    "labelColor":"#000000"
  }
}

Example of jsonArray payload

[
  "passbook-IconFile",
  "passbook-LogoFile"
]

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

To update the images on a template you will need to use a multipart form. All other template attributes are updated separately using the Update Template Method.

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}

URL Parameters

Parameter Data Type Description
templateName string This is the reference name that you gave your template when when using the Create Template Method.

Multipart Form Parameters

The Multipart Form parameters are the same as Create Template Method

JSON Body Parameters

The JSON parameters are the same as Create Template Method

Push Updates

To send a push update to all passes after making changes to the template you can do so using this endpoint.

Push Update

$result = $pk->PushTemplateUpdate('MyTemplate');
String pushedUpdatedTemplateName = pk.pushUpdate("nameOfTargetTemplate");
curl https://api-pass.passkit.net/v2/templates/templateName/push
  -X PUT
  -H "Authorization:PKAuth json_web_token"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/templates/{templateName}/push

Additional Information

Passbook Language

The basic layout in json:

    {
        "lang1": {
            "text": {
                "Original Text1": "Language1 Translated Text1",
                "Original Text2": "Language1 Translated Text2"
            }
        },
        "lang2": {
            "text": {
                "Original Text1": "Language2 Translated Text1",
                "Original Text2": "Language2 Translated Text2"
            }
        }
    }

The basic layout of the passbook language object is shown on the right. The variables in the example are as follows:

Parameter Type Description
lang
(required)
string lang1 and lang2 in the example should be chosen from the list of supported languages. You can use as many languages as you need as long as they are supported.
Original Text
(required)
string The “Original Text” variables should be the text from your original template that you want to translate. They must match the text in the original template exactly.
Translated Text
(required)
string The “Translated Text” should be translated text from the “Original Text” in the other language you have chosen. The text will be used to exactly replace the corresponding original text when the device is set to that language.

Apple Wallet Template

Apple Wallet Documentation

Our API follows the original Apple structure closely, sometimes it may be necessary to refer back to Apple’s doccumentation to understand the true purpose of an optional field, as they are not always immediately obvious. We have left our API as open as possible to allow the full flexibility that Apple can provide with their passes.

Overall Structure

The overall json:

{
  "type":"general",
  "orgName":"Example Company",
  "desc":"Description of the template",
  "assoStoreId":[
    284882215
  ],
  "appLaunchUrl":"fb://profile/331998086879963",
  "bgColor":"#500000",
  "labelColor":"#200000",
  "fgColor":"#000000",
  "logoText":"My Company",
  "transitType":"air",
  "header":[
    {
      "itemName":"Balance",
      "changeMsg":"You got %@ HKD",
      "defaultLabel":"Balance",
      "defaultValue":"#{balance=0}",
      "textAlign":"left",
      "format":{
        "type":"number",
        "numberFormat":"decimal",
        "currencyCode":"HKD"
      }
    }
  ],
  "primary":[
    {
      "defaultLabel":"Points",
      "defaultValue":"#{points=0}",
      "textAlign":"left",
      "format":{
        "type":"number",
        "numberFormat":"decimal"
      }
    },
    {
      "defaultLabel":"Name",
      "defaultValue":"${name}",
      "format":{
        "type":"string"
      }
    }
  ],
  "auxiliary":[
    {
      "defaultLabel":"Offer",
      "defaultValue":"Buy one get one free",
      "format":{
        "type":"string"
      }
    },
    {
      "defaultLabel":"Expiry Date",
      "defaultValue":"2019-05-26T05:38:20+08:00",
      "format":{
        "type":"date",
        "dateFormat":"short"
      }
    }
  ],
  "secondary":[

  ],
  "back":[

  ],
  "beacons":[
    {
      "major":0,
      "minor":0,
      "uuid":"19d5f76a-fd04-5aa3-b16e-e93277163af6",
      "relevantText":"Welcome to PassKit"
    }
  ],
  "locations":[
    {
      "alt":15,
      "lat":22.28735687010302,
      "lon":114.14827988250626,
      "relevantText":"Welcome to PassKit"
    }
  ],
  "maxDist":10,
  "relevantDate":"2019-08-01T00:00:00Z",
  "barcode":{
    "altText":"Text below the barcode",
    "altTextOption":"text",
    "format":"pdf417",
    "message":"BarcodeText",
    "messageOption":"text",
    "messageEncoding":"UTF-8"
  },
  "nfc":{
    "message":"messageForTerminal",
    "encryptionPublicKey":"L0ngRand0m3ncrypt1onK3y"
  } 
}

The example json shows all the possible fields that can be used when creating a pass, and example data for most fields. You will not need to use all these fields, however we have provided a list below with descriptions for your reference. The list follows the json object from top to bottom.

Parameter Data Type Description
type
(required)
string Valid options for this parameter are: boardingPass, coupon, storeCard, generic, eventTicket
desc
(required)
string This is a a brief description of the template, it is used by apple for user accessibility.
orgName string This is the name of the company or organisation issuing the pass.
assoStoreId array of integers This is used to display and link to an app on the back of the pass. Each number in the array should be an iTunes Adam ID, the pass will ONLY display the first app in the array which is compatible with the current device.
appLaunchUrl string This is used to specify a deep link into the app displayed on the back of the pass (the app is chosen from the assoStoreId). If the app supports deep linking, you can use this url to go to a specific point within the app when it is opened.
bgColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the background colour of the pass. (deprecated)
labelColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the label colour of the pass. (deprecated)
fgColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the foreground colour of the pass. (deprecated)
logoText string This is the logo text displayed on your template.
transitType string This field is required for boarding passes, it defines which travel mode icon is displayed on the pass. Available values are air, boat, bus, generic, and train. the default value is generic.
header 
primary 
auxiliary 
secondary 
array of passbook template fields These four fields contain the text that is displayed on the front of the pass. These fields follow the same format described below in the passbook template fields section. The primary field(s) do not have the text align attribute.
back  an array of backfield groups These fields contain the text that is displayed in the pass backfields. Adresses and phone numbers are automatically made tapable and the href attribute can be be used with links.
beacons  Beacons allow you to display subtle messages to your users when they are in close proximity. Ideally used in places where a user may want to access the pass. For more information regarding beacons and their use, please see our GemTots Page or download our guide to iBeacon.
    - major integer This is the major id of your beacon. Valid range is 0 - 65535.
    - minor integer This is the minor id of your beacon. Valid range is 0 - 65535.
    - uuid string This is the UUID of your beacon
    - relevantText string This is the message is displayed on the device lockscreen when the device is in proximity to a recognised beacon.
locations  Locations provide a broader range using GPS to trigger a lockscreen message.
    - alt  integer This is an optional setting to allow the notification to only trigger at a certain altitude, useful in shopping malls.
    - lat float This is the latitude of the location.
    - lon float This is the longitude of the location.
    - relevantText string This is the message that will display on the lockscreen when the device is within range of the location.
maxDist integer Maximum distance in meters from a relevant latitude and longitude that the releventText will be displayed. Apple will use the default max range (either 100m or 1000m depending on the Pass Type) if it is less than the value set here.
relevantDate ISO8601 datetime This allows you to set a date and time when the pass location notification is relevant. For example an event ticket should show on the lockscreen at the time of the event for it to be relevant. The use of this parameter is dependent on the Pass Type being used.
barcode
    - altText string This is the alternative text for your barcode, it is displayed directly under the barcode.
    - altTextOption string Can be either text, pid, or none. Setting to text will display the altText underneath the barcode, setting to pid will override the altText field and display the pass id below the barcode, setting to none will display no alternative text under the barcode.
    - format string This is the format of the barcode, it can be qr, pdf417, aztec, or code128
    - message string This is the message that is encoded in the barcode
    - messageOption string Can be set as text or pid. Setting to text will encode the text from the message field above, setting to pid will override the message and encode the pass id in the barcode.
    - messageEncoding string This is the text encoding for the barcode, any IANA character set name can be used.
nfc Note that you need to have a special NFC certificate from Apple in order to enable this feature. Contact us directly with any enquiries regarding custom solutions involving NFC.
    - message string This is the data that is sent to the NFC terminal.
    - encryptionPublicKey string This is the public encryption key used to ensure the NFC transaction is secure.

Passbook Template Field

The json for a template field (header, auxiliary, secondary, primary):

{
    "itemName": "secondaryField1",
    "attributedValue": "<a href=\"https://passkit.com\">PassKit</a>",
    "changeMsg": "Value Changed",
    "defaultLabel": "Item Label",
    "defaultValue": "Item Value",
    "textAlign": "left",
    "format": {
        "type": "text",
        "dateFormat": "short",
        "timeFormat": "long",
        "ignoreTimezone": true,
        "isRelative": false,
        "currencyCode": "",
        "numberFormat": "decimal"
    }
}

Please refer to the Apple Documentation for full details regarding the Apple Wallet template fields. This will help clarify when certain fields should be used.

Parameter Data Type Description
itemName string This is a unique identifier for a template field. This value must not be reused in the same template. If you do not provide an itemName, we will automatically generate one for you.
defaultLabel
(required)
string This is the field label that is displayed on the pass.
defaultValue
(required)
string, number or ISO8601 datetime This is the field value displayed on the pass, it must match the field format selected for that field.
attributedValue string The attributed value allows you to enter html links. It will override the default value. The format only allows the <a href=""></a> tag with a href attribute.
changeMsg string This message will be displayed as a notification when this field is updated. If %@ is used in the change message it will be replaced with the new field value when the message is displayed.
textAlign string This field sets the alignment of the field, the possible settings are left, center, right, and natural. This field is not used in the primary field(s). Default is left.
format
(required)
    - type
(required)
string This is the field type, the possible values are text, number, currency, date, or dateTime
    - dateFormat string This used when the date, or dateTime field type is selected. The value can be none, short, medium, long, or full which will affect the length of the date displayed.
    - timeFormat string This is used when the date, or dateTime field type is selected. The value can be none, short, medium, long, or full which will affect the length of the time section displayed.
    - ignoreTimezone boolean This is used when the date, or dateTime field type is selected. If true, the time will display in the given time zone, not the user’s time zone.
    - isRelative boolean This is used when the date, or dateTime field type is selected. If true, the time will display as a relative date, otherwise the date is displayed as an absolute date.
    - currencyCode string ISO 4217 currency code. This is only used when the currency field type is selected, the code must be in the list of currency codes
    - numberFormat string This is used when the number field type is selected. The value can be decimal, percent, scientific, or spellout.

Passbook Backfield Group

Backfield groups allow you to define a set of backfields that can be replaced by dynamic backfields on the pass level. Please see the following diagram:

passbook backfield diagram

The json for a custom backfield:

{
  "dynamicBackfieldKey":"custom-promotions",
  "defaultValues":[
    {
      "itemName":"backfield1",
      "attributedValue":"<a href=\"https://passkit.com\">PassKit</a>",
      "changeMsg":"Value Changed",
      "defaultLabel":"Default Promotion A",
      "defaultValue":"Default Promotion A Value",
      "format":{
        "type":"text",
        "dateFormat":"short",
        "timeFormat":"long",
        "ignoreTimezone":true,
        "isRelative":false,
        "currencyCode":"",
        "numberFormat":"decimal"
      },
      "detectorType":[
        "link"
      ]
    },
    {
      "itemName":"backfield2",
      "defaultLabel":"Default Promotion B",
      "defaultValue":"Default Promotion B Value",
      "format":{
        "type":"text",
        "dateFormat":"short",
        "timeFormat":"long",
        "ignoreTimezone":true,
        "isRelative":false,
        "currencyCode":"",
        "numberFormat":"decimal"
      },
      "detectorType":[

      ]
    }
  ]
}

The pass will combine the template and pass record to create a pass. You can see an example here.

If you want to provide a custom list of back fields on each user’s pass (for example, a personalised list of promotions) then you can set the dynamicBackfieldKey for any group of backfields.

To see how backfields and backfield groups work you can use this helper tool to try out different configurations.

Parameter Data Type Description
defaultValues
(required)
array of Passbook Template Back Fields These are the default values for the backfield group . If no dynamicBackfieldKey is provided then these backfields will always be displayed. Fields will appear in order on the back of the pass.
dynamicBackfieldKey string An optional string to provide the key name for dynamic backfields. If there is a matching key on the user’s pass, the backfields on the pass will be used instead of the defaultValue backfields for this backfield group.

Passbook Template Backfield

The json for a template backfield:

{
  "itemName":"backfield1",
  "attributedValue":"<a href=\"https://passkit.com\">PassKit</a>",
  "changeMsg":"Value Changed",
  "defaultLabel":"Item Label",
  "defaultValue":"Item Value",
  "format":{
    "type":"text",
    "dateFormat":"short",
    "timeFormat":"long",
    "ignoreTimezone":true,
    "isRelative":false,
    "currencyCode":"HKD",
    "numberFormat":"decimal"
  },
  "detectorType":[
    "phone",
    "link",
    "address",
    "event"
  ]
}

A template backfield is similar to the fields on the front of the pass and they follow a similar structure to Apple’s Wallet specification, for further details please read the Apple Documentation regarding template fields.

Parameter Data Type Description
itemName string This is a unique identifier for a template field. This value must not be reused in the same template. If you do not provide an itemName, we will automatically generate one for you.
defaultLabel
(required)
string This is the field label that is displayed on the pass.
defaultValue
(required)
string, number or ISO8601 datetime This is the field value displayed on the pass, it must match the field format selected for that field.
attributedValue string The attributed value allows you to enter html links. It will override the default value. The format only allows the <a href=""></a> tag with a href attribute.
changeMsg string This message will be displayed as a notification when this field is updated. If %@ is used in the change message it will be replaced with the new field value when the message is displayed.
textAlign string This field sets the alignment of the field, the possible settings are left, center, right, and natural. This field is not used in the primary field(s). Default is left.
format
(required)
    - type
(required)
string This is the field type, the possible values are text, number, currency, date, or dateTime
    - dateFormat string This used when the date, or dateTime field type is selected. The value can be none, short, medium, long, or full which will affect the length of the date displayed.
    - timeFormat string This is used when the date, or dateTime field type is selected. The value can be none, short, medium, long, or full which will affect the length of the time section displayed.
    - ignoreTimezone boolean This is used when the date, or dateTime field type is selected. If true, the time will display in the given time zone, not the user’s time zone.
    - isRelative boolean This is used when the date, or dateTime field type is selected. If true, the time will display as a relative date, otherwise the date is displayed as an absolute date.
    - currencyCode string ISO 4217 currency code. This is only used when the currency field type is selected, the code must be in the list of currency codes
    - numberFormat string This is used when the number field type is selected. The value can be decimal, percent, scientific, or spellout.

Passbook Image Position

strip image

thunbnail image

logo and footer image

Passbook Image Types

When creating or updating a template, you may need to include image files. The naming convention for the multipart form upload is as follows:

Each file key begins with either passbook- or passbookRedeem- depending on whether it belongs to the template default state or the template redeemed state. If the image is to be used on a translated version of the pass an additional string is added to show which language the image is for. Example: passbook-fr-, the language codes are found here. Finally the image type that you are uploading is appended to the end of the file key name. For example passbook-IconFile is the default icon image for the template, passbook-fr-IconFile will be used instead if the user has the language set to French.

The exact specifications relating to using images in Apple wallet can be found in their developer documentation. The list of image types that can be uploaded is as follows:

Image Type Position on the Pass Other Notes Dimensions
IconFile Displayed on the lock screen as part of a notification, and apps like “Mail” when showing that a pass is attached 29 x 29
LogoFile Displayed in the top left corner of the Pass The maximum width is 320 pixels. In most cases it should be narrower. Please note, if you use the full pixel width you may not have room to display the Logo Text or Header Fields. 320 x 100
StripFile Displayed behind the Primary Fields On iPhone 6 and 6 Plus, the space is 750 x 196 for event tickets, 750 x 288 for gift cards and coupons, and 750 x 246 in all other cases.
On earlier models, the space is 640 x 168 for event tickets, 640 x 220 for square barcodes on devices with 3.5 inch screens, and 640 x 246 in all other cases.
FooterFile Displayed directly bove the barcode Available when using the Transport Pass Type 572 x 30
ThumbFile Displayed next to the fields on the front right of the pass The aspect ratio should be in the range of 2:3 to 3:2, otherwise the image is cropped Up to 180 x 180
BgFile Behind the entire front of the pass Available when using Event Pass Type. The image is cropped slightly on all sides and blurred 360 x 440

Passes

Create a Pass

Example of a pass creation request

$data = array('templateName' => 'MyTemplate');
$result = $pk->CreatePass($data);
Pass p1 = new Pass();
p1.templateName = "MyTemplate";
String createdPassName = pk.createPass(p1);
curl https://api-pass.passkit.net/v2/passes
  -X POST 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "templateName":"templateName",
  "dynamicData":{
    "name":"Nicholas Bortoluzzi",
    "nickName":"LKF Killer",
    "point":12,
    "balance":952.24
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbook":{
    "groupId":"airline-1",
    "bgColor":"#FFFFFF",
    "labelColor":"000000",
    "fgColor":"#E4F9A0",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

POST https://api-pass.passkit.net/v2/passes

JSON parameters

Data type Description
templateName
(required)
string This is the name of the template you created. For more detail, please see Create Template. If you are using CherryPie, you can find the template name in the template edit page.
dynamicData JSON object This is the user’s unique data. For example, customer name, date of birth, membership number. etc. The data will not show on the pass until it is defined in the template. See the example json for an example of the format.
dynamicImages JSON object This is used to define a dynamic image for a pass, like a profile image on a membership pass. The value is the image path from Images Upload Endpoint. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields JSON object Please see Passbook Backfields
userDefinedId string This allows a unique Id to be added to the pass record that can provide easy compatibilty with an existing system using unique customer identifiers (e.g. membership numbers). You can retrieve pass data by using this endpoint via userDefinedId and campaignName instead of pass ID. This value must be unique within a campaign, and once this value is set, it cannot be changed.
recoveryEmail string The user’s email address. If this parameter is used, the user will receive an email containing a link to the pass.
isVoided bool When this field set to true, the pass will be voided. When the pass is voided the barcode will be greyed out and beacon and location notification will be turned off. Default value is false.
isRedeemed bool When this field set to true, the pass will be marked as redeemed. Default value is false
isInvalid bool When this field set to true, the pass is set as invaludated. The barcode, beacon and location messages will be removed and the pass can no longer be communicated with. Once a pass is set as invalidated, it cannot be changed. Default is false.
expiryDate ISO8601 datetime This is the pass expiry date. After the expiry date, the pass is automatically voided (seeisVoided). This value will override the template and campaign end date value.
passbook JSON object This is where the Apple Wallet (Passbook) specific parameters are defined. Please see Passbook

Passbook

This object allow you to define Apple Wallet (Passbook) specific parameters.

JSON parameters

Data type Description
groupId string This is an optional parameter used only for event tickets and boarding passes. This is the identifier used to group related passes. If a grouping identifier is specified, passes with the same style, pass type identifier, and grouping identifier are displayed as a group within Apple Wallet. Otherwise, passes are grouped automatically. Use this to group passes that are tightly related, such as the boarding passes for different connections of the same trip.
Available in iOS 7.0+ devices
bgColor string This parameter will override background color of the template. For example, If you set this value to #ffffff, this will override the template value of #000000 and the pass will show a background colour of #ffffff.
labelColor string This parameter will override label color set in the template, in the same way as using bgColor.
fgColor string This parameter will override foreground color set in the template, in the same way as using bgColor..
userInfo JSON Object Custom information for companion apps. This data is not displayed to the user.
For example, a pass for a cafe could include information about the user’s favorite drink and sandwich in a machine-readable form for the companion app to read, making it easy to place an order for “the usual” from the app.

Retrieve a Pass

Example of a pass retrieve request

$result = $pk->GetPassById('PassId');
Pass p2 = null;
p2 = pk.retrievePass("idOfTargetPass");
curl https://api-pass.passkit.net/v2/passes/RanD0mStr1ng
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

{
  "id":"RanD0mStr1ng",
  "campaignName":"campaignName",
  "templateName":"templateName",
  "passbookDevices":0,
  "androidPayDevices":0,
  "updatedAt":"2016-03-15T23:42:56.271326844Z",
  "createdAt":"2016-03-15T23:42:56.271325489Z",
  "dynamicData":{
    "name":"Hello",
    "number":123,
    "float":123.34215
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Ohffer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":false,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbookMeta":{
    "groupId":"airline-1",
    "bgColor":"#000000",
    "labelColor":"#000000",
    "fgColor":"#000000",
     "userInfo":{
        "key":"value"
    }
  }
}

HTTP Request

GET https://api-pass.passkit.net/v2/passes/{passId}

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass.

JSON Response

Data type Description
id string This is the pass Id that was returned when you created the pass.
dynamicData JSON object The dynamic data that the pass contains.
dynamicImages JSON object The dynamic images set in the pass. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields JSON object Please see Passbook Backfields
userDefinedId string This displays the user defined ID for the pass, if specified when the pass was created.
campaignName string The campaign name the pass is associated with. Please see Create Campaign.
templateName string The template name that the pass was issued from. Please see Create Template.
passbookDevices integer The number of Passbook (Apple) devices that the pass is registered on.
androidPayDevices integer The number of Android Pay devices that the pass is registered on.
updatedAt ISO8601 datetime The date and time the pass was last updated
createdAt ISO8601 datetime The date and time the pass was created.
firstUnregisteredAt ISO8601 datetime The date and time the pass was first unregistered.
lastUnregisteredAt ISO8601 datetime The date and time the pass was most recently unregistered
firstRegisteredAt ISO8601 datetime The date and time the pass was first registered on a device
lastRegisteredAt ISO8601 datetime The date and time the pass was most recently registered on a device
isVoided bool A true value shows the pass is voided.
isRedeemed bool A true value shows the pass is in a redeemed state, if redeem status is enabled in your template.
isInvalid bool A true value show the pass is invalidated. An invalidated pass will have the barcode, beacon, and location messages removed and the pass can no longer be communicated with.
expiryDate ISO8601 datetime The Pass expiry date. After the expiry date, the pass will automatically be voided (same effect of isVoided). This value will override the template and campaign end date value.
recoveryEmail string This is the recovery email that was added when the pass was created.

Retrieve a Pass with User Defined Id

Example of a pass retrieve request

$result = $pk->GetPassByUserDefinedId('UserDefinedID','MyCampaign');
Pass p3 = null;
p3 = pk.retrievePass("userDefinedIdOfTargetPass","campaignOfTargetPass");
curl https://api-pass.passkit.net/v2/passes?userDefinedId=12345&campaignName=campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"

Server response is the same as from a normal retrieve pass

HTTP Request

GET https://api-pass.passkit.net/v2/passes?userDefinedId={userDefinedId}&campaignName={campaignName}

URL Parameters

Parameter Data Type Description
userDefinedId string This is the user defined id that was assigned when the pass was created. If a user defined id was not assigned at pass creation, the pass must be updated to include a user defined id before this method can be used.
campaignName string This is the reference name that you gave your campaign when it was created.

Update a Pass

Example of pass update request

$data = array('recoveryEmail' => 'apoorva@passkit.com');
$result = $pk->UpdatePassById('PassId',$data);
Pass p4 = new Pass();
p4.recoveryEmail = "apoorva@passkit.com";
String updatedPassId = pk.updatePass("idOfTargetPass", p4);
curl https://api-pass.passkit.net/v2/passes/RanD0mStr1ng
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "templateName":"10_percent_off",
  "dynamicData":{
    "name":"Duncan Brown",
    "nickName":"Druncan",
    "points":20
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbookMeta":{
    "groupId":"airline-1",
    "bgColor":"#000000",
    "labelColor":"#000000",
    "fgColor":"#000000",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passes/{passId}

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass

JSON parameters

Data type Description
templateName string This value can be the templateName of any template being used by a campaign. For example, you can update this field from 10_percent_off_coupon to PassKit_membership_card, the pass data will remain the same, but the new template design will be used. Only the templates within same campaign can be used.
dynamicData JSON object This is the user’s unique data. For example, customer name, date of birth, membership number. etc. The data will not show on the pass until it is defined in the template. See the example json for an example of the format.
dynamicImages JSON object This is used to define a dynamic image for a pass, like a profile image on a membership pass. The value is the image path from Images Upload Endpoint. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields JSON object Please see Passbook Backfields
userDefinedId string This allows a unique Id to be added to the pass record that can provide easy compatibilty with an existing system using unique customer identifiers (e.g. membership numbers). You can retrieve pass data by using this endpoint via userDefinedId and campaignName instead of pass ID. This value must be unique within a campaign, and once this value is set, it cannot be changed.
recoveryEmail string The user’s email address. If this parameter is used, the user will receive an email containing a link to the pass.
isVoided bool When this field set to true, the pass will be voided. When the pass is voided the barcode will be greyed out and beacon and location notification will be turned off. Default value is false.
isRedeemed bool When this field set to true, the pass will be marked as redeemed. Default value is false
isInvalid bool When this field set to true, the pass is set as invaludated. The barcode, beacon and location messages will be removed and the pass can no longer be communicated with. Once a pass is set as invalidated, it cannot be changed. Default is false.
expiryDate ISO8601 datetime This is the pass expiry date. After the expiry date, the pass is automatically voided (seeisVoided). This value will override the template and campaign end date value.
passbook JSON object This is where the Apple Wallet (Passbook) specific parameters are defined. Please see Passbook

Updating a Pass with a User Defined Id

Example of pass update request

$data = array('recoveryEmail' => 'apoorva@passkit.com');
$result = $pk->UpdatePassByUserDefinedId('UserDefinedID','MyCampaign',$data);
Pass p5 = new Pass();
p5.recoveryEmail = "apoorva@passkit.com";
String updatedPassId = pk.updatePass("userDefinedIdOfTargetPass","campaignOfTargetPass", p5);
curl https://api-pass.passkit.net/v2/passes?userDefinedId=12345&campaignName=campaignName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "templateName":"templateName",
  "dynamicData":{
    "name":"Nicholas Bortoluzzi",
    "nickName":"LKF Killer",
    "point":12,
    "balance":952.24
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbook":{
    "groupId":"airline-1",
    "bgColor":"#FFFFFF",
    "labelColor":"000000",
    "fgColor":"#E4F9A0",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passes?userDefinedId={userDefinedId}&campaignName={campaignName}

URL Parameters

Parameter Data Type Description
userDefinedId string This is the user defined id that was assigned when the pass was created. If a user defined id was not assigned at pass creation, the pass must be updated to include a user defined id before this method can be used.
campaignName string This is the reference name that you gave your campaign when it was created.

JSON parameters

The JSON parameters are the same as Update Pass Method

Redeem a Pass

This method is a wrapper of Update Pass Method to simplify redemption process. This endpoint will update the pass data - isRedeemed from false to true. You can define a redeem status (e.g. passbookRedeem) in the template record. For more details regarding template records, please see JSON parameters of Template. When you call the endpoint using a pass ID, the redeem status of the template will automatically apply to a pass, instead of using the update pass method to change pass style individually.

Example of pass redeem request

// Not available yet
string redeemedPassId = pk.redeemPass("idOfTargetPass");
curl https://api-pass.passkit.net/v2/passes/RanD0mStr1ng/redeem
  -X PUT 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passes/{passId}/redeem

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass

JSON parameters

No payload is needed.

Batch Pass Methods

Batch Create Passes

Example of batch pass creation request

$data = array('passes' => array(array('templateName' => 'MyTemplate'),array('templateName' => 'MyTemplate')));
$result = $pk->CreatePassBatch($data);
Pass[] p6 = new Pass[2];
p6[0] = new Pass();
p6[0].templateName = "MyTemplate";
p6[1] = new Pass();
p6[1].templateName = "MyTemplate";
String[] createdPassIdArray = pk.createPassBatch(p6);
curl https://api-pass.passkit.net/v2/passesBatch
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "passes":[
    {
      "templateName":"templateName",
      "dynamicData":{
        "name":"Nicholas Bortoluzzi",
        "nickName":"LKF Killer",
        "point":12
      },
      "dynamicImages":{
        "passbook":{
          "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
          "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
          "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
          "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
          "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
          "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
        }
      },
      "dynamicBackfields":{
        "personalised-offers":[
          {
            "label":"Offer X",
            "value":"Offer X information"
          },
          {
            "label":"Offer Y",
            "value":"Offer Y information"
          },
          {
            "label":"Offer Z",
            "value":"Offer Z information"
          }
        ],
        "birthday-offers":[
          {
            "label":"Happy Birthday",
            "value":"Buy one get two free"
          }
        ]
      },
      "userDefinedId":"E1234567",
      "recoveryEmail":"hello@passkit.com",
      "isVoided":true,
      "isRedeemed":true,
      "expiryDate":"2016-04-11T12:59:40Z",
      "passbook":{
        "groupId":"airline-1",
        "bgColor":"#000000",
        "labelColor":"#000000",
        "fgColor":"#000000"
      }
    },
    {
      "templateName":"templateName2",
      "dynamicData":{
        "name":"Patrick Kosterman",
        "nickName":"Kostrgirl",
        "point":99
      },
      "dynamicImages":{
        "passbook":{
          "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9c.png",
          "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9d.png",
          "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9e.png",
          "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9f.png",
          "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9g.png",
          "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9h.png"
        }
      },
      "dynamicBackfields":{
        "personalised-offers":[
          {
            "label":"Offer X",
            "value":"Offer X information"
          }
        ],
        "birthday-offers":[
          {
            "label":"Happy Birthday",
            "value":"Buy one get two free"
          }
        ]
      },
      "userDefinedId":"E1234568",
      "recoveryEmail":"hello@passkit.com",
      "isVoided":false,
      "isRedeemed":true,
      "expiryDate":"2019-04-11T12:59:40Z",
      "passbook":{
        "groupId":"airline-2",
        "bgColor":"#000000",
        "labelColor":"#000000",
        "fgColor":"#000000",
        "userInfo":{
            "key":"value"
        }
      }
    }
  ]
}

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

{
  "id": [
    "RanD0mStr1ng",
    "IYqwjwde124J"
  ]
}

HTTP Request

POST https://api-pass.passkit.net/v2/passesBatch

JSON parameters

Data type Description
passes
(required)
an array of pass data When using the batch create pass method you can specify an array of data for up to 25 passes, containing the same data as found in create a pass

Batch Update Passes

Example of batch pass update request

$data = array('passes' => array(array('passId' => 'PassId','recoveryEmail' => 'apoorvakatta@gmail.com'),array('passId' => 'PassId','recoveryEmail' => 'apoorvakatta@gmail.com')));
$result = $pk->UpdatePassBatch($data);
Pass[] p8 = new Pass[2];
String[] passIdArray = {"passId1","passId2"};
p8[0] = new Pass();
p8[0].id = passIdArray[0];
p8[0].recoveryEmail = "apoorva@passkit.com";
p8[1] = new Pass();
p8[1].id = passIdArray[1];
p8[1].recoveryEmail = "apoorva@passkit.com";
String[] updatedPassIdArray = pk.updatePassBatch(p8);
curl https://api-pass.passkit.net/v2/passesBatch
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
[
  {
    "id":"RanD0mStr1ng",
    "templateName":"templateName",
    "dynamicData":{
      "points":"10"
    }
  },
  {
    "id":"IYqwjwde124J",
    "passbook":{
      "groupId":"Airline3"
    }
  }
]

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

{
  "id": [
    "RanD0mStr1ng",
    "IYqwjwde124J"
  ]
}

HTTP Request

PUT https://api-pass.passkit.net/v2/passesBatch

JSON parameters

Data type Description
passes
(required)
an array of pass data When using the batch update pass method you can specify an array of data for up to 25 passes, containing the same data as found in update a pass. Please note, each pass in the batch update pass call will also need to have their pass id added to the update call.

Batch Get Passes

Example of batch pass get request

Not available yet
Pass[] p7 = null;
String[] passIdArray = {"passId1","passId2"};
p7 = pk.retrievePassBatch(passIdArray);
curl https://api-pass.passkit.net/v2/passesBatch?id=RanD0mStr1ng,IYqwjwde124J
  -X GET
  -H "Authorization:PKAuth json_web_token"

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

[
  {
    "id":"RanD0mStr1ng",
    "campaignName":"campaignName",
    "templateName":"templateName",
    "passbookDevices":0,
    "androidPayDevices":0,
    "updatedAt":"2016-03-15T23:42:56.271326844Z",
    "createdAt":"2016-03-15T23:42:56.271325489Z",
    "dynamicData":{
      "name":"Hello",
      "number":123,
      "float":123.34215
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
      }
    },
    "userDefinedId":"E1234567",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":true,
    "isRedeemed":true,
    "isInvalid":false,
    "expiryDate":"2016-04-11T12:59:40Z",
    "passbookMeta":{
      "groupId":"airline-1",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000"
    }
  },
  {
    "id":"IYqwjwde124J",
    "campaignName":"campaignName",
    "templateName":"templateName",
    "passbookDevices":0,
    "androidPayDevices":0,
    "updatedAt":"2016-03-15T23:42:56.271326844Z",
    "createdAt":"2016-03-15T23:42:56.271325489Z",
    "dynamicData":{
      "name":"Hello",
      "number":123,
      "float":123.34215
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
      }
    },
    "userDefinedId":"E1234567",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":true,
    "isRedeemed":true,
    "isInvalid":false,
    "expiryDate":"2016-04-11T12:59:40Z",
    "passbookMeta":{
      "groupId":"airline-1",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000",
      "userInfo":{
          "key":"value"
      }
    }
  }
]

HTTP Request

PUT https://api-pass.passkit.net/v2/passesBatch?id=ABC,CDE

JSON parameters

Data type Description
passes an array of pass data When using the batch get passes method you can specify an array of data for up to 25 passes, containing the same data as found in retrieve a pass. Please note, each pass in the batch get passes call will also need to have their pass id added to the call.

Search

Example of a search initiation request:

Search s = new Search();
s.size = 10;
s.passFilter = new PassFilter();
s.passFilter.isRedeemed = new Operation();
s.passFilter.isRedeemed.eq = false;
SearchResult sr = new SearchResult();
sr = pk.search(s);
curl https://search.passkit.net/v1/passes
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Search input in JSON format:

{
  "size":2,
  "from":0,
  "passFilter":{
    "id":"passId123",
    "templateName":"templateName",
    "campaignName":"campaignName",
    "userDefinedId":"myPass123",
    "isRedeemed":false,
    "isInvalid":false,
    "isVoided":false,
    "expiryDate":{
      "gte":"2016-04-11T12:59:59Z"
    },
    "updatedAt":{
      "eq":"2015-04-11T13:00:00Z"
    },
    "createdAt":{
      "eq":"2015-04-11T13:00:00Z"
    },
    "firstUnregisterAt":{
      "exists":false
    },
    "lastUnregisterAt":{
      "exists":false
    },
    "firstRegisterAt":{
      "exists":false
    },
    "lastRegisterAt":{
      "exists":false
    },
    "lastRedeemAt":{
      "exists":false
    },
    "recoveryEmail":{
      "exists":false
    },
    "dynamicData":{
      "name":{
        "eq":"MrAwesome"
      },
      "point":{
        "lte":12
      },
      "balance":{
        "gt":900,
        "lt":1500
      }
    },
    "androidPayDevices":{
      "gte":5000,
      "lte":10000
    },
    "passbookDevices":{
      "gte":5000,
      "lte":10000
    }
  }
}

Search output in JSON format:

{
  "data":[
    {
      "androidPayDevices":0,
      "campaignName":"campaign",
      "createdAt":"2016-06-17T07:08:53.627020984Z",
      "dynamicBackfields":null,
      "dynamicData":{},
      "id":"8HcmhZ7xu6rmUQ",
      "isInvalid":false,
      "isRedeemed":false,
      "isVoided":false,
      "passbookDevices":0,
      "recoveryEmail":"test@passkit.com",
      "templateName":"Test_Run",
      "updatedAt":"2016-06-17T07:08:53.627022014Z"
    },
    {
      "androidPayDevices":0,
      "campaignName":"campaign2",
      "createdAt":"2016-06-27T08:35:33.820605955Z",
      "dynamicBackfields":null,
      "dynamicData":{},
      "id":"WA4CICRvomIM0X",
      "isInvalid":false,
      "isRedeemed":false,
      "isVoided":false,
      "passbookDevices":0,
      "recoveryEmail":"test@passkit.com",
      "templateName":"Test_Run2",
      "updatedAt":"2016-06-27T08:35:33.820605955Z"
    }
  ],
  "nextFrom": 3,
  "totalCount": 4
}

HTTP Request

POST https://search.passkit.net/v1/passes

Query

The attributes of the search are to be defined here

JSON parameters

Data Type Description
size integer The size of the search result
from integer The starting index of the search
passFilter pass filter The filter criteria of the search

JSON response

Data Type Description
data array of passes shows each pass and their related fields
nextFrom int allows the user to paginate for a certian number of values
totalCount int references the number of passes in the entire search

CSV Request

CSV input request for fields in JSON in format:

{
  "dynamicFields":["Email"],
  "standardFields":["id","isRedeemed"],
  "email":"johndoe@example.com",
  "customSubject": "CSV EMAIL"
}

CSV output in JSON format:

{
  "fileID": "6s8K5aSVtFKGpO8LChkgleaQllBIMq6n",
  "fileName": "2017_02_06_1633_6s8K5aSVtFKGpO8LChkgleaQllBIMq6n.zip",
  "password": "D0opQZwrjqZ8bZGy",
  "totalCount": 2
}

Error example input:

{
  "dynamicFields":[],
  "standardFields":[],
  "email":"jlangford@pga.com"
}

Error output

{
  "error": "Can not have both dynamicFields and 
            standardFields as empty arrays"
}

Error example input:

{
  "dynamicFields":["Email"],
  "standardFields":["incorrectName"],
  "email":"jlangford@pga.com"
}

Error output

{
  "error": "Your key/keys: (incorrectName) do not match our pre-defined key names"
}

We offer the ability to send a custom CSV file containing information on up to a million customers to a specified email. The CSV file will be held inside a password protected zipfile.

Note(s):

1) The CSV function only allows 1 million entries per file.

2) UTF-8 characters are supported by this function; however, certian programs may not fully support all characters available.

3) Processing time may vary based on number of passes and usage rate.

HTTP Request

POST https://search.passkit.net/v1/passes/csv

JSON parameters

Data Type Description
dynamicFields array of strings Refers to the dynamic data that the pass contains. This field is not case sensitive. See Operation for further details.
standardFields array of strings
standardFields
If you specify any number of fields here, they will be the only ones written to the CSV. If it is an empty array, none will be used. If you leave it blank, we will send you all fields.
email
(required)
string This is the email that you wish the CSV to be sent to.
passFilter PassFilter The filter criteria of the search.
customSubject string Custom email subject.

JSON response

Data Type Description
fileID string Refers to the ID of the file.
fileName string Refers to the name of the file. Contains the fileID.
password string Refers to the password needed to open the zipfile.
totalCount int Refers to the total number of entries in the csv.

Error handling

Below are the custom errors we have included when requesting a CSV file.

Description Status
Both dynamicFields and standardFields can not be empty arrays. 400
Values in standardFields must match our pre-defined list. All values can be found here 400
You have requested over a million pass records. 400

Standard Fields

Name Type
id string
campaingName string
templateName string
userDefinedId operation
passbookDevices operation
androidPayDevices operation
updatedAt operation
createdAt operation
firstUnregisterAt operation
lastUnregisterAt operation
lastRegisterAt operation
lastRedeemAt operation
firstRegisterUserAgent operation
lastRegisterUserAgent operation
expiryDate operation
isInvalid bool
isRedeemed bool
isVoided bool
recoveryEmail operation

Pass Filter

The specific search criteria of the search are to be defined here

Note(s):

1) To filter by date, follow YYYY-MM-DDTHH:MM:SSZ format. Also, note that defining the full date format is not requried. For example, date in YYYY-MM format is also a valid search filter.

JSON Parameters

Data Type Description
id string Refers to the auto-generated passId of the issued pass.
templateName string The template name that the pass was issued from. Please see Create Template.
campaignName string Refers to the campaign name the pass is associated with. Please see Create Campaign.
userDefinedId operation Refers to the passId given by the issuer of the issued pass
isRedeemed bool A true value shows that the pass has been redeemed, if redeem status is enabled in your template.
isInvalid bool A true value shows that the pass is invalidated. An invalidated pass will have the barcode, beacon, and location messages removed and the pass can no longer be communicated with.
isVoided bool A true value shows that the pass is voided.
expiryDate operation Refers to the expiry date of the pass. After the expiry date, the pass will automatically be voided (same effect of isVoided). This value will override the template and campaign end date value. See Operation for further details.
updatedAt operation Refers to the date and time the pass was last updated. See Operation for further details.
createdAt operation Refers to the date and time the pass was created. See Operation for further details.
firstUnregisterAt operation Refers to the first date and time the pass was unregistered at. See Operation for further details.
lastUnregisterAt operation Refers to the last date and time the pass was unregistered at. See Operation for further details.
firstRegisterAt operation Refers to the first date and time the pass was registered at. See Operation for further details.
lastRegisterAt operation Refers to the last date and time the pass was registered at. See Operation for further details.
lastRedeemAt operation Refers to the date and time the pass was redeemed at. See Operation for further details.
recoveryEmail operation Refers to the recovery email that was added when the pass was created. See Operation for further details.
dynamicData map-operation Refers to the dynamic data that the pass contains. See Operation for further details.
androidPayDevices operation Refers to the number of Android Pay devices that the pass is registered on. See Operation for further details.
passbookDevices operation Refers to the number of Apple devices that the pass is registered on. See Operation for further details.

Operation

The range of the search are to be defined here.

Note(s):

1) Either of “gt” or “gte” can be used to filter the search of an operation.

2) Either of “lt” or “lte” can be used to filter the search of an operation.

3) “eq” can only be used alone to define the search range for an operation.

4) “exists” can only be used alone to define the search range for an operation.

JSON parameters

Data Type Description
gt interface Returns search results that is greater than the stated value.
gte interface Returns search results that is greater than and equal to the stated value.
lt interface Returns search results that is smaller than the stated value.
lte interface Returns search results that is smaller than and equal to the stated value.
eq interface Returns search results that is equal to the stated value.
exists bool A true value will return search results that have a previously defined value.

Images

Upload an Image

Upload an Image

String path = null;
path = pk.uploadImage(new File(img.png));
#To create a template, image files are required, therefore this request must be sent via multipart form
curl https://api-pass.passkit.net/v2/images
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -F "image=@icon.png"

On success the api will respond with the Template Name in JSON format:

{
  "path": "images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png"
}

HTTP Request

POST https://api-pass.passkit.net/v2/images

Multipart Form Parameters

Creating a template requires image files to be uploaded at the same time, this request is sent as multipart form.

The parameters required are as follows

Parameter Type Description
image image file An image file. Only allow : .png, .jpg, .jpeg, .gif, .bmp. Maximum file size is 5MB.

Note: Please make the image as small as possible because big file size significantly slow down the pass download time.

JSON Response

Data type Description
path string A unique path to the image. It can be used as input parameter for anther API method.

Recovery Email

Resend or Update Recovery Email

This endpoint allows people to send a recovery email based on pass ID. In addition, it also allows to update pass’s recovery email and resend to the new email address at the same time. You can resend emails up to 10 items per request.

Example of a request

// Resend Single Recovery Email
RecoveryEmail re1 = new RecoveryEmail();
re1.passId = "idOfTargetPass";
re1.newRecoveryEmail = "apoorva@passkit.com";
RecoveryEmail resultRE1 = null;
resultRE1 = pk.resendRecoveryEmail(re1);

// Resend Multiple Recovery Email
RecoveryEmail[] re2 = new RecoveryEmail[2];
re2[0] = new RecoveryEmail();
re2[0].passId = "idOfTargetPass";
re2[0].newRecoveryEmail = "apoorva@passkit.com";
re2[1] = new RecoveryEmail();
re2[1].passId = "idOfTargetPass";
RecoveryEmail[] resultRE2 = null;
resultRE2 = pk.resendRecoveryEmail(re2);
curl "https://api-pass.passkit.net/v2/recoveryEmails/resend"
  -X "PUT" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

[
  {
    "passId":"6ddyveV8Ho5xV8",
    "newRecoveryEmail":"kit@passkit.com"
  },
  {
    "passId":"meNyAZnTnbCmWH"
  },
  {
    "passId":"4qgfeKDIuBINHh",
    "newRecoveryEmail":"hello@passkit.com"
  }
]

On success the api will respond with the Pass Id in JSON format:

[
  {
    "passId": "6ddyveV8Ho5xV8",
    "recoveryEmail": "kit@passkit.com",
    "success": true
  },
  {
    "passId": "meNyAZnTnbCmWH",
    "recoveryEmail": "kit@passkit.com",
    "success": true
  },
  {
    "passId":"4qgfeKDIuBINHh",
    "recoveryEmail":"hello@passkit.com",
    "success": true
  }
]

HTTP Request

PUT https://api-pass.passkit.net/v2/recoveryEmails/resend

JSON parameters

Data type Description
passId
(required)
string Pass ID need to resend recovery email.
newRecoveryEmail string If this value is specified, it will update current pass’s recovery email and resend a recovery email to the new email address.

General

Supported Languages

Language Code Language
ar (Arabic) العربية
ca Català (Catalan)
zh-Hans 简体中文 (Simplified Chinese)
zh-Hant 繁體中文 (Traditional Chinese)
hr Hrvatski (Croatian)
cs Čeština (Czech)
da Dansk (Danish)
nl Nederlands (Dutch)
en English
en-GB English (British)
fi Suomi (Finnish)
fr Français (French)
de Deutsch (German)
el Ελληνικά (Greek)
he (Hebrew) עברית
hu Magyar (Hungarian)
id Bahasa Indonesia (Indonesian)
it Italiano (Italian)
ja 日本語 (Japanese)
ko 한국어 (Korean)
ms Bahasa Melayu (Malay)
nb Norsk Bokmål (Norwegian)
pl Polski (Polish)
pt-BR Português (Brazilian Portuguese)
pt Português de Portugal (Portuguese)
ro Română (Romanian)
ru Русский (Russian)
sk Slovenčina (Slovakian)
es Español (Spanish)
sv Svenska (Swedish)
th ภาษาไทย (Thai)
tr Türkçe (Turkish)
uk Українська (Ukranian)
vi Tiếng Việt (Vietnamese)

Currency Codes

All the available currency codes (ISO 4217) are listed here:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, USS, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, XTS, XXX, YER, ZAR, ZMK, ZWL

Campaign Callbacks (Webhook)

When a callback object is defined in Campaign record. The following pass activites will trigger webhook and send a POST HTTP requset to the URL.

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
onDeregisterCallbackUrl - An event will fire when a pass is uninstalled the on the Phone (only available for iOS, Pass2U and mWallet App)

For the HTTP request, it contain a JWT in the HTTP header - Authorization so that you can use the following information to authenticate the request.

exp - Unix timestamp of expiry time
key - Your API key
iat - Unix timestamp of create time

The JWT will be signed by API secret. So, you can verify the JWT by your API key and secret.

Errors

This section details the different error responses

Error Code Meaning
400 Bad Request – Your request is incorrect
401 Unauthorized – Your API key, secret or both are wrong
403 Forbidden – You don’t have permission to perform that action.
404 Not Found – The specified request or data could not be found
500 Internal Server Error – We had a problem with our server. Please try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Change Log

Date Notes
13 Oct, 2016 Added disableWebServiceUrl in Apple Wallet model.
4 August, 2016 Added meta in template and campaign model to store meta data.
29 June, 2016 Updated Apple renew certificate endpoint and search API.
20 June, 2016 Added recovery email resend endpoint.
27 May, 2016 Added ERD, image upload, passbook backfield diagram.
26 May, 2016 Updated campagin, template, and pass input parameters.