> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/command-centre-client/configuring-command-centre/configuring-licensable-features/universal-credential/json-file-configuration.md).

# JSON File Configuration

### Introduction

This topic describes how to configure a JSON file that defines a third-party Apple Wallet, Google Wallet, or physical credential format for use with the Universal Credential feature.

**Note:** Third-party wallet formats are owned by the credential provider and cannot be shared by Gallagher Security. A Gallagher Technology Partner obtains the credentials directly from the provider and assigns them to cardholders using REST APIs. The wallet provider can supply the required formats.

### Apple Wallet

To assist with configuration, Gallagher has provided an Apple Format JSONC Template File downloadable from this [location](https://help.security.gallagher.com/knowledge-hub/command-centre-client/configuring-command-centre/configuring-licensable-features/universal-credential/json-file-configuration/universal-credential-files.md). Download the file, populate it with your required values, then save as a JSON file.

<table><thead><tr><th width="214">Property</th><th width="169">Supported Values</th><th>Description</th></tr></thead><tbody><tr><td>providerName</td><td>alphanumeric</td><td>The provider’s name. Shown in the Provider list. Required. Max 110 characters.</td></tr><tr><td>subTechnology</td><td>walletApple</td><td>The technology associated with the format. Required.</td></tr><tr><td>cardNumberFormat</td><td>hex, decimal</td><td>The card number display format. Omit and Command Centre silently stores hex.</td></tr><tr><td>uidDiscovery.appId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the UID Discovery Application. Optional.</td></tr><tr><td>uidDiscovery.key.type</td><td>aes128, pkt2K3DES</td><td>The encryption algorithm used by the UID Discovery key.</td></tr><tr><td>uidDiscovery.key.number</td><td>0-13</td><td>The UID Discovery Key Number used for authentication.</td></tr><tr><td>read.cardDataAppId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the application that contains the card data file. 0x prefix optional. Cannot be 0x000000.</td></tr><tr><td>read.secureDataAppId</td><td>000000-FFFFFF</td><td>The Application ID (AID) of the application that contains the secure data used for second-factor authentication (2FA). Delete the line if unused - do not leave it as an empty string.</td></tr><tr><td>read.protectionLevel</td><td>enciphered, plain</td><td>The protection level used when reading data from the file. Typically, enciphered is used.</td></tr><tr><td>read.fileNumber</td><td>0-31</td><td>The file number within the application to read from. An application can contain up to 32 files.</td></tr><tr><td>read.credentialNumberOffsetBits</td><td>0-134,217,728 bits</td><td>The bit offset within the file where card number extraction begins. A start position of 0 indicates that reading begins at the first bit of the file.</td></tr><tr><td>read.credentialNumberLengthBits</td><td>1-400 bits</td><td>The length of the card number data to read from the file, specified in bits.</td></tr><tr><td>read.key.type</td><td>aes128, pkt2K3DES</td><td>The cryptography used to protect the key.</td></tr><tr><td>read.key.number</td><td>0-13</td><td>The key number from the application you want to use. Key 0 is always the application’s master key. Editable after Universal Credential Type creation.</td></tr><tr><td>read.key.diversification.cmacPadLength</td><td>standard16, standard32</td><td>The CMAC padding applied during key diversification, either standard16 or standard32. Delete the line for a non-diversified key. Defaults to standard32.</td></tr><tr><td>read.key.diversification.inputSequence</td><td>uid, aid, reversedAid, infoByte, timestamp</td><td>The diversification input to use. Typically, UID is used. Order matters: uid, aid, reversedAid, infoByte, timestamp. No repeats. Command Centre allows at most 4 and rejects aid and reversedAid together.</td></tr><tr><td>apple.tci</td><td>2-30 hex (1-15 bytes)</td><td>The Terminal Capabilities Identifier (TCI) advertised by the reader to display the correct badge in Apple Wallet. A TCI with length 0 is invalid. Editable after Universal Credential Type creation.</td></tr><tr><td>apple.vasUpFormat</td><td>0x02</td><td>The supported Apple Enhanced Contactless Polling (ECP) protocol version.<br>Default 0x02 which is ECP Specification v2.3</td></tr><tr><td>apple.terminalInfo</td><td>0x83, 0xC3</td><td>Indicates whether Apple Terminal Requested Authentication (TRA) is supported.<br>0x83=Supported, 0xC3=Not supported.<br>For credentials that support 2FA use the TRA mode value. For credentials that don’t support TRA use the Express mode value.</td></tr><tr><td>apple.terminalType</td><td>Any</td><td>The Apple Terminal Type. Typically, 0x02 is specified.</td></tr><tr><td>apple.terminalSubtype</td><td>0x00, 0x02</td><td>The Apple Terminal Subtype.<br>0x00 = University, 0x02 = Corporate.<br>Editable after Universal Credential Type creation.</td></tr></tbody></table>

### Google Wallet

To assist with configuration, Gallagher has provided a Google Format JSONC Template File downloadable from this [location](https://help.security.gallagher.com/knowledge-hub/command-centre-client/configuring-command-centre/configuring-licensable-features/universal-credential/json-file-configuration/universal-credential-files). Download the file, populate it with your required values, then save as a JSON file.

<table><thead><tr><th width="268">Property</th><th width="170">Supported Values</th><th>Description</th></tr></thead><tbody><tr><td>providerName</td><td>alphanumeric</td><td>The provider’s name shown in the Provider list. Required. Max 110 characters.</td></tr><tr><td>subTechnology</td><td>walletGoogleMifare2go</td><td>The technology associated with the format. Required.</td></tr><tr><td>cardNumberFormat</td><td>hex, decimal</td><td>The card number display format. Omit &#x26; Command Centre silently stores hex.</td></tr><tr><td>uidDiscovery.appId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the UID Discovery Application. Optional.</td></tr><tr><td>uidDiscovery.key.type</td><td>aes128, pkt2K3DES</td><td>The encryption algorithm used by the UID Discovery Key.</td></tr><tr><td>uidDiscovery.key.number</td><td>0-13</td><td>The UID Discovery Key Number used for authentication.</td></tr><tr><td>read.cardDataAppId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the application that contains the card data file. 0x prefix optional. Cannot be 0x000000.</td></tr><tr><td>read.protectionLevel</td><td>enciphered, plain</td><td>Protection level used when reading data from the file. Typically, enciphered is used.</td></tr><tr><td>read.fileNumber</td><td>0-31</td><td>The file number within the application to read from. An application can contain up to 32 files.</td></tr><tr><td>read.credentialNumberOffsetBits</td><td>0-134,217,720 bits</td><td>The bit offset within the file where card number extraction begins. A start position of 0 indicates that reading begins at the first bit of the file.</td></tr><tr><td>read.credentialNumberLengthBits</td><td>1-400 bits</td><td>The length of the card number data to read from the file, specified in bits.</td></tr><tr><td>read.key.type</td><td>aes128, pkt2K3DES</td><td>The cryptography used to protect the key.</td></tr><tr><td>read.key.number</td><td>0-13</td><td>The key number from the application you want to use. Key 0 is always the application’s master key.</td></tr><tr><td>read.key.diversification.cmacPadLength</td><td>standard16, standard32</td><td>The CMAC padding applied during key diversification, either standard16 or standard32. Delete the line for a non-diversified key. Defaults to standard32.</td></tr><tr><td>read.key.diversification.inputSequence</td><td>uid, aid, reversedAid, infoByte, timestamp</td><td>The diversification input to use. Typically, UID is used. Order matters: uid, aid, reversedAid, infoByte, timestamp. No repeats. Command Centre allows at most 4 and rejects aid and reversedAid together.</td></tr><tr><td>google.rid</td><td>10 hex (5 bytes)</td><td><p>The Registered Application Provider Identifier (RID) within the DFNAME. Required. Exactly 10 hexadecimal characters and not 0x0000000000.<br>The RID forms part of the unique DFNAME used during the ISO Select process, allowing the reader to activate the correct credential in Google Wallet.<br>The DFNAME consists of three fields:</p><ul><li>RID (5 bytes)</li><li>Provider Code (11 bytes)</li><li>Customer Code (4 bytes)<br>The combined DFNAME has a maximum length of 32 hexadecimal characters (16 bytes). Defining the RID, Provider Code, and Customer Code allows a simplifiled card number to be displayed in Command Centre. If not defined, the full DFNAME displays.</li></ul></td></tr><tr><td>google.providerCode</td><td>22 hex (11 bytes) shared with customerCode</td><td>The Provider Code within the DFNAME. Optional. Delete if unused.</td></tr><tr><td>google.customerCode</td><td>22 hex (11 bytes) shared with providerCode</td><td>The Customer Code within the DFNAME. Editable after Universal Credential Type creation.</td></tr><tr><td>google.runCommitCommand</td><td>true, false</td><td><p>Determines whether a Commit Transaction command is sent to complete the transaction sequence.</p><ul><li>True = Send the Commit Transaction command.</li><li>False = Do not send the command (default).<br>Do not set it to true unless required by your wallet provider.<br>As part of the Commit Transaction, the byte at offset 15 of File 2 is read from the application and then written back.<br>Only applies to MIFARE2Go profiles.<br>Omitted entirely when not set.</li></ul></td></tr></tbody></table>

### Physical

To assist with configuration, Gallagher has provided a Physical Format JSONC Template File downloadable from this [location](https://help.security.gallagher.com/knowledge-hub/command-centre-client/configuring-command-centre/configuring-licensable-features/universal-credential/json-file-configuration/universal-credential-files). Download the file, populate it with your required values, then save as a JSON file.

<table><thead><tr><th width="268">Property</th><th width="169">Supported Values</th><th>Description</th></tr></thead><tbody><tr><td>providerName</td><td>alphanumeric</td><td>The provider’s name shown in the Provider list. Required. Max 110 characters.</td></tr><tr><td>subTechnology</td><td>physical</td><td>The technology associated with the format. Required.</td></tr><tr><td>cardNumberFormat</td><td>hex, decimal</td><td>The card number display format. Omit and Command Centre rejects the JSON file.</td></tr><tr><td>siteCode</td><td>decimal</td><td>The site code value. Must fit within the siteCodeLengthBits. Editable after Universal Credential Type creation.</td></tr><tr><td>siteCodeFormat</td><td>hex, decimal</td><td>The site code display format. Editable after Universal Credential Type creation.</td></tr><tr><td>uidDiscovery.appId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the UID Discovery application. Optional.</td></tr><tr><td>uidDiscovery.key.type</td><td>aes128, pkt2K3DES</td><td>The encryption algorithm used by the UID Discovery key.</td></tr><tr><td>uidDiscovery.key.number</td><td>0-13</td><td>The UID Discovery Key Number used for authentication.</td></tr><tr><td>read.cardDataAppId</td><td>000001-FFFFFF</td><td>The Application ID (AID) of the application that contains the card data file. 0x prefix optional. Cannot be 0x000000.</td></tr><tr><td>read.protectionLevel</td><td>enciphered, plain</td><td>The protection level used when reading data from the file. Typically, enciphered is used. Select plain if the file is read without encryption or data protection.</td></tr><tr><td>read.fileNumber</td><td>0-31</td><td>The file number within the application to read from. An application can contain up to 32 files.</td></tr><tr><td>read.credentialNumberOffsetBits</td><td>0-134,217,720 bits</td><td>The bit offset within the file where card number extraction begins. A start position of 0 indicates that reading begins at the first bit of the file.</td></tr><tr><td>read.credentialNumberLengthBits</td><td>1-400 bits</td><td>The length of the card number data to read from the file, specified in bits.</td></tr><tr><td>read.siteCodeOffsetBits</td><td>0-134,217,720 bits</td><td>The bit offset within the file where site code extraction begins. A start position of 0 indicates that reading begins at the first bit of the file. Editable after Universal Credential Type creation.</td></tr><tr><td>read.siteCodeLengthBits</td><td>1-400 bits</td><td>The site code length to read from the file, specified in bits. Editable after Universal Credential Type creation.<br>The site code must not overlap the credential number length. Length zero means no site code, and the site code offset is then ignored.<br>The site code and card number length cannot exceed 400 bits but can have a much larger offset. For example:<br>Site code offset: 10,000<br>Site code length: 32<br>Card number offset: 10,032<br>Card number length: 64<br>Total:<br>Combined offset: 10,000<br>Combined length: 96</td></tr><tr><td>read.key.type</td><td>aes128, pkt2K3DES</td><td>The cryptography used to protect the key.</td></tr><tr><td>read.key.number</td><td>0-13</td><td>The key number from the application you want to use. Key 0 is always the application’s master key.</td></tr><tr><td>read.key.diversification.cmacPadLength</td><td>standard16, standard32</td><td>The CMAC padding applied during key diversification, either standard16 or standard32. Delete the line for a non-diversified key. Defaults to standard32.</td></tr><tr><td>read.key.diversification.inputSequence</td><td>uid, aid, reversedAid, infoByte, timestamp</td><td>The diversification input to use. Typically, UID is used. Order matters: uid, aid, reversedAid, infoByte, timestamp. No repeats. Command Centre allows at most 4 and rejects aid and reversedAid together.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.security.gallagher.com/knowledge-hub/command-centre-client/configuring-command-centre/configuring-licensable-features/universal-credential/json-file-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
