Mobile Wallet

Suggest Edits

Mobile Wallet Passes are items with content or information stored in the Apple Wallet or Google Pay (formerly Android Pay / Google Wallet) native Applications. They are the equivalent of things stored in a physical wallet, such as loyalty cards, coupons, business cards, tickets, credit cards and more. Wallet Passes are very effective and efficient for businesses because they can be easily created, managed and updated, allowing a business to significantly reduce the cost of printing traditional physical cards.Passes can be thought of as another means of engagement and communication that can be sent to your audience.

The Wallet API provides functions to create, read, update, delete passes. Additionally there are functions to get a list of pass-templates and existing passes. Creating and updating wallet templates is currently supported via the API.

Apple and Google took different approaches at architecting their mobile wallet solutions even though what users experience is pretty much the same. For instance, Apple passes are pkpass files that must be bundled and hosted by issuers whereas Google takes care of that but only behind a cumbersome web interface.

The steps to create and download a wallet pass are the following:

  • Create the wallet pass template
  • Create a wallet pass
  • Download the wallet pass

Creating Wallet Template

Create a Wallet Template and send on payload the wallet template object in JSON format.

Stores a Wallet template in the server using JSON object data.

You can specify the layout of the pass you want to create by adding functions you require such as accumulating points, personalizing the pass depending on the user, generating dynamic QR codes for the particular order, add different types of images, among others.

The Wallet API allows you to specify five pass styles:

  • Store card: The digital store card is used to record the credit points granted by stores or commercial organizations. These points can then be redeemed on future purchases for rewards, like discounts on purchases or free gifts. Not only that, but customers can also accumulate points to redeem for bigger rewards. That can incentivize your customers to make several purchases in a row, in order to get the fancier reward - and that means they're coming to you more often.

  • Event ticket: The Wallet API ensures optimal processing creation of bulk event tickets. It does not matter whether these are entertainment, cultural or sporting events. With the help of pass style. you can provide your clients with an efficient, fast, safe, and easy way to use when accessing any type of event without any extras.

  • Boarding pass: A mobile boarding pass is a digital document provided by transit organizations to board an airplane, train, or bus. The pass includes a QR code which allows the passenger to easily board by showing the mobile QR code at the security checkpoints before boarding time. Each pass usually corresponds to a single trip with a specific starting and ending point.

  • Coupon: The coupon is a digital ticket that can be redeemed for a financial discount or rebate when purchasing a product. With this type of pass, you can offer discounts, offers, and promotions to your customers. The growing popularity of eCommerce has greatly contributed to the rise of coupon codes. This form of discount is easier for the customer to complete at the point of sale.

  • Generic pass: This pass style allows you to personalize your own pass by adding fields and images to the wallet template. When viewed by a user, the pass looks like a simple card, with a front side and a backside. You can use it to create membership cards or claim tickets.

When you create a wallet template, the request body contains the following data:

HTTP Request : POST /wallet/templates

{
  "name": "test Template doc",
  "type": "storecard",
  "description": "A wallet pass storecard example",
  "organization": "My Organization Name"
}

The parameters presented in the request body example when creating the Wallet Template are the following:

Parameter Required Description
name Yes

Wallet Template name.
type Yes

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.
description Yes

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

Identifies your brand inside the wallet pass.
googlePayCompatible No

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).

By default is false.

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

{
  "meta": {
    "timestamp": 1662500442846,
    "transactionId": "9e06797b-ec38-4368-b883"
  },
  "data": {
    "serial": "6317be5a8373144f2b4e14cc",
    "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-06T21:40:42.792408093",
    "lastUpdated": "2022-09-06T21:40:42.792408093",
    "createdBy": "[email protected]"
  }
}

The parameters presented in the response body example when creating the Wallet Template are the following:

Parameter Description
data

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

Unique identifier of the wallet template.
data.passTypeId

Unique identifier of the pass type template.

Used to distinguish pass types.
data.name

Required. Wallet Template name.
data.type

Required. 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

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

Required. Identifies your brand inside the wallet pass.
data.googlePayCompatible

Optional. 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).

By default is false.
data.creationDate

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

Date when the wallet template has been updated.
data.last_update_date

Date when the last update or status change.
data.createdBy

User who created the wallet template.

Updating Wallet Template

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

117

Aztec

130

PDF-417

197

Code128

154

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:

3686

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.

Creating Wallet Passes

Create New Wallet Passes based on the Apple and Google json keys defined in your wallet template and send on payload the wallet pass object in JSON format and access them from a URL link.

The next step is creating a wallet pass or passes and sending on payload the wallet pass object in JSON format. That is, you can create a specified wallet pass according to the wallet template that was created or updated previously. With this call, you can also specify and add the unique values you set in the wallet template as fields, images, barcode or beacons for each wallet pass.

