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
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/digitalpass/apple/templates1{
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
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
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/digitalpass/apple/templates1{
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
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
Compact Credential
Request
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact/digitalpass/google/templates1{
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
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
1POST https://YOUR_TENANT_URL/core/v2/credentials/compact-semantic/digitalpass/google/templates1{
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
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