Digital Pass Template Management

Introduction

This guide will step through how to manage a digital pass template, which is required to be used to generate a digital pass of the compact or semantic compact credentials. 

Prerequisites

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

  • Access to the MATTR VII APIs

  • A signed and encoded compact or semantic compact credential issued by your organization

  • Credentials associated with your organization’s Apple developer account or Google account.

  • An Apple pass template or Google wallet pass template named template.zip

If you’re experiencing any difficulties, contact us

Click here for a how-to-guide on digital pass template and design guidelines

Apple Pass

Set up an Apple Pass Template

The following are required to generate an Apple pass under your organization's Apple Developer Account:

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: Pass type identifier: 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 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, do the following:
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 

Compact Credential 

Request 
http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact/digitalpass/apple/templates
json
Copy to clipboard.
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": "xxxxx",
12    "passTypeIdentifier": "xxxxx",
13    "wwdr": "xxxxx",
14    "signerCert": "xxxxx",
15    "signerKey": "xxxxx",
16    "signerKeyPassphrase": "xxxxx",
17}
Response 
json
Copy to clipboard.
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}

Semantic Compact Credential 

Request 
http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact-semantic/digitalpass/apple/templates
json
Copy to clipboard.
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": "xxxxx",
12    "passTypeIdentifier": "xxxxx",
13    "wwdr": "xxxxx",
14    "signerCert": "xxxxx",
15    "signerKey": "xxxxx",
16    "signerKeyPassphrase": "xxxxx",
17}
Response 
json
Copy to clipboard.
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}

Update an Apple Pass Template

If you would like to change the issuer's information such as teamIdentifier, passTypeIdentifier, wwdr, signerCert, signerKey or signerKeyPassphrase, it is highly recommended to create a new template instead of updating an existing one. However, you can always replace the bundle file of an existing template.

Possible Errors

Errors may occur in the following scenarios:

  • unable to decompress the bundle

  • pass.json is missing from the bundle

  • pass.json is malformed

  • the required fields of pass.json such as name or file name are not defined

  • the file name contains a special character that is not supported by the Apple pass template endpoint. It only allows "-" and "_".

  • the bundle file exceeds the maximum size allowed

Google Wallet Pass

Set up a Google Wallet Pass Template

The following are required to generate a Google wallet pass in your organization's Google Pay & Wallet Console:

isserId: Google Wallet Pass signer issuer ID 

serviceAccountClientEmail: Email address of the Google Cloud Platform service account for accessing the Google Pay Passes API 

serviceAccountPrivateKey: Private key PEM of the Google Cloud Platform service account 

Click here to find out more about how to grant access to your service account to call the Google Wallet API.

Compact Credential 

Request 
http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact/digitalpass/google/templates
json
Copy to clipboard.
1{
2    "template": {
3      "value": fs.createReadStream("WorkingLoyaltyPass.zip"),
4      "options": {
5        "filename": "WorkingLoyaltyPass.zip",
6        "contentType": null
7      }
8    },
9    "name": "example",
10    "issuerId": "xxxxx",
11    "serviceAccountClientEmail": "xxxxx",
12    "serviceAccountPrivateKey": "xxxxx"
13}
Response 
json
Copy to clipboard.
1{
2    "id": "0793fade-bd27-46a8-8dfe-67c4d3e9cf09",
3    "name": "example",
4    "passType": "google",
5    "metadata": {
6        "issuerId": "xxxxx",
7        "serviceAccountClientEmail": "xxxxx",
8        "payPassId": "xxxxx"
9    }
10}

Semantic Compact Credential 

Request 
http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v2/credentials/compact-semantic/digitalpass/google/templates
json
Copy to clipboard.
1{
2    "template": {
3      "value": fs.createReadStream("WorkingLoyaltyPass.zip"),
4      "options": {
5        "filename": "WorkingLoyaltyPass.zip",
6        "contentType": null
7      }
8    },
9    "name": "example",
10    "issuerId": "xxxxx",
11    "serviceAccountClientEmail": "xxxxx",
12    "serviceAccountPrivateKey": "xxxxx"
13}
Response 
json
Copy to clipboard.
1{
2    "id": "0793fade-bd27-46a8-8dfe-67c4d3e9cf09",
3    "name": "example",
4    "passType": "google",
5    "metadata": {
6        "issuerId": "xxxxx",
7        "serviceAccountClientEmail": "xxxxx",
8        "payPassId": "xxxxx"
9    }
10}

Update a Google Wallet Pass Template

To avoid potential impact on the previous generated Google Wallet Passes, updating an existing template will always create a new template in Google Pay Business Console.

Possible Errors

Errors may occur in the following scenarios:

  • unable to decompress the bundle

  • template.json is missing from the bundle

  • template.json is malformed

  • the bundle file exceeds the maximum size allowed