What is a Wallet Identity

A Wallet Identity is the key to finding and opening the wallet. This data object can take on many different forms and be used in different ways:

Loyalty Card Number
Email Address
Phone Number
Third Party System Identifier for a customer
Mobile App Identifier
etc.

AIR can be configured to have as many different Identity Types as are required by a given integration. Limitations can also be applied to the setup, allowing, say, only a single identity of type EMAIL in a customer's wallet.

There is a resources API to create new Identity Types.

Example Identity Usage

As a customer proceeds through a physical checkout in a brick-and-mortar location, they might choose to open their mobile APP and scan their APP identity so they can get the rewards in their wallet made available. This identity value is sent to AIR to find the customer's wallet before proceeding to adjudicate the customer's basket.

Similarly, they may have chosen to use a Key Fob with a printed barcode on it to identify themselves. Both of these identity values would be in the same wallet, meaning that through both routes, the same customer is found in AIR.

Wallet Identity Data Structure

{
    "identityId": "197008851",
    "walletId": "244602841",
    "type": "CUSTOMER_ID",
    "friendlyName": null,
    "value": "3db4adee64c89530a4cec95643b27845",
    "safeValue": null,
    "secret": null,
    "dates": {
        "start": "2025-08-22T11:53:35+00:00",
        "end": null
    },
    "meta": [],
    "state": "DEFAULT",
    "status": "ACTIVE",
    "dateCreated": "2025-08-22T11:53:35+00:00",
    "lastUpdated": "2025-08-22T11:53:35+00:00",
    "mobileWallet": null
}

Key	Data Type	Description
idenitityId	String	A unique Identifier generated by AIR for this identity
walletId	String	The ID of the wallet to which this identity belongs
type	String	The type of identity created. These are configured using the above mentioned Identity Type Create API
friendlyName	String	A value that can hold a user input name for the identity. This is often used so an end user can easily identity the identity. E.g. John's Mobile
value	String	This is the value for the identity. This value can be provided by the retailer creating the identity, or it can be automatically generated by AIR depending on the configuration of the identity type
safeValue	String	This value can be used by third-party platforms to perform a check on the individual presenting the identity. E.g. an answer to a pre-set security question. AIR does not do anything with this value.
secret
dates.start	DateTime in ATOM format	AIR does not validate this value but can be a used by other applications to ensure the identity is valid to be used
date.end	DateTime in ATOM format	Similar to dates.start
meta	Object	This object can hold arbitrary key/value pairs. Note - when empty this object appears as an empty array.
state	String	Identity States can be used, if required, to drive behaviour in AIr. For example, in POS Connect if the state was set to "EARNONLY", configuration can be added to prevent this identity from being allowed to spend points at POS and only earn them. This can be a fraud prevention measure. Identity types such as "MOBILE" numbers are easily to guess.
status	String	Identities can be in any of the below statuses: ACTIVE SUSPENDED LOST STOLEN INACTIVE TERMINATED
dateCreated	DateTime in ATOM format	This imutable date time is the time at which the identity is created in the AIR platform
lastUpdated	DateTime in ATOM format	This is the date and time that this identity value was last updated.
mobileWallet	String	This field is deprecated.

Identity Statuses

The below section outlines the meaning of the different IDentity statuses.

ACTIVE

The identity can be used to transact and no restrictions are applied.

SUSPENDED

This is a temporary status frequently used when some form of investigation is required and stops the customer from transacting for a short period at the POS.

LOST

This temporary status is used by customers to put a hold on this identity and prevent it being used. Once found, an identity can be re-activated.

Stolen

If an identity value has been compromised, the value is marked as stolen. This is a terminal status and this identity value can never be used within the loyalty programme again.

Inactive

Identities can be created in an INACTIVE status. They can not be used until the identity is activated. Once activated, an identity can not be transitioned back to INACTIVE

Terminated

This status is terminal. Once transitioned to TERMINATED, the identity can not be used to transact but the value remains in the customer's wallet for visibility.

Auto Generated Identity Values

If configured, AIR can generate an identity value for a customer's wallet. This configuration defines the format of the value to create. For example, if the need is to create a value that always starts with 12345 and is numeric only in nature, this can be configured.

On request to creat an identity in the customer's wallet, the value field is sent in as null (or not provided) and AIR will generate the value internally.

The identity type can be configured to allow a value to be passed in as well. IF this is the case, AIR will ensure the value conforms to the configured format and instead of generating it's own value, use the one passed.