How to create an Apple digital pass template
An Apple digital pass template is required to format a CWT or Semantic CWT credential as an Apple digital pass.
Overview
Creating an Apple digital pass template comprises the following steps:
Prerequisites
- Credentials associated with your organization’s Apple developer account .
Sample templates: You can download the following sample templates to better understand how to structure your own templates as you follow along this guide:
- CWT credential sample Apple digital pass template .
- Semantic CWT credential sample Apple digital pass template .
Design a template
Bundle the following digital pass assets into a .zip
file:
pass.json
: This required file contains pass information and identifiers.footer.png
: Displayed on the front of the pass near the barcode. Only available on boarding passes.icon.png
: Displayed in notifications and in emails that have a pass attached, and on the lock screen. When it is displayed, the icon gets a shine effect and rounded corners.thumbnail.png
: Displayed on the front of the pass. Only available on generic passes. For example, on a membership card, the thumbnail could be used for a cardholder picture.logo.png
: Displayed on the top-left corner of the front of the pass.strip.png
: Displayed behind the primary fields on the front of the pass. Only available on store cards, event tickets and coupons.The template.zip
file cannot be larger than 1mb.Different sized images (e.g. @2x, @3x) can be included in the bundle.
Read more about the visual layout of Apple digital passes and suggested design guidelines .
pass.json
The contents of pass.json
are described in detail in
Apple’s developer documentation . The
following is an example pass.json
file:
{
"formatVersion": 1,
"organizationName": "Advanced Safety Training",
"description": "HS.278 Working at Heights Certification",
"labelColor": "rgb(45, 45, 45)",
"foregroundColor": "rgb(45, 45, 45)",
"backgroundColor": "rgb(202, 202, 202)",
"sharingProhibited": true,
"voided": false,
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "iso-8859-1",
"message": "{{encoded}}",
"altText": "Exp: {{ date decoded.expiry 'dd MMM yyyy' }}"
},
"storeCard": {
"headerFields": [
{
"key": "codeHeader",
"label": "Certification",
"value": "{{ decoded.code }}"
}
],
"primaryFields": [],
"secondaryFields": [
{
"key": "nameSecondary",
"label": "Name",
"value": "{{ decoded.name }}"
},
{
"key": "certificationLevelSecondary",
"label": "Certified for",
"value": "{{ decoded.certificationLevel }}"
}
],
"auxiliaryFields": [],
"backFields": [
{
"key": "nameBack",
"label": "Name",
"value": "{{ decoded.name }}"
},
{
"key": "certificationNameBack",
"label": "Certification",
"value": "{{ decoded.certificationName }}"
}
]
}
}
formatVersion
(required): File format version. The value must be 1.organizationName
(required): Name of the organization that created and signed the pass.description
(required): Pass description, used by iOS accessibility technologies.labelColor
(optional): Label text color, specified as a CSS-style RGB triple. When omitted, label color is automatically determined.foregroundColor
(optional): Foreground pass color, specified as a CSS-style RGB triple. When omitted, label color is automatically determined.sharingProhibited
: Set tofalse
to disable the Share Pass optionvoided
: Indicates that the pass is void. For example, a one time use coupon that has been redeemed. The default value isfalse
.barcode
:format
: Must be set toPKBarcodeFormatQR
.messageEncoding
: Must be set toiso-8859-1
.
storeCard
: This is the style key which corresponds with the pass’s style. Can be eitherstoreCard
(as shown in the example above),generic
,eventTicket
,coupon
or aboardingPass
. Each style key has different components. Below is an example of astoreCard
pass structure:headerFields
: Fields to be displayed in the header on the front of the pass. Use header fields sparingly; unlike all other fields, they remain visible when a stack of passes is displayed.primaryFields
: Fields to be displayed prominently on the front of the pass.secondaryFields
: Fields to be displayed on the front of the pass.auxiliaryFields
: Additional fields to be displayed on the front of the pass.backFields
: Fields to be on the back of the pass.transitType
: this is required for boarding passes and not allowed otherwise. Must be one of the following:PKTransitTypeAir
,PKTransitTypeBoat
,PKTransitTypeBus
,PKTransitTypeGeneric
orPKTransitTypeTrain
.- Each field must contain a set of standard field dictionary keys:
key
: the key must be unique within the scope of the entire pass.label
: label text for the field.value
: the value of the field.
Create a MATTR VII template
Request
Make a multipart/form-data
request with the template .zip
file included as a binary file to
create a CWT credential Apple digital pass template:
POST /v2/credentials/compact/digital-pass/apple/templates
You can make a similar request to a different endpoint to create a Semantic CWT credential Apple digital pass template:
POST /v2/credentials/compact-semantic/digital-pass/apple/templates
Request keys
Key | Type | Description |
---|---|---|
template | File | Attach your template.zip file. |
name | Text | Insert a name to identify this Apple digital pass template. |
fileName | Text | Insert the file name that will be assigned to Apple digital passes created from this template. |
teamIdentifier | Text | The Team ID for the Apple Developer Program account that registered the pass type identifier. |
passTypeIdentifier | Text | The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass. |
wwdr | Text | Apple G1 or G4 worldwide developer relations intermediate certificate. |
signerCert | Text | Apple pass signer certificate . |
signerKey | Text | The encrypted key of the Apple pass signer certificate. |
signerPassphrase | Text | Passphrase for the encrypted key. |
Response
{
"id": "1b04f0ee-8e3e-4153-a0e0-8603a10e7f0a",
"name": "example",
"passType": "apple",
"metadata": {
"fileName": "example.pkpass",
"teamIdentifier": "xxxxx",
"passTypeIdentifier": "xxxxx"
}
}
id
: This is a unique identifier for this Apple digital pass template. You will use it as thetemplateId
when formatting a CWT credential as an Apple digital pass.- All other fields in the response include information retrieved from your Apple digital pass template.
Troubleshooting
Errors may occur in the following scenarios:
- Unable to decompress the template
.zip
file. pass.json
is missing from the bundle or it is malformed.- Required fields in
pass.json
are not available. - The file name contains a special character that is not supported by the Apple pass template endpoint.
- The bundle file exceeds the maximum size allowed (1mb).
If you ever need to update any issuer information such as teamIdentifier
, passTypeIdentifier
,
wwdr
, signerCert
, signerKey
or signerKeyPassphrase
, it is highly recommended to create a new
template. However, you can also
update an existing template.