Mobile Wallet API

The Mobile Wallet API purpose, authentication, fields, request and response parameters, payloads, and feature description.

API Overview

The Mobile Wallet API provides the ability to create and update mobile wallet passes/objects for Apple iOS and Google Android Pay.

Base URL

The base URL for all API calls is: https://api.imimobilewallet.com/api/

The Mobile Wallet implementation might be deployed in more than one geographical region.

Check with the IMImobile staff to verify which base URL is most compatible with your requirements.

Authentication

All requests to the API require a use of the authentication key as an HTTP header for all requests.

  • Name of the header: x-api-key
  • Value can be looked up on the Integration Page when you are logged into the Wallet UI.

Create and Update Notes

Apple notes

Preferably, list all fields in the API that are included in a pass by UI, for create and update.

It is possible that if you add a new field into the Update request and not include existing fields into the call, it is possible that the existing fields might be deleted.

Google notes

There is a list of fields that are included in a template and they cannot be updated via API. They can be updated with the UI.
There is another list of fields that are only updated via API and not UI. There is yet another set of fields
that are updated via the UI or the API. If there is a new field added in the UI, it is static and cannot be changed via API.
If a field is added via the API, it can be updated via API again.

Create a wallet landing page

A landing page will display installation buttons for Android or Apple, which will allow the end user to install a wallet pass on a device.

📘

Note

Creation of a landing pages and sending links to such a pages to consumers does not guarantee installation of a passes on consumers' devices.
Ultimately, it up to consumers to install passes with the help of landing pages.

Request

  • Method: POST
  • URI: /wallet/[Wallet ID]/landing

Headers

NameValueRequired
Content-Typeapplication/jsonyes
x-api-keyapi keyyes

Body

The body of the request is in JSON format and may contain the following fields:

NameDescriptionRequired
dataA nested object that contains the data elements and values of the wallet object/pass.yes
data.barcode.typeFormat of the barcode. Possible values are: AZTEC, CODABAR, CODE128, CODE39, DATAMATRIX, EAN13, EAN8, ITF14, PDF417 ,PDF417COMPACT, QRCODE, TEXTONLY, UPCAyes
data.barcode.valueValue that is encoded in the barcodeyes
data.barcode.altTextValue that is encoded in the barcodeyes

Apple-Only Fields

📘

These custom fields only apply to Apple. N starts at 0. All values must be specified for a given field.

  • key - Identifier for the field
  • label - Label of the field that is displayed on the pass.
  • value - Value of the field that is displayed on the pass.
  • alignment - Alignment of the field value and label. Possible values are:
    • PKTextAlignmentLeft
    • PKTextAlignmentCenter
    • PKTextAlignmentRight
NameDescriptionRequired
data.customHeaderFields[N].key data.customHeaderFields[N].label data.customHeaderFields[N].value data.customHeaderFields[N].alignHeader fields are displayed at the top of the pass.no
data.customPrimaryFields[N].key
data.customPrimaryFields[N].label data.customPrimaryFields[N].value data.customPrimaryFields[N].align
Primary fields are displayed on the strip image of the passno
data.customSecondaryFields[N].key data.customSecondaryFields[N].label
data.customSecondaryFields[N].value
data.customSecondaryFields[N].align
Secondary fields are located below the strip image.no
data.customAuxiliaryFields[N].key data.customAuxiliaryFields[N].label
data.customAuxiliaryFields[N].value data.customAuxiliaryFields[N].align
Auxiliary fields are located below the secondary fields.no
data.customBackFields[N].key data.customBackFields[N].label data.customBackFields[N].value data.customBackFields[N].alignBack fields are located on the back of the pass.no

Google-Only Fields

📘

The texts field only applies to Google. Both header and body must be specified. N starts at 0.

NameDescriptionRequired
texts[N].header texts[N].bodyAdds a text field to the wallet object.no
{
  "data":{
    "type":"offer",
    "state":"active",
    "expirationDate":"2017-12-31T23:59:59-0400",
    "validTimeInterval.end":"2017-12-31T23:59:59-0400",
    "barcode.type":"CODE128",
    "barcode.value":"CPN12345678",
    "barcode.altText":"CPN12345678",
    "customHeaderFields[0].key":"headerField1",
    "customHeaderFields[0].label":"Expires",
    "customHeaderFields[0].value":"12/31/17",
    "customHeaderFields[0].align":"PKTextAlignmentLeft",
    "customSecondaryFields[0].key":"secondaryField1",
    "customSecondaryFields[0].label":"SPEED PERKS DOUBLE REWARDS",
    "customSecondaryFields[0].value":"$10 off $50 purchase",
    "customSecondaryFields[0].align":"PKTextAlignmentLeft",
    "texts[0].header":"SPEED PERKS DOUBLE REWARDS",
    "texts[0].body":"$10 off $50 purchase"
  }
}

