Lower-Level Keys

Keys that are used lower in the hierarchy of the pass.json file—for example, in a dictionary that is the value of a top-level key.

Pass Structure Dictionary Keys

Keys that define the structure of the pass.

These keys are used for all pass styles and partition the fields into the various parts of the pass.

Key name

Type

Description

auxiliaryFields

array of field dictionaries

Optional. Additional fields to be displayed on the front of the pass.

backFields

array of field dictionaries

Optional. Fields to be on the back of the pass.

headerFields

array of field dictionaries

Optional. 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 are displayed.

primaryFields

array of field dictionaries

Optional. Fields to be displayed prominently on the front of the pass.

secondaryFields

array of field dictionaries

Optional. Fields to be displayed on the front of the pass.

transitType

string

Required for boarding passes; otherwise not allowed. Type of transit. Must be one of the following values: PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric,PKTransitTypeTrain.

Beacon Dictionary Keys

Information about a location beacon.

Available in iOS 7.0.

Key name

Type

Description

major

16-bit unsigned integer

Optional. Major identifier of a Bluetooth Low Energy location beacon.

minor

16-bit unsigned integer

Optional. Minor identifier of a Bluetooth Low Energy location beacon.

proximityUUID

string

Required. Unique identifier of a Bluetooth Low Energy location beacon.

relevantText

string

Optional. Text displayed on the lock screen when the pass is currently relevant. For example, a description of the nearby location such as “Store nearby on 1st and Main.”

Location Dictionary Keys

Information about a location.

Key name

Type

Description

altitude

double

Optional. Altitude, in meters, of the location.

latitude

double

Required. Latitude, in degrees, of the location.

longitude

double

Required. Longitude, in degrees, of the location.

relevantText

string

Optional. Text displayed on the lock screen when the pass is currently relevant. For example, a description of the nearby location such as “Store nearby on 1st and Main.”

Barcode Dictionary Keys

Information about a pass’s barcode.

Key name

Type

Description

altText

string

Optional. Text displayed near the barcode. For example, a human-readable version of the barcode data in case the barcode doesn’t scan.

format

string

Required. Barcode format. For the barcode dictionary, you can use only the following values: PKBarcodeFormatQR, PKBarcodeFormatPDF417, or PKBarcodeFormatAztec. For dictionaries in the barcodes array, you may also use PKBarcodeFormatCode128.

message

string

Required. Message or payload to be displayed as a barcode.

messageEncoding

IANA character set name, as a string

Required. Text encoding that is used to convert the message from the string representation to a data representation to render the barcode. The value is typically iso-8859-1, but you may use another encoding that is supported by your barcode scanning infrastructure.

NFC Dictionary Keys

Information about the NFC payload passed to an Apple Pay terminal.

Key name

Type

Description

message

string

Required. The payload to be transmitted to the Apple Pay terminal. Must be 64 bytes or less. Messages longer than 64 bytes are truncated by the system.

encryptionPublicKey

string

Optional. The public encryption key used by the Value Added Services protocol. Use a Base64 encoded X.509 SubjectPublicKeyInfo structure containing a ECDH public key for group P256.