Home
Guides
Start typing to search…

Wallet Data Entities: Wallet Transactions

What is a Wallet Transaction

A wallet transaction is a wrapper object that pulls together several other data points. It aligns to a completed customer journey. For example, a journey through a checkout process. It holds the details of what happened in that interaction.

The data points held against a wallet transaction are:

  • Basket contents
  • Payment information
  • Account Transactions
  • Metadata
  • Transaction Type
  • Status
  • State

Transaction Types

Wallet Transactions hold a data point of "type". In the AIR standard configurations, the below is a list of transaction types and where they are used.

Transaction TypeDescription
ADJUSTMENTA wallet transaction which is generated when making a points adjustment
BEHAVIOURAL_ACTION_POINTSA wallet transaction which is generated by completing a behavioural action and rewarding points
BEHAVIOURAL_ACTION_COUPONA wallet transaction which is generated by completing a behavioural action and rewarding a coupon
CHALLENGE_REWARDA wallet transaction which is generated for when using the EagleAI Challenges functionality and the completion rewards
CREDITA wallet transaction which is generated when crediting points through Customer Care
DEBITA wallet transaction which is generated when debiting points through Customer Care
DONATIONA wallet transaction which is generated when donating points
EXCHANGEA wallet transaction which is generated when exchanging points for a coupon
EXPIRYA wallet transaction which is generated when points expire
FULFILA wallet transaction type used when a transaction is following the fulfil journey
GAME_REWARDA wallet transaction type used when a gamification entry is completed by a third party platform
GIFTA wallet transaction which is generated when gifting points
GOODWILLA wallet transaction which is generated when issuing goodwill points
PRODUCT_EXCHANGEA wallet transaction used for the product exchange functionality in POS Connect
REDEEM_CREDITA wallet transaction which is generated when a coupon is redeemed and points credited via the wallet services endpoint
SETTLEA wallet transaction occurred due to a settle request from POS Connect - Settle
SPENDA wallet transaction which is generated by spending points at POS
SUBSCRIPTION_CREATEDA wallet transaction which is generated when a subscription is created
SUBSCRIPTION_RENEWEDA wallet transaction which is generated when a subscription is renewed
SUBSCRIPTION_CANCELLEDA wallet transaction which is generated when a subscription is cancelled
UNREDEEMA wallet transaction which is generated when un-redeeming a coupon via Customer Care
VOIDA wallet transaction created for when a transaction gets voided

Although the above transactions are part of the AIR standard configuration, additional types can be added on demand. Please contact your System Integrator to help with adding new types.

Wallet Transaction Statuses

ACTIVE

The wallet transaction has been created but not yet settled. For example, when Wallet Open is called and locking is enabled, an ACTIVE wallet transaction is created to later be settled.

SETTLED

The transaction is completed and no further updates are expected after this time

EXPIRED

Available to be used but nothing in AIR uses this status

CANCELLED

If a transaction is cancelled without being settled, the status is changed to CANCELLED

PURGED

After a period of time, the basket contents and payment information are removed from the transaction but the summary is maintained in alignment with the AIR data retention policies.

VOIDED

If a transaction is undone without being settled, the status can be changed to VOIDED

EMPTIED

The contents have been removed

FULFILLED

If the POS Connect Fulfil funcitonality is being used, this status represents the end of the journey. No further updates are expected after this point.

FULFILLING

The wallet transaction is not yet fully shipped but is in the process of being fulfilled.

Wallet Transaction States

As in all wallet entities, state is a confurable data point that clients can setup to meet their needs. We have found however that there are two states used repeatedly across EagleEye clients. Those are listed below with a description of how they are used.

ORIGINAL

A wallet transaction in this state is in it's original structure and no changes have been made. This is the most common case for wallet transactions

MODIFIED

When a transaction has been updated since it's initial data (via a return for example).

Wallet Transaction Data Structure

The below provides a sample wallet transaction from a POS Connect settle.

{
  "walletTransactionId": "123",
  "parentWalletTransactionId": "0",
  "walletId": "321",
  "reference": "aaa4c524-863d-4bc1-8b8a-fb416d4b66a5",
  "transactionDateTime": "2025-08-27T14:24:52+00:00",
  "transactionDateTimeOffset": "+00:00",
  "identityId": "2345",
  "identity": {
    "identityId": "197097398",
    "walletId": "244727065",
    "type": "CUSTOMER_ID",
    "friendlyName": null,
    "value": "[email protected]",
    "safeValue": null,
    "secret": null,
    "dates": {
      "start": "2025-08-27T14:24:38+00:00",
      "end": null
    },
    "meta": [],
    "state": "DEFAULT",
    "status": "ACTIVE",
    "dateCreated": "2025-08-27T14:24:38+00:00",
    "lastUpdated": "2025-08-27T14:24:38+00:00",
    "mobileWallet": "https://sb.uk.mypass.is/identity/1/2/3/456"
  },
  "type": "SETTLE",
  "status": "SETTLED",
  "meta": null,
  "state": "ORIGINAL",
  "expiryDate": null,
  "accounts": [
    {
      "accountId": "12345",
      "accountTransactionId": "65432"
    }
  ],
  "basket": {
    "contents": [
      {
        "upc": "54321",
        "itemUnitCost": 500,
        "salesKey": "SALE",
        "totalUnitCostAfterDiscount": 500,
        "totalUnitCost": 500,
        "description": "Basket Item",
        "itemUnitMetric": "EACH",
        "itemUnitCount": 1,
        "contributionResults": [
          {
            "instanceId": "1577698-1",
            "value": 7500
          }
        ]
      },
      {
        "upc": "12345",
        "itemUnitCost": 500,
        "salesKey": "SALE",
        "totalUnitCostAfterDiscount": 500,
        "totalUnitCost": 500,
        "description": "Basket Item 2",
        "itemUnitMetric": "EACH",
        "itemUnitCount": 1,
        "contributionResults": [
          {
            "instanceId": "1577698-1",
            "value": 7500
          }
        ]
      }
    ],
    "summary": {
      "redemptionChannel": "instore",
      "totalDiscountAmount": {
        "general": null,
        "staff": null,
        "promotions": null
      },
      "totalQualifyingAmount": {
        "points": 1000,
        "baseEarn": 1000,
        "promotions": 1000,
        "discount": 1000
      },
      "totalItems": 2,
      "totalBasketValue": 1000,
      "results": {
        "points": {
          "spend": 0,
          "debit": 0,
          "refund": 0,
          "totalPointsTaken": 0,
          "earn": 15000,
          "credit": 0,
          "totalPointsGiven": 15000,
          "totalMonetaryValue": 0
        }
      }
    },
    "payment": null
  },
  "channel": "api",
  "location": {
    "storeId": "0001",
    "storeParentId": "banner1"
  },
  "dateCreated": "2025-08-27T14:24:52+00:00",
  "lastUpdated": "2025-08-27T14:25:14+00:00"
}

Updated about 4 hours ago