Request

Status Code: 200 - The mobile wallet pass/object was successfully created

Response body

The body of the response is in JSON format. Most of the response fields are the same as

in the request. In addition, the response returns a passId and a URL link to the landing page

for installation of this pass on a device.

{
  "content": {
    "passId": "XXXXXX",
    "walletId": "XXXXXXX",
    "accountId": "accountId",
    "appleTemplateId": "e3tgewokrnfrdkc2kudmzu3zxe",
    "googleTemplateId": "AdvanceAutoPartsOctober2017",
    "data": {
      "state": "active",
      "expirationDate": "2017-12-31T23:59:59-0400",
      "validTimeInterval.end": "2017-12-31T23:59:59-0400",
      "barcode.type": "CODE128",
      "barcode.value": "CPN12345678",
      "barcode.altText": "CPN12345678",
      "customHeaderFields[0].key": "headerField1",
      "customHeaderFields[0].label": "Expires",
      "customHeaderFields[0].value": "12/31/17",
      "customHeaderFields[0].align": "PKTextAlignmentLeft",
      "customSecondaryFields[0].key": "secondaryField1",
      "customSecondaryFields[0].label": "SPEED PERKS DOUBLE REWARDS",
      "customSecondaryFields[0].value": "$20 off $50 purchase",
      "customSecondaryFields[0].align": "PKTextAlignmentLeft",
      "texts[0].header": "SPEED PERKS DOUBLE REWARDS",
      "texts[0].body": "$20 off $50 purchase"
    },
    "distributionType": "ONE-TO-ONE",
    "landingPageStrategy": "GOOGLE",
    "customLayout": {
      "mainImage": "<https://-> link to an image",
      "mainImagePosition": "BELOW",
      "logoImagePosition": "CENTER",
      "titleText": "SAVE NOW!",
      "mainText": "any text here, including HTML markup",
      "installConfirmationPage": {
        "text": "<b>Your reward can be found in your Apple Wallet or Google Android Pay app.</b><br><br><b>Visit shop.acmeshop.com for the latest deals.</b>",
        "fontColor": "#ffffff",
        "backgroundColor": "#000000"
      }
    },
    "redirect": true,
    "passName": "SpeedPerksDiscount10"
  },
  "_links": {
    "self": {
      "href": "<https://imimobilewallet.com/passes/[PASS> ID HERE]/landing.html"
    }
  }
}

Update a single wallet pass

Pass Update

Apple allows updating (also adding or removing) almost all fields through API calls.

Google allows updating only fields used in API call when issuing a pass. Some fields could be added: texts, messageList.

Wallet Template Update

Updating a published wallet template has no effect on the apple passes, only future passes will include the changes

On the other hand updating a published wallet template will change all installed google passes

Wallet passes/objects may be updated using this API. The passId and data

Objects are required for the update requests. Only data for fields that are changing need to be specified, however, all fields may be specified if desired.

📘

Note

If a field is present in a template, but omitted from the request, its value from the template will be displayed.

Fields may be modified or added using this API. A lock screen notification message may be triggered on Apple IOS devices to inform the consumer that the pass has been updated.

Request

  • Method: PATCH
  • URI: /pass

Headers

NameValueRequired
Content-Typeapplication/jsonyes

Body

The body of the request is a JSON object and may contain the following fields:

NameDescriptionRequired
passIdThe ID of the wallet pass/object to update.yes
customLayoutMust be included but the value portion can be left blankYes
dataA nested object that contains the data elements and values of the wallet object/pass. All data fields (except for type) must be specified including values that are not changing. Additional data fields may be included.yes
data.trackProgressPass this as "true" in order to track the progress of a pass upade on the Status report page in wallet builder uino
data.<field>.changeMessage (Apple only)A lock screen notification may be triggered on Apple devices to notify the consumer about the update by including a changeMessage value. The lock screen notification only displays when a field value is modified.
Notes about using changeMessage:

