Create an Apple digital pass template

This guide will show you how to create an Apple digital pass template, which is required to format a Compact or Compact Semantic Credential as an Apple digital pass.

Prerequisites

You need the following in order to proceed with this tutorial:

• Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

• Design an Apple pass template and save it as a template.zip bundle file:

  • Download a Compact Credential sample Apple digital pass template. 

  • Download a Compact Semantic Credential sample Apple digital pass template. 

• Credentials associated with your organisation's Apple developer account.

Request

Make the following request to create an Apple digital pass template:

1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/digitalpass/apple/templates

You can make a similar request to a different endpoint to create a Compact Semantic Credential Apple pass template:

1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/digitalpass/apple/templates

Request body

1{
2    "template": {
3        "value": fs.createReadStream("pass.zip"),
4        "options": {
5            "filename": "WorkingStoreCard.pass.zip",
6            "contentType": null
7        }
8    },
9    "name": "example",
10    "fileName": "example.pkpass",
11    "teamIdentifier": "xxx",
12    "passTypeIdentifier": "xxx",
13    "wwdr": "xxx",
14    "signerCert": "xxx",
15    "signerKey": "xxx",
16    "signerKeyPassphrase": "xxx",
17}

• template: Include your template files.

• name: Insert a name to identify this Apple digital pass template.

• fileName: Insert the file name that will be assigned to Apple digital passes created from this template.

• teamIdentifier: The Team ID for the Apple Developer Program account that registered the pass type identifier.

To find your Team ID, do the following:
1. Open Keychain Access, and select your certificate.
2. Select File > Get Info, and find the Organizational Unit section under Details. This is your Team ID.

You can also find your Team ID by looking at your organization profile in Member Center.

• passTypeIdentifier: The pass type identifier that’s registered with Apple. The value must be the same as the distribution certificate used to sign the pass. 

Every pass has a pass type identifier associated with a developer account. Pass type identifiers are managed in the Member Center by a team admin. To build this pass, request and configure a pass type identifier. (You can’t use the pass type identifier that is already in the pass because it isn’t associated with your developer account)

To register a pass type identifier:
1. In Certificates, Identifiers & Profiles select Identifiers.
2. Under Identifiers, select Pass Type IDs.
3. Click the plus (+) button.
4. Enter the description and pass type identifier, and click Submit.

• wwdr: Apple G1 or G4 worldwide developer relations intermediate certificate.

• signerCert: Apple pass signer certificate.

• signerKey: The encrypted key of the Apple pass signer certificate 

• signerPassphrase: Passphrase for the encrypted key 

Response

1{
2    "id": "1b04f0ee-8e3e-4153-a0e0-8603a10e7f0a",
3    "name": "example",
4    "passType": "apple",
5    "metadata": {
6        "fileName": "example.pkpass",
7        "teamIdentifier": "xxxxx",
8        "passTypeIdentifier": "xxxxx"
9    }
10}

• 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.

Errors may occur in the following scenarios:

• Unable to decompress the bundle.

• pass.json is missing from the bundle 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.

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.