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.