1. Use %@ in the changeMessage to display the new value of the field within the lock screen notification message.
2. If %@ is omitted from the changeMessage, the notification message will say "Store card changed" or "Coupon changed" (depending on the pass type) regardless of any other text in the changeMessage.
3. %@ only applies to the field value (for example, an updated label will not trigger a lock screen notification).
4. Multiple fields may be updated, but the lock screen notification is only capable of displaying information about one of the fields.
no

Example 1: Update an existing field

{
  "passId": "XXXXXXXXX",
  "customLayout": {},
  "data": {
    "expirationDate": "2021-01-15T23:59:59-0400",
    "validTimeInterval.end": "2021-01-15T23:59:59-0400",
    "customHeaderFields[0].key": "headerField1",
    "customHeaderFields[0].label": "Expires",
    "customHeaderFields[0].value": "01/15/21",
    "customHeaderFields[0].align": "PKTextAlignmentLeft",
    "customHeaderFields[0].changeMessage": "Your offer expiration has been extended until %@",
    "trackProgress":"true"
  }
}

Example 2: Add New Field

{
  "passId": "XXXXXXX",
  "customLayout": {},
  "data": {
    "customBackFields[0].key": "BackField1",
    "customBackFields[0].label": "Reminder",
    "customBackFields[0].value": "Don't forget to use your Volume Perks reward before it expires!",
    "customBackFields[0].align": "PKTextAlignmentLeft",
    "customBackFields[0].changeMessage": "%@"
  }
}

Response

Status Code: 200 - The mobile wallet pass/object was successfully updated

Response Body

The body of the response is a JSON document. Most of the response fields are the same as in the
response for the issue method. Any new field values or changeMessage fields will be included as well.

Example:

{
  "content": {
    "passId": "XXXXXXX",
    "appleTemplateId": "e3tgewokrnfrdkc2kudmzu3zxe",
    "googleTemplateId": "AcmeToolsOctober2020",
    "data": {
      "type": "offer",
      "state": "active",
      "expirationDate": "2021-01-15T23:59:59-0400",
      "validTimeInterval.end": "2021-01-15T23:59:59-0400",
      "barcode.type": "CODE128",
      "barcode.value": "CPN12345678",
      "barcode.altText": "CPN12345678",
      "customHeaderFields[0].key": "headerField1",
      "customHeaderFields[0].label": "Expires",
      "customHeaderFields[0].value": "01/15/21",
      "customHeaderFields[0].align": "PKTextAlignmentLeft",
      "customHeaderFields[0].changeMessage": "Your offer expiration has been extended until %@",
      "customSecondaryFields[0].key": "secondaryField1",
      "customSecondaryFields[0].label": "SPEED PERKS DOUBLE REWARDS",
      "customSecondaryFields[0].value": "$20 off $50 purchase",
      "customSecondaryFields[0].align": "PKTextAlignmentLeft",
      "texts[0].header": "SPEED PERKS DOUBLE REWARDS",
      "texts[0].body": "$20 off $50 purchase"
    },
    "distributionType": "ONE-TO-ONE",
    "landingPageStrategy": "GOOGLE",
    "customLayout": {
      "mainImage": "https:[url to image here]",
      "mainImagePosition": "BELOW",
      "logoImagePosition": "CENTER",
      "titleText": "SAVE NOW!",
      "mainText": "<b>Volume Perks reward: Save $20 today!</b>",
      "installConfirmationPage": {
        "text": "<b>Your reward can be found in your Apple Wallet or Google Android Pay app.</b><br><b>Visit acmetools.com for latest deals.</b>",
        "fontColor": "#ffffff",
        "backgroundColor": "#000000"
      }
    },
    "redirect": true,
    "passName": "SpeedPerksDiscount10"
  },
  "_links": {
    "self": {
      "href": "<https://api.imimobilewallet.com/passes/XXXXXXXX/landing.html">
    }
  }
}

Retrieve a single wallet pass

An issued wallet pass/object may be retrieved using its passId.

Request

  • Method: GET
  • URI: /pass/{passId}

Headers

NameValueRequired
Content-Typeapplication/jsonyes

Body

