Updating Wallet Template

Suggest Edits

The next step is Partially updating an existing Wallet Template by adding new features (data) according to the pass style you selected, and sending on payload the wallet template object in JSON format. That is, you can edit a specified wallet template that was created previously. With this call, you can also add or remove fields from the wallet template. One of the special fields you can add are the images, fields, and barcodes, among others.

📘

NOTE

With this call, you do not need to provide a complete template object when updating a template.

The images help you to set the overall visual appearance and improve the layout, style, and notification of the pass in order to be more intuitive to the end user. There are eight types of images you can add to the wallet template according to the pass style you chose when creating the wallet template in the previous step :

📘

NOTE

Each image must be in .png format.

ImageDescription & SizeWallet Pass Compatible
logoIn iOS, the logo image is displayed in the top left corner of the pass, next to the logo text: 480 pixels wide x 150 pixels high.

In Android, is displayed in the top middle of the pass. The minimum size of the logo on the Google Pay pass is 660 pixels wide x 660 pixels high.		Boarding pass

Coupon

Event ticket

Store card

Generic pass
iconThe icon image is shown when a Push Notification is received from the Wallet Pass in the user’s lock screen: 87 pixels wide x 87 pixels high.Boarding pass

Coupon

Event ticket

Store card
stripThe strip image is displayed beneath the logo: 1125 pixels wide x 432 pixels high. Coupon

Event ticket

Store card

Generic pass
footerThe footer image is displayed near the barcode: 381 pixels wide x 20 pixels high.Boarding pass
backgroundThe background image is displayed behind the entire front side of the Wallet pass: 240 pixels wide x 293 pixels high.Event ticket
thumbnailThe thumbnail image displayed next to the fields on the front of the pass: 270 pixels wide x 270 pixels high.Event ticket

Generic pass
heroThe hero image is used only on google pay passes: 1032 pixels wide x 336 pixels high.
mainThe main image is used only on google pay passes: 1500 pixels wide x 1536 pixels high.

In summary, the following table shows the images supported by each wallet pass type:

Wallet Pass TypeSupported images
Boarding passlogo, icon, footer
Couponlogo, icon, strip
Event ticketlogo, icon, strip, background, thumbnail

If you specify a strip image, do not specify a background image or a thumbnail.
Store cardlogo, icon, strip
Generic passlogo, icon, thumbnail

There are four types of Barcodes to be used inside of Wallet Passes supported by the Wallet API you can add to the wallet template:

QR

Aztec

PDF-417

Code128

In order to create a wallet pass, you are able to add custom fields (unique) or general fields to the wallet template.

There are five types of fields you can add to the wallet template:

Field typeDescription
Primary fieldsThe primary fields contain the most important information and are shown prominently on the pass.
Secondary fieldsThe secondary fields are less important and less prominent.
Auxiliary fieldsAuxiliary fields are even less important than secondary fields.
Header fieldsThe header fields contain highly salient information, and they are the only field that is visible when the passes are stacked up in Wallet.
BackfieldsThe fields behind the pass are called backfields.

The field values can be unique or non-unique, depending on the pass style. For example, the Auxiliary field value is "email" and you want that the "email" value to be personalized for each pass that is generated, which means that the value will not be static for each pass to generate.

The pass style determines the maximum number of fields that can appear on the front of a pass:

  • Coupons, store cards, and generic passes with a square barcode can have a total of up to four secondary and auxiliary fields, combined.

  • Boarding passes can have up to two primary fields and up to five auxiliary fields.

Each field is defined by a dictionary, which gives it a value and label (which are displayed to the user), a unique key, and optional information about how its value should be formatted as shown in the next example.

The following wallet pass example will help you to understand the location of each image, field, barcode, and JSON format for each one according to the wallet pass type.

Store Card example:

The field values can be unique or generic, depending on the pass style. For example, the Secondary field (label) is "name" and you want that the "name" value to be personalized for each pass that is generated, which means that the value will not be static for each pass to generate.

From the stored card example mentioned above, the "fixed" parameter means if the field will be unique (false) or generic (true). That is, the SECONDARY fields → “Name” and “Last Name” will be false, because once the wallet pass is generated and created will be sent to different end-users, therefore the name and last name values will be different for each recipient.

