How to create an Apple digital pass template

Prerequisites

• Credentials associated with your organisation's Apple developer account (opens in a new tab).

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 (opens in a new tab).

pass.json

The contents of pass.json are described in detail in Apple's developer documentation (opens in a new tab). 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 organisation 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 to false to disable the Share Pass option
• voided : Indicates that the pass is void. For example, a one time use coupon that has been redeemed. The default value is false.
• barcode :
  • format : Must be set to PKBarcodeFormatQR.
  • messageEncoding : Must be set to iso-8859-1.
• storeCard : This is the style key which corresponds with the pass's style. Can be either storeCard (as shown in the example above), generic, eventTicket, coupon or a boardingPass. Each style key has different components. Below is an example of a storeCard 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 or PKTransitTypeTrain.
  • 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 Compact 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 Compact Semantic Credential Apple digital pass template:

POST /v2/credentials/compact-semantic/digital-pass/apple/templates

Request keys

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 the templateId when formatting a Compact 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).