It should be remembered, the unique values are personalized for each pass generated. For example, the Secondary field (label) is "Name" and you want that the secondary field value of the "Name" to be personalized for each pass that is generated, which means that value will not be static for each pass to generate, so the Secondary field ("Name") must be entered in the request body in JSON format because each value of the Secondary field will be personalize for each pass created.

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

Required ParameterDescription
serialUnique identifier of the Wallet Template.

When you create or update one or more wallet passes, the request body contains the following data according to the unique values you set when creating the wallet template:

HTTP Request : POST /wallet/templates/{serial}/passes/batch

📘

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 or according to the unique values you set up when creating the wallet template.

Each parameter you set as a unique value when creating the wallet template, it is required when creating the wallet pass. For example, if you didn't set any image type as a unique value, you don't need to add the image to the request body because the image will not be unique for each wallet pass, it will be generic (static) for all generated passes. Only those parameters that are unique values (not generic) are included in the request body when creating the wallet pass as long as they were configured when the wallet template was created.

When updating the wallet template, it was included only two unique values:

"fields": [
    {
      "place": "SECONDARY",
      "label": "Name",
      "fixed": false
    },
    {
      "place": "SECONDARY",
      "label": "Last Name",
      "fixed": false
    }
 ]

But in the request body example, we added the image and barcode as unique values to help you understand the JSON format if you set more than one unique value.

{
  "items": [
    {
      "recipientId": "123ddd20",
      "uniqueValues": {
        "fields": [
          {
            "place": "SECONDARY",
            "label": "Name",
            "value": "Elizabeth"
          },
          {
            "place": "SECONDARY",
            "label": "Last Name",
            "value": "Smith"
          }
        ],
        "images": [
          {
            "name": "strip",
            "url": "https://www.example.com/wp-content/uploads/example-Strip-Image-AirplaneTicket.png"
          }
       ],
        "barcode": {
            "altText": "Scan the QR code to download the airplane tickets",
            "content": "www.airplaneTickets22.com"
         }
      }
    },
    {
      "recipientId": "135dfc97",
      "uniqueValues": {
        "fields": [
          {
            "place": "SECONDARY",
            "label": "Name",
            "value": "Joshua"
          },
          {
            "place": "SECONDARY",
            "label": "Last Name",
            "value": "Williams"
          }
        ],
        "images": [
          {
            "name": "strip",
            "url": "https://www.example.com/wp-content/uploads/example-Strip-Image-ConcertTicket.png"
          }
        ],
        "barcode": {
            "altText": "Scan the QR code to download the concert tickets",
            "content": "www.concertTickets3434.com"
         }
      }
    }
  ]
}

The parameters presented in the request body example when creating the Wallet Pass are the following:

Parameter Required Description
items Yes

List (array) of wallet passes that will be created.
items.recipientId Yes

Unique identifier of the recipient.

The recipient ID must be different for each generated wallet pass.
items.uniqueValues Yes

Specify the unique values you set in the wallet template as fields, images, barcode or beacons for each wallet pass.
items.uniqueValues.fields No

Wallet Template text fields you set as unique values.

If the "fixed" parameter you set as true (unique value) when creating the wallet template, you need to specify the field values.
items.uniqueValues.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.

items.uniqueValues.fields.label Yes

Field text.
items.uniqueValues.fields.value Yes

Value of the field text.
items.uniqueValues.images No

Wallet Template images you set as unique values.

If the "fixed" parameter you set as true (unique value) when creating the wallet template, you need to specify the image values.
items.uniqueValues.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.
items.uniqueValues.images.url No

URL where the image is located.

By default a custom image is displayed.
items.uniqueValues.barcode No

Wallet Template barcode information you set as unique values.

If the "contentFixed" or "altTextFixed" parameter you set as true (unique value) when creating the wallet template, you need to specify the barcode values.
items.uniqueValues.barcode.altText No

Text displayed below the barcode.
items.uniqueValues.barcode.content No

String encoded in the barcode.
items.uniqueValues.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.

If the "Fixed" parameter you set as true (unique value) when creating the wallet template, you need to specify the beacon values.
items.uniqueValues.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
items.uniqueValues.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.
items.uniqueValues.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.
items.uniqueValues.beacons.text Yes

Text to display nearby a beacon.

When you create the Wallet Pass, the response body contains the following data:

{
  "meta": {
    "timestamp": 1663784641851,
    "transactionId": "b947a798-e12a-414a-977f-92cf3c91817b"
  },
  "items": [
    {
      "recipientId": "135dfc97",
      "url": "msgi.me/t0n111"
    },
    {
      "recipientId": "123ddd20",
      "url": "msgi.me/VNN777"
    }
  ]
}