If the field is generic like the SECONDARY field → “Discount” and the HEADER field → “Expires” will be true, because once the wallet pass is generated and created will be sent to different end-users, but the discount and expires values won't be changed for each recipient. That is, these values are static for each pass.
The pass style determines the maximum number of fields that can appear on the front of a pass:

A pass can have up to three header fields, a single primary field, up to four secondary fields, and up to four auxiliary fields.

Boarding passes can have up to two primary fields and up to five auxiliary fields.

Coupons, store cards, and generic passes with a square barcode can have a total of up to four secondary and auxiliary fields, combined.

To update the Wallet Template, the same structure is used as the creation of the wallet template where the relevant data is the identifier ( serial ).

HTTP Request: PATCH /wallet/templates/{serial}

Before updating the wallet template, you need to provide the unique identifier of the wallet template created.

Required ParameterDescription
serialUnique identifier of the Wallet Template.

In the following request body, we enter the parameters needed to create a simple store card according to the pass style selected when creating the wallet template as the example above.

📘

NOTE

For Unique values ("fixed": false) , do not enter the “value” parameter in the request body when creating or updating the wallet template, because the values will change depending on who the pass is addressed to.

{
  "images": [
    {
      "name": "logo",
      "fixed": true
    },
    {
      "name": "strip",
      "fixed": true
    },
    {
      "name": "icon",
      "fixed": true
    }
  ],
  "fields": [
    {
      "place": "HEADER",
      "label": "Expires",
      "fixed": true,
      "value": "04/25/2023"
    },
    {
      "place": "PRIMARY",
      "label": "2X1 Cappuccino",
      "fixed": true,
      "value": ""
    },
    {
      "place": "SECONDARY",
      "label": "Name",
      "fixed": false
    },
    {
      "place": "SECONDARY",
      "label": "Last Name",
      "fixed": false
    },
    {
      "place": "SECONDARY",
      "label": "Discount",
      "fixed": true,
      "value": "20%"
    }
  ],
  "visualInfo": {
      "labelColor": "#0608fa",
      "backgroundColor": "#e5cece",
      "foregroundColor": "#000000",
      "barcode": {
        "type": "QR",
        "content": "encoded message",
        "altText": "Scan QR code",
        "contentFixed": true,
        "altTextFixed": true
      }
   }
}

The parameters presented in the request body example when creating the Wallet Template of a store card are the following:

📘

NOTE

There are additional parameters that are not included in the example request body when creating the Wallet Template of a store card. These parameters will be included according to the pass style (event ticket, boarding pass, coupon, generic pass) the user desires to create.

Parameter Required Description
images No

Wallet Template images.
images.name Yes

Image type.

There are 8 types of images you can add to the wallet template according to the pass type chosen when creating the template:

  • "logo": In iOS, the logo image is displayed in the top left corner of the pass, next to the logo text: 480 pixels wide x 150 pixels high.

    In Android, is displayed in the top middle of the pass. The minimum size of the logo on the Google Pay pass is 660 pixels wide x 660 pixels high.

  • "icon": The icon image is shown when a Push Notification is received from the Wallet Pass in the user’s lock screen: 87 pixels wide x 87 pixels high.

  • "strip": The strip image is displayed beneath the logo: 1125 pixels wide x 432 pixels high.

  • "footer": The footer image is displayed near the barcode: 381 pixels wide x 20 pixels high.

  • "background": The background image is displayed behind the entire front side of the Wallet pass: 240 pixels wide x 293 pixels high.

  • "thumbnail": The thumbnail image displayed next to the fields on the front of the pass: 270 pixels wide x 270 pixels high.

  • "hero": The hero image is used only on google pay passes: 1032 pixels wide x 336 pixels high.

  • "main": The main image is used only on google pay passes: 1500 pixels wide x 1536 pixels high.

NOTE: Each imagen must be in .png format.

For more information to know what type of images you need to add to the wallet template according to the pass type, go to the Updating Wallet Template section.
images.fixed Yes

Defines if the image is unique or generic (fixed) for all recipients.

true: The image is generic for all recipients. That is, the image is static for each pass to generate.

false: The image is unique for each recipient. That is, the image is custom for each pass to generate.
fields No

Wallet Template text fields.
fields.place Yes

Field type.

