Mobile Wallet
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.
|
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.
By default is |
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.
|
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.
By default is |
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.
Image | Description & Size | Wallet Pass Compatible |
---|---|---|
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. | Boarding pass Coupon Event ticket Store card Generic pass |
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. | Boarding pass Coupon Event ticket Store card |
strip | The strip image is displayed beneath the logo: 1125 pixels wide x 432 pixels high. | Coupon Event ticket Store card Generic pass |
footer | The footer image is displayed near the barcode: 381 pixels wide x 20 pixels high. | Boarding pass |
background | The background image is displayed behind the entire front side of the Wallet pass: 240 pixels wide x 293 pixels high. | Event ticket |
thumbnail | The thumbnail image displayed next to the fields on the front of the pass: 270 pixels wide x 270 pixels high. | Event ticket Generic pass |
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. |
In summary, the following table shows the images supported by each wallet pass type:
Wallet Pass Type | Supported images |
---|---|
Boarding pass | logo, icon, footer |
Coupon | logo, icon, strip |
Event ticket | logo, icon, strip, background, thumbnail If you specify a strip image, do not specify a background image or a thumbnail. |
Store card | logo, icon, strip |
Generic pass | logo, 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 type | Description |
---|---|
Primary fields | The primary fields contain the most important information and are shown prominently on the pass. |
Secondary fields | The secondary fields are less important and less prominent. |
Auxiliary fields | Auxiliary fields are even less important than secondary fields. |
Header fields | The header fields contain highly salient information, and they are the only field that is visible when the passes are stacked up in Wallet. |
Backfields | The 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 Parameter | Description |
---|---|
serial | Unique 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:
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.
|
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:
|
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.
|
fields.value | No | Value of the field text. If the If the |
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: |
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.
|
visualInfo.barcode.altTextFixed | Yes | Defines if the text displayed below the barcode (Alt Text) is unique or generic (fixed) for all recipients.
|
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 Useful for single-use coupons/cards. By default is |
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 |
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 |
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.
|
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 If this key is present, the |
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.
|
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.
|
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:
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.
|
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:
|
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.
|
data.fields.value | Optional. Value of the field text. If the If the |
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: |
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.
|
data.visualInfo.barcode.altTextFixed | Required. Defines if the text displayed below the barcode (Alt Text) is unique or generic (fixed) for all recipients.
|
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 Useful for single-use coupons/cards. By default is |
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 |
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 |
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.
|
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 If this key is present, the |
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 Parameter | Description |
---|---|
serial | Unique 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 |
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:
|
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 |
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:
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 |
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 |
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 |
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 |
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 Parameter | Description |
---|---|
serial | Unique identifier of the Wallet Template. |
recipientId | Unique 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:
-
Get access credentials.
-
Get your API Key
-
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"
}'
-
Copy the curl example above.
-
Paste the curl call into your favorite text editor.
-
Copy your API key and paste it in the
Authorization
header. -
In the data section, we recommend you to specify the
name
( Template name ),type
( Template pass type ),description
( Brief description of the pass ) andorganization
( Your brand inside the pass ) before entering the other parameters. -
Copy the code and paste it in your terminal command.
-
Press Enter.
-
Check the response body and verify the wallet template created.
-
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"
-
Copy the curl example above.
-
Paste the curl call into your favorite text editor.
-
Copy your API key and paste it in the
Authorization
header. -
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.
-
In the data section, we recommend you to specify the
fields
( Template fields ),images
( Template images ),visualInfo
( Visual information of the pass ) andgooglePayCompatible
( Compatibility with Google Pay ). -
Copy the code and paste it in your terminal command.
-
Press Enter.
-
Check the response body and verify the wallet template updated.
-
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\"}}}]}"
-
Copy the curl example above.
-
Paste the curl call into your favorite text editor.
-
Copy your API key and paste it in the
Authorization
header. -
Copy the unique identifier
serial
of the wallet template into the URL. -
Next we add the unique values to the curl call:
-
Template fields:
PRIMARY
,SECONDARY
,AUXILIARY
,HEADER
. -
Visual info: barcode [
QR
]
-
In the data section, specify the
recipientId
( unique identifier of the recipient ),uniqueValues
( unique values ),fields
( template fields which are unique ) andbarcode
( barcode which is unique ).
Copy the code and paste it in your terminal command. -
Press Enter.
-
Check the response body and verify the wallet template updated.
-
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/--"
}
- Copy the parameter
serial
(Template ID) andrecipientId
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>
-
Copy the curl example above.
-
Paste the curl call into your favorite text editor.
-
Copy your API key and paste it in the
Authorization
header. -
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 ]
-
To download the Wallet Pass with a specific name, type the desired name of the pass :
--output <WALLET_PASS_NAME>
-
Copy the code and paste it in your terminal command or copy the URL to your Browser.
-
Press Enter.
-
The pass will be downloaded immediately.
-
Copy the parameter
serial
(Template ID) andrecipientId
located in the response body for future requests.
Congratulations! You have created your own pass!
Updated 5 months ago