The parameters presented in the response body example when creating the Wallet Pass are the following:

Parameter Description
items

List (array) of wallet passes created.
recipientId

Unique identifier of the recipient.

The recipient ID must be different for each generated wallet pass.
url

URL of the wallet pass.

NOTE: Copy and paste the URL into your browser to download the wallet pass that has been created.

Downloading Wallet Pass

Once the wallet pass is created, we proceed to download the pass and distribute it to end users.

To be called from devices, you need to download the pass for the given template and recipient ids, providing the proper object for each platform based on its User-Agent.

When the pass is downloaded from Apple devices, they will receive the Apple Wallet pkpass file.

When the pass is downloaded from Android devices, they will be redirected to the GooglePay save link (https: //pay.google.com/gp/v/save / ...)

HTTP Request : GET /wallet/templates/{serial}/passes/{recipientId}/download

When the browser sends a GET request to
https://elastic.messangi.me/ironbank/v2/wallet/templates/serial/passes/recipientId/download the pass will be downloaded immediately with filename 'serial.pkpass'.

Before downloading the wallet pass, you need to provide the unique identifier of the wallet template created and the recipient ID of the pass you want to download.

Required ParameterDescription
serialUnique identifier of the Wallet Template.
recipientIdUnique identifier of the recipient.

The recipient ID must be different for each generated wallet pass.

Example

In the following example, we are going to create a store card.

These instructions describe how you can create your first Wallet Template! Using cURL calls.

Before you can start using the Wallet API, you need to complete the following steps:

  1. Get access credentials.

  2. Get your API Key

  3. Have cURL installed in your machine

For more information, go to the Build your API Call section.

Your API call must have the following components:

  • A host -> The host requests are always [ https://elastic.messangi.me/ ]

  • An Authorization header -> Your API Key must be included in the Authorization header.

  • A request -> When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

Create a Wallet Pass Template

The steps to create a wallet pass template of a store card using the Wallet API are the following:

curl -X POST "https://elastic.messangi.me/ironbank/v2/wallet/templates" -H  "accept: application/json" -H  "Authorization: Bearer <YOUR_API_KEY>" -H  "Content-Type: multipart/form-data" --form 'template={
  "name": "Example Store card",
  "type": "storecard",
  "description": "Wallet pass storecard example",
  "organization": "SmallYuGi7"
}'
💻
Create Wallet Template
Open Recipe

  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the Authorization header.

  4. In the data section, we recommend you to specify the name ( Template name ), type ( Template pass type ), description ( Brief description of the pass ) and organization ( Your brand inside the pass ) before entering the other parameters.

  5. Copy the code and paste it in your terminal command.

  6. Press Enter.

  7. Check the response body and verify the wallet template created.

  8. Copy the parameter serial (Template ID) located in the response body for future requests.

Update a Wallet Pass Template

Once the template is created, we proceed to add the parameters to create an intuitive store card pass for the user.

The steps to update a wallet pass template of a store card using the Wallet API are the following:

curl -X PATCH "https://elastic.messangi.me/ironbank/v2/wallet/templates/<WALLET_TEMPLATE_ID>" -H  "accept: application/json" -H  "Authorization: Bearer <YOUR_API_KEY>" -H  "Content-Type: multipart/form-data" --form 'template={
"fields": [
    {
      "place": "HEADER",
      "label": "Points",
      "fixed": "false"
    },
    {
      "place": "SECONDARY",
      "label": "Name",
      "fixed": "false"
    },
    {
      "place": "SECONDARY",
      "label": "Last Name",
      "fixed": "false"
    },
    {
      "place": "AUXILIARY",
      "label": "email",
      "fixed": "false"
    }
  ],
"images": [
    {
      "name": "logo",
      "fixed": "true"
    },
    {
      "name": "icon",
      "fixed": "true"
    },
    {
      "name": "strip",
      "fixed": "true"
    }
  ],
 "googlePayCompatible" : true,
   "visualInfo" : {
        "labelColor" : "#666666",
        "backgroundColor" : "#f3f3f3",
        "foregroundColor" : "#0000ff",
        "barcode" : {
          "type" : "QR",
          "contentFixed" : false,
          "altTextFixed" : false
        }
      }  
}' --form "[email protected]/mnt/c/Users/tec13/Pictures/logo.png;type=image/png" --form "[email protected]/mnt/c/Users/tec13/Pictures/icon.png;type=image/png" --form "[email protected]/mnt/c/Users/tec13/Pictures/strip.png;type=image/png"

  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the Authorization header.

  4. Copy the unique identifier serial of the wallet template into the URL.

  • Next we add the optional fields to the curl call:

  • Activate pass compatibility with Google Pay

  • Template fields : PRIMARY, SECONDARY, AUXILIARY, HEADER.

  • Template images: icon, logo, strip.

  • Visual info: barcode [QR]

    The values of the template fields and the barcode are unique.

  1. In the data section, we recommend you to specify the fields ( Template fields ), images ( Template images ), visualInfo ( Visual information of the pass ) and googlePayCompatible ( Compatibility with Google Pay ).

  2. Copy the code and paste it in your terminal command.

  3. Press Enter.

  4. Check the response body and verify the wallet template updated.

  5. Copy the parameter serial (Template ID) located in the response body for future requests.

Create Wallet Passes

Once the template is created, we proceed to create the store card pass for two users.

The steps to create one or more wallet passes of a store card using the Wallet API are the following:

curl -X POST "https://elastic.messangi.me/ironbank/v2/wallet/templates/<WALLET_TEMPLATE_ID>/passes/batch" -H  "accept: application/json" -H  "Authorization: Bearer <YOUR_API_KEY>" -H  "Content-Type: application/json;charset=UTF-8" -d "{\"items\":[{\"recipientId\":\"abcdefg7\",\"uniqueValues\":{\"fields\":[{\"place\":\"HEADER\",\"label\":\"Points\",\"value\":\"50\"},{\"place\":\"SECONDARY\",\"label\":\"Name\",\"value\":\"Sarah\"},{\"place\":\"SECONDARY\",\"label\":\"Last Name\",\"value\":\"Carter\"},{\"place\":\"AUXILIARY\",\"label\":\"email\",\"value\":\"[email protected]\"}],\"barcode\":{\"altText\":\"my VAR altText\",\"content\":\"my VAR content\"}}},{\"recipientId\":\"abababab\",\"uniqueValues\":{\"fields\":[{\"place\":\"HEADER\",\"label\":\"Points\",\"value\":\"20\"},{\"place\":\"SECONDARY\",\"label\":\"Name\",\"value\":\"Joshua\"},{\"place\":\"SECONDARY\",\"label\":\"Last Name\",\"value\":\"Albarn\"},{\"place\":\"AUXILIARY\",\"label\":\"email\",\"value\":\"[email protected]\"}],\"barcode\":{\"altText\":\"my VAR altText\",\"content\":\"my VAR content\"}}}]}"

  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the Authorization header.

  4. Copy the unique identifier serial of the wallet template into the URL.

  5. Next we add the unique values to the curl call:

  • Template fields: PRIMARY, SECONDARY, AUXILIARY, HEADER.

  • Visual info: barcode [QR]

  1. In the data section, specify the recipientId ( unique identifier of the recipient ), uniqueValues ( unique values ), fields ( template fields which are unique ) and barcode ( barcode which is unique ).
    Copy the code and paste it in your terminal command.

  2. Press Enter.

  3. Check the response body and verify the wallet template updated.

  4. In the response body, you can download the passes by copying every value of the url parameter and placing it in the browser the pkpass will be downloaded immediately.

"items": [
    {
      "recipientId": "-8a04732e682g",
      "url": "elastic.messangi.me/--"
    },
    {
      "recipientId": "135dfc977382g",
      "url": "elastic.messangi.me/--"
    }
  1. Copy the parameter serial (Template ID) and recipientId located in the response body for future requests.

Download Wallet Passes

Once the pass is created, we proceed to download the store card pass for the users.

The steps to download a wallet pass using the Wallet API are the following:

curl -X GET "https://elastic.messangi.me/ironbank/v2/wallet/templates/<WALLET_TEMPLATE_ID>/passes/<RECIPIENT_ID>/download?forcePkPass=true" -H  "accept: application/vnd.apple.pkpass" -H  "Authorization: Bearer <YOUR_API_KEY>" --output <WALLET_PASS_NAME>

  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the Authorization header.

  4. In the data section, select the URL and enter the id (serial) of the wallet template and his recipient Id (recipientId) into the URL:

[ https://elastic.messangi.me/ironbank/v2/wallet/templates/{serial}/passes/{recipientId}/download?forcePkPass=true ]

  1. To download the Wallet Pass with a specific name, type the desired name of the pass :
    --output <WALLET_PASS_NAME>

  2. Copy the code and paste it in your terminal command or copy the URL to your Browser.

  3. Press Enter.

  4. The pass will be downloaded immediately.

  5. Copy the parameter serial (Template ID) and recipientId located in the response body for future requests.

Congratulations! You have created your own pass!

Updated 5 months ago