There are 4 types of fields you can add to the wallet template according to the pass type chosen when creating the template:

  • PRIMARY: The primary fields contain the most important information and are shown prominently on the pass.

  • SECONDARY: The secondary fields are less important and less prominent.

  • AUXILIARY: The auxiliary fields are even less important than secondary fields.

  • HEADER: The header fields contain highly salient information, and they are the only field that is visible when the passes are stacked up in Wallet.

fields.label Yes

Field text of the wallet template.
fields.fixed Yes

Defines if the field text is unique or generic (fixed) for all recipients.

true: The field text is generic for all recipients. That is, the field text is static for each pass to generate.

false: The field text is unique for each recipient. That is, the field text is custom for each pass to generate.
fields.value No

Value of the field text.

If the "fixed" parameter is true, you need to specify the field value.

If the "fixed" parameter is false, you don't need to specify the field value.
visualInfo No

Visual style attributes of the wallet template.
visualInfo.labelColor No

Set the field text color in hexadecimal (#RRGGBB) format.
visualInfo.backgroundColor No

Set the background color of the wallet pass in hexadecimal (#RRGGBB) format.
visualInfo.foregroundColor No

Set the field value text color in hexadecimal (#RRGGBB) format.
visualInfo.barcode No

Wallet Template barcode information.
visualInfo.barcode.type Yes

Barcode type.

Choose one of the following 4 types of barcodes you can add to the wallet template: "QR", "Aztec", "PDF-417", "Code128".
visualInfo.barcode.content No

String encoded in the barcode.
visualInfo.barcode.altText No

Text displayed below the barcode.
visualInfo.barcode.contentFixed Yes

Defines if the barcode content is unique or generic (fixed) for all recipients.

true: The barcode content is generic for all recipients. That is, the barcode content is static for each pass to generate.

false: The barcode content is unique for each recipient. That is, the barcode content is custom for each pass to generate.
visualInfo.barcode.altTextFixed Yes

Defines if the text displayed below the barcode (Alt Text) is unique or generic (fixed) for all recipients.

true: The text displayed below the barcode is generic for all recipients. That is, the Alt Text is static for each pass to generate.

false: The text displayed below the barcode is unique for each recipient. That is, the Alt Text is custom for each pass to generate.
relevanceInfo No

Relevance attributes of the wallet pass.

Mobile devices may display pass on the lockscreen or notify users based on this.
relevanceInfo.relevantDate No

Wallet Pass relevant date and time. It must be in ISO8601 format.
relevanceInfo.expirationDate No

Wallet Pass expiration date and time. It must be in ISO8601 format.
relevanceInfo.maxDistance No

Max distance in meters from any location where the pass is Relevant.
relevanceInfo.voided Yes

Set this flag to true to produce voided or expired wallet pass (same effect as expiration date).

Useful for single-use coupons/cards.

By default is false.
relevanceInfo.locations No

List (array) of locations where the wallet pass is relevant.
relevanceInfo.locations.altitude No

Set the altitude in meters.
relevanceInfo.locations.latitude No

Set the latitude in degrees.
relevanceInfo.locations.longitude No

Set the longitude in degrees.
relevanceInfo.locations.relevantText No

Text to display in the location.
relevanceInfo.beacons No

List (array) of IBeacons near where the wallet pass is Relevant.

The UUID, major and minor values provide the identifying information for the iBeacon.
relevanceInfo.beacons.uuid Yes

The UUID is a standard identifying system which allows a 'unique' number to be generated for a device.

The purpose of the ID is to distinguish iBeacons in your network, from all other beacons in networks outside your control. When you receive your beacons, they will all have a common proximity UUID set, which will look something like: f7826da6-4fa2-4e98-8024-bc5b71e0893e

Application developers should define a UUID specific to their app and deployment use case.

Size: 16 bytes
relevanceInfo.beacons.major No

Specifies a specific iBeacon and use case. For example, this could define a sub-region within a larger region defined by the UUID. That is, Major values are intended to identify and distinguish a group—for example all beacons on a certain floor or room in your venue could be assigned a unique Major value.

Size: 2 bytes.

By default, if you don't set the major value, it will be 0.
relevanceInfo.beacons.minor No

Allows further subdivision of region or use case, specified by the application developer. That is, Minor values are intended to identify and distinguish an individual—for example distinguishing specific beacons within a group of beacons assigned a Major value.

Size: 2 bytes.

By default, if you don't set the major value, it will be 0.
relevanceInfo.beacons.text No

Text to display nearby a beacon.
relevanceInfo.beacons.fixed Yes

Defines if the beacon is unique or generic (fixed) for all recipients.

true: The beacon is generic for all recipients. That is, the beacon is static for each pass to generate.

false: The beacon is unique for each recipient. That is, the beacon is custom for each pass to generate.
relevanceInfo.nfc No

NFC data to enable sending data from passes on payment transactions.

NFC stands for "Near Field Communication". NFC is a technology that allows the secure transfer of data between two nearby devices. On mobile phones, this technology is predominately used to facilitate contactless payments, as well as confirming identity for loyalty card usage or point redemption.
relevanceInfo.nfc.message Yes

Data to transmit to payment terminals. Max 64 bytes.
relevanceInfo.nfc.message.publicKey No

Optional public encryption key.
appKeys No

Associated and Custom companion app information for wallet pass.
appKeys.appLaunchURL No

A URL to be passed to the associated app when launching it.

The app receives this URL in the application:didFinishLaunchingWithOptions: and application:openURL:options: methods of its app delegate.

If this key is present, the associatedStoreIdentifiers key must also be present.
appKeys.storeIds No

List (array) of numeric Apple App Store Ids.

Only one item in the list is used—the first item identifier for an app compatible with the current device. If the app is not installed, the link opens the App Store and shows the app. If the app is already installed, the link launches the app.
appKeys.userInfo No

Custom user info for companion apps. Any JSON data can be stored.

When you create the Wallet Template of a store card, the response body contains the following data:

{
  "meta": {
    "timestamp": 1663695135248,
    "transactionId": "930617db-da5c-4d09-9f74-01465734b19a"
  },
  "data": {
    "serial": "6329f8c5b258215f37f17327",
    "passTypeId": "pass.com.ironbank.production",
    "name": "test Template doc",
    "type": "storecard",
    "description": "A wallet pass storecard example",
    "organization": "My Organization Name",
    "googlePayCompatible": false,
    "creationDate": "2022-09-20T17:30:45.922840834",
    "lastUpdated": "2022-09-20T17:32:15.241162348",
    "fields": [
      {
        "place": "HEADER",
        "label": "Expires",
        "fixed": true,
        "value": "04/25/2023"
      },
      {
        "place": "PRIMARY",
        "label": "2X1 Cappuccino",
        "fixed": true,
        "value": ""
      },
      {
        "place": "SECONDARY",
        "label": "Name",
        "fixed": false,
        "value": null
      },
      {
        "place": "SECONDARY",
        "label": "Last Name",
        "fixed": false,
        "value": null
      },
      {
        "place": "SECONDARY",
        "label": "Discount",
        "fixed": true,
        "value": "20%"
      }
    ],
    "images": [
      {
        "name": "logo",
        "fixed": true
      },
      {
        "name": "strip",
        "fixed": true
      },
      {
        "name": "icon",
        "fixed": true
      }
    ],
    "visualInfo": {
      "labelColor": null,
      "backgroundColor": null,
      "foregroundColor": null,
      "transitType": null,
      "logoText": null,
      "logoTextFixed": null,
      "barcode": {
        "type": "QR",
        "content": "encoded message",
        "altText": "Scan QR code",
        "contentFixed": true,
        "altTextFixed": true
      }
    },
    "createdBy": "[email protected]"
  }
}

The parameters presented in the response body example when creating the Wallet Template of a store card are the following:

📘

NOTE

There are additional parameters that are not included in the example response body when creating the Wallet Template of a store card. These parameters will be included according to the pass style (event ticket, boarding pass, coupon, generic pass) the user desires to create.

Parameter Description
data

Data contained once the Wallet Template has been created or updated.
data.serial

Unique identifier of the wallet template.
data.passTypeId

Unique identifier of the pass type template.

Used to distinguish pass types.
data.name

Wallet Template name.
data.type

Wallet Template pass type.

  • storecard: store card is used to record the credit points granted by stores or commercial organizations.

  • event: creation of bulk event tickets. It does not matter whether these are entertainment, cultural or sporting events.

  • boarding: digital document provided by transit organizations to board the airplane, train or bus.

  • coupon: digital ticket that can be redeemed for a financial discount or rebate when purchasing a product.

  • generic: personalize your own pass by adding fields and images to the wallet template.
data.description

A brief description of your wallet passes’s intent.
data.organization

Identifies your brand inside the wallet pass.
data.googlePayCompatible

Defines if this wallet template pass type also generates GooglePay passes.

true: the wallet template pass will be compatible with GooglePay (android).

false: the wallet template pass won't be compatible with GooglePay (android).
data.creationDate

Date when the wallet template has been created.
data.lastUpdated

Date when the wallet template has been updated.
data.images Optional. Wallet Template images.
data.images.name

Required. Image type.

There are 8 types of images you can add to the wallet template according to the pass type chosen when creating the template:

  • "logo": In iOS, the logo image is displayed in the top left corner of the pass, next to the logo text: 480 pixels wide x 150 pixels high.

    In Android, is displayed in the top middle of the pass. The minimum size of the logo on the Google Pay pass is 660 pixels wide x 660 pixels high.

  • "icon": The icon image is shown when a Push Notification is received from the Wallet Pass in the user’s lock screen: 87 pixels wide x 87 pixels high.

  • "strip": The strip image is displayed beneath the logo: 1125 pixels wide x 432 pixels high.

  • "footer": The footer image is displayed near the barcode: 381 pixels wide x 20 pixels high.

  • "background": The background image is displayed behind the entire front side of the Wallet pass: 240 pixels wide x 293 pixels high.

  • "thumbnail": The thumbnail image displayed next to the fields on the front of the pass: 270 pixels wide x 270 pixels high.

  • "hero": The hero image is used only on google pay passes: 1032 pixels wide x 336 pixels high.

  • "main": The main image is used only on google pay passes: 1500 pixels wide x 1536 pixels high.

NOTE: Each imagen must be in .png format.

For more information to know what type of images you need to add to the wallet template according to the pass type, go to the Updating Wallet Template section.
data.images.fixed

Required. Defines if the image is unique or generic (fixed) for all recipients.

true: The image is generic for all recipients. That is, the image is static for each pass to generate.

false: The image is unique for each recipient. That is, the image is custom for each pass to generate.
data.fields

Optional. Wallet Template text fields.
data.fields.place

Required. Field type.

There are 4 types of fields you can add to the wallet template according to the pass type chosen when creating the template:

  • PRIMARY: The primary fields contain the most important information and are shown prominently on the pass.

  • SECONDARY: The secondary fields are less important and less prominent.

  • AUXILIARY: The auxiliary fields are even less important than secondary fields.

  • HEADER: The header fields contain highly salient information, and they are the only field that is visible when the passes are stacked up in Wallet.

data.fields.label

Required. Field text of the wallet template.
data.fields.fixed

Required. Defines if the field text is unique or generic (fixed) for all recipients.

true: The field text is generic for all recipients. That is, the field text is static for each pass to generate.

false: The field text is unique for each recipient. That is, the field text is custom for each pass to generate.
data.fields.value

Optional. Value of the field text.

If the "fixed" parameter is true, you need to specify the field value.

If the "fixed" parameter is false, you don't need to specify the field value.
data.visualInfo

Optional. Visual style attributes of the wallet template.
data.visualInfo.labelColor

Optional. Set the field text color in hexadecimal (#RRGGBB) format.
data.visualInfo.backgroundColor

Optional. Set the background color of the wallet pass in hexadecimal (#RRGGBB) format.
data.visualInfo.foregroundColor

Optional. Set the field value text color in hexadecimal (#RRGGBB) format.
data.visualInfo.barcode

Optional. Wallet Template barcode information.
data.visualInfo.barcode.type

Required. Barcode type.

Choose one of the following 4 types of barcodes you can add to the wallet template: "QR", "Aztec", "PDF-417", "Code128".
data.visualInfo.barcode.content

Optional. String encoded in the barcode.
data.visualInfo.barcode.altText

Optional. Text displayed below the barcode.
data.visualInfo.barcode.contentFixed

Required. Defines if the barcode content is unique or generic (fixed) for all recipients.

true: The barcode content is generic for all recipients. That is, the barcode content is static for each pass to generate.

false: The barcode content is unique for each recipient. That is, the barcode content is custom for each pass to generate.
data.visualInfo.barcode.altTextFixed

Required. Defines if the text displayed below the barcode (Alt Text) is unique or generic (fixed) for all recipients.

true: The text displayed below the barcode is generic for all recipients. That is, the Alt Text is static for each pass to generate.

false: The text displayed below the barcode is unique for each recipient. That is, the Alt Text is custom for each pass to generate.
data.relevanceInfo

Optional. Relevance attributes of the wallet pass.

Mobile devices may display pass on the lockscreen or notify users based on this.
data.relevanceInfo.relevantDate

Optional. Wallet Pass relevant date and time. It must be in ISO8601 format.
data.relevanceInfo.expirationDate

Optional. Wallet Pass expiration date and time. It must be in ISO8601 format.
data.relevanceInfo.maxDistance

Optional. Max distance in meters from any location where the pass is Relevant.
data.relevanceInfo.voided

Required. Set this flag to true to produce voided or expired wallet pass (same effect as expiration date).

Useful for single-use coupons/cards.

By default is false.
data.relevanceInfo.locations

Optional. List (array) of locations where the wallet pass is relevant.
data.relevanceInfo.locations.altitude

Optional. Set the altitude in meters.
data.relevanceInfo.locations.latitude

Optional. Set the latitude in degrees.
data.relevanceInfo.locations.longitude

Optional. Set the longitude in degrees.
data.relevanceInfo.locations.relevantText

Optional. Text to display in the location.
data.relevanceInfo.beacons

Optional. List (array) of IBeacons near where the wallet pass is Relevant.

The UUID, major and minor values provide the identifying information for the iBeacon.
data.relevanceInfo.beacons.uuid

Required. The UUID is a standard identifying system which allows a 'unique' number to be generated for a device.

The purpose of the ID is to distinguish iBeacons in your network, from all other beacons in networks outside your control. When you receive your beacons, they will all have a common proximity UUID set, which will look something like: f7826da6-4fa2-4e98-8024-bc5b71e0893e

Application developers should define a UUID specific to their app and deployment use case.

Size: 16 bytes
data.relevanceInfo.beacons.major

Optional. Specifies a specific iBeacon and use case. For example, this could define a sub-region within a larger region defined by the UUID. That is, Major values are intended to identify and distinguish a group—for example all beacons on a certain floor or room in your venue could be assigned a unique Major value.

Size: 2 bytes.

By default, if you don't set the major value, it will be 0.
data.relevanceInfo.beacons.minor

Optional. Allows further subdivision of region or use case, specified by the application developer. That is, Minor values are intended to identify and distinguish an individual—for example distinguishing specific beacons within a group of beacons assigned a Major value.

Size: 2 bytes.

By default, if you don't set the major value, it will be 0.
data.relevanceInfo.beacons.text

Optional. Text to display nearby a beacon.
data.relevanceInfo.beacons.fixed

Required. Defines if the beacon is unique or generic (fixed) for all recipients.

true: The beacon is generic for all recipients. That is, the beacon is static for each pass to generate.

false: The beacon is unique for each recipient. That is, the beacon is custom for each pass to generate.
data.relevanceInfo.nfc

Optional. NFC data to enable sending data from passes on payment transactions.

NFC stands for "Near Field Communication". NFC is a technology that allows the secure transfer of data between two nearby devices. On mobile phones, this technology is predominately used to facilitate contactless payments, as well as confirming identity for loyalty card usage or point redemption.
data.relevanceInfo.nfc.message

Optional. Data to transmit to payment terminals. Max 64 bytes.
data.relevanceInfo.nfc.message.publicKey

Optional. Optional public encryption key.
data.appKeys

Optional. Associated and Custom companion app information for wallet pass.
data.appKeys.appLaunchURL

Optional. A URL to be passed to the associated app when launching it.

The app receives this URL in the application:didFinishLaunchingWithOptions: and application:openURL:options: methods of its app delegate.

If this key is present, the associatedStoreIdentifiers key must also be present.
data.appKeys.storeIds

Optional. List (array) of numeric Apple App Store Ids.

Only one item in the list is used—the first item identifier for an app compatible with the current device. If the app is not installed, the link opens the App Store and shows the app. If the app is already installed, the link launches the app.
data.appKeys.userInfo

Optional. Custom user info for companion apps. Any JSON data can be stored.
data.createdBy

User who created the wallet template.

Updated 8 months ago