The body of the response is in JSON format. Most of the response fields are the same as a response for the issue method. Any new field values or changeMessage fields will be included as well.

Example Curl request:

curl -X GET -H "Content-type: application/json" -H \
  "x-api-key: [API AUTH KEY]" <https://api.imimobilewallet.com/api/pass/[PASS> ID]

Response:

{
    "content": {
        "passId": "[PASS ID]",
            "walletId": "[WALLET ID]",
            "googleTemplateId": "[GOOGLE TEMPLATE ID]",
            "data": {
            "texts[0].body": "update body",
                "barcode.type": "PDF417",
                "walletName": "amazon",
                "barcode.value": "123",
                "texts[0].header": "Update",
                "trackProgress": "true",
                "state": "active",
                "type": "offer"
        },
        "distributionType": "ONE-TO-ONE",
            "landingPageStrategy": "CUSTOM",
            "customLayout": {
            "type": "STACKED",
                "useOriginalImages": true,
                "hideBarcode": false,
                "googleTheme": "dark",
                "image1": {
                "name": "URL",
                    "url": "<https://google-wallet-assets.s3.amazonaws.com/e9187e90-4139-11eb-8c86-d770cac81bbd-image1.png">
            },
            "barcodePosition": "top"
        },
        "redirect": false,
            "passName": "amazon"
    },
    "_links": {
        "self": {
            "href": "<https://imimobilewallet.com/passes/[PASS> ID]/landing.html"
        }
    }
}

📘

Note

The 'data' field will contain only fields used when issuing and updating a pass.

Request a list of pass ids by wallet name

Request

  • Method: GET
  • URI: /api/wallet/[wallet_name]/passes

Request headers

NameValueRequiredDescription
Content-Typeapplication/jsonyes
Accepttext/csvnoIf omitted, the response will be in the JSON format. If provided, the response will be in a CSV format.

Response

A list of pass IDs associated with a provided wallet name in a CSV format with a single column.

Response headers

NameValue
Content-Dispositionattachment; filename="[wallet-name]-passes.csv"

Loyalty

UI field name (which are part of TEMPLATE)UI field name (Which are part of PASS)Key for API JSON Body (issue/update)Included in templateIncluded in pass
ACCOUNT IDloyaltyAccountIdYES
ACCOUNT NAMEloyaltyAccountNameYES
loyaltyPointsLabelYES
loyaltyPointsBalanceStringYES
loyaltyPointsBalanceIntYES
loyaltyPointsBalanceDoubleYES
loyaltyPointsBalanceMoneyValueYES
loyaltyPointsBalanceMoneyCurrencyCodeYES
linkedOfferIds[%index%]YES
secondaryLoyaltyPointsLabelYES
secondaryLoyaltyPointsBalanceStringYES
secondaryLoyaltyPointsBalanceIntYES
secondaryLoyaltyPointsBalanceDoubleYES
secondaryLoyaltyPointsBalanceMoneyValueYES
secondaryLoyaltyPointsBalanceMoneyCurrencyCodeYES
barcode.valueYES
BARCODE TYPE (BARCODE)BARCODE TYPEbarcode.typeYESYES
BARCODE ENCODING (BARCODE)YES
PROGRAM NAME (ANDROID)YES
ACCOUNT NAME LABEL (ANDROID)YES
ACCOUNT ID LABEL (ANDROID)YES
REWARDS TIER LABEL (ANDROID)YES
REWARDS TIER (ANDROID)YES
HOME PAGE URI (ANDROID)YES
ISSUER NAME (ANDROID)YES
ANDROID CARD BACKGROUND COLOR (GRAPHICS COLORS)YES
PASS TYPE (SETUP/PASS INFORMATION)YES
PASS TYPE (SETUP/PASS INFORMATION)messageList[].headerYESYES
ITEM BODY (ANDROID/MESSAGE)messageList[].bodyYESYES
ITEM LABEL (ANDROID/URLS)linkList[].descriptionYESYES
ITEM URI (ANDROID/URLS)linkList[].urlYESYES
ITEM HEADER (ANDROID/TEXT MODULE)textList[].headerYESYES
ITEM BODY (ANDROID/TEXT MODULE)textList[].bodyYESYES
HERO IMAGE (GRAPHICS/ANDROID/ANDROID IMAGES)heroImage.urlYESYES

Boarding

Offer

Gift

Event