POS Connect Best Practices: Spend
Overview
This documentation will cover:
- Spend Integration Flow
- Spend Calculate
- Sample use cases
- Minimum recommended fields for the Spend Calculate API request
- Spend
- Sample use cases
- Minimum recommended fields for the Spend API request
- Spend Void
- Sample use cases
- Minimum recommended fields for the Spend Void API request
References
- Visit High-Level POS integration flow for when the Spend flow is invoked in a consumer's POS journey.
- Visit API documentation for a complete list of request and response fields along with definitions:
Spend Integration Flow
Within a consumer's purchase journey at POS, after basket items are adjudicated, the consumer can choose to spend points as tender towards the payment of the transaction. This can be done before the purchase transaction is settled. The following POS Connect APIs can be called within the Spend flow:
- Spend Calculate API call is made to adjudicate spending of points based on spend permissions, points spend rules, points balances and any points spend offers. A consumer can indicate a desired amount of points or monetary value they would like to spend within the API request. In response the API call will inform the actual amount of points that can be spent if spending of points is allowed.
Permission to spend points
Spend Calculate APIcan be made more than once if the amount of points to be spent is to be adjusted. If permission engine rules for spend do not allow for spend, for e.g. when a points account is in anEARNONLYstate, then spending of points will not be allowed regardless of the number of API calls. Therefore in this scenario, multiple API requests should be avoided.
- Spend API call is made when the consumer is happy with spend calculate results and wishes to commit the spend. Points are locked towards a pending spend transaction that can be settled later on, together with the purchase transaction. This API does not check if a consumer is allowed to spend points.
Locked PointsPoints that are "LOCKED" by this API are ready to be debited from a points account upon confirmation by the consumer. Typically the spend transaction is settled when a transaction is confirmed and payment is made. This is similar to a credit card "pre-auth" and "settle" process.
- Spend Void API call is made if the consumer changes their mind and wants to change or cancel the points committed to be spent. Void can only be performed on a pending spend transaction that is not yet settled. If a spend transaction was already settled, then points have to be credited back.
Void vs. Refund of points spentIf the spend transaction is in a status of SETTLED and not ACTIVE, then Spend Void is no longer an option. Points have to be credited back like in a refund scenario.
Spend Calculate
Use Case - Gemma wonders if she can spend 25k points
Gemma has a points balance of 25,000 points. She considers spending all of her points towards her purchase. The following Spend Calculate request and response are produced.
Expand to see request and response JSON payloads.
{
"identity": {
"identityValue": "66c3b7bda01c8756b883390dca9fbb30"
},
"location": {
"incomingIdentifier": "111",
"parentIncomingIdentifier": "AFabulousRetailer"
},
"pointsValue": 25000,
"scheme": {
"reference": "RETAILPOINTS"
}
}{
"wallet": {
"walletId": "217190201",
"friendlyName": null,
"status": "ACTIVE",
"type": "CONSUMER",
"state": "DEFAULT",
"meta": null,
"dateCreated": "2025-02-22T22:31:49+00:00",
"lastUpdated": "2025-02-22T22:31:49+00:00",
"relationships": null
},
"identity": {
"identityId": "188245110",
"walletId": "217190201",
"type": "CUSTOMER_ID",
"friendlyName": null,
"value": "66c3b7bda01c8756b883390dca9fbb30",
"safeValue": null,
"secret": null,
"dates": {
"start": "2025-02-22T22:31:49+00:00",
"end": null
},
"meta": null,
"state": "DEFAULT",
"status": "ACTIVE",
"dateCreated": "2025-02-22T22:31:49+00:00",
"lastUpdated": "2025-02-22T22:31:49+00:00",
"mobileWallet": "https://sb.uk.mypass.is/identity/142378/217190201/188245110/3950601b2edbea4619db57235155a50225bc8b11afe6da5ee6ea4fdb12ec953d"
},
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304699",
"walletId": "217190201",
"operationType": "spend",
"details": null,
"value": 20000,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T22:36:35+00:00"
}
}
Read-only API callThis is a read-only call. Data in EE AIR is not created or modified therefore events are not generated.
When a pointsValue of 25,000 is submitted in the request, spendAdjudicationResults.pointsValue in the response contains 20,000 as a suggested value of points that can be spent. This is because points can be spent at increments of 10,000 for "A Fabulous Retailer" based on scheme configuration. The response also contains 2,000 for spendAdjudicationResults.monetaryValue which indicates that 20,000 points would equate to $20.00 of value. The response also contains of 5,000 forspendAdjudicationResults.pointsRemainder which is the number of points that would remain the spend.
Minimum Recommended Fields for Spend Calculate
Below is a list of minimum recommended fields for the Wallet Spend Calculate API for a typical POS Connect integration. Refer to Wallet Spend Calculate API documentation for field definitions and additional attributes should they be required.
Request
Body
Expand to see the list of minimum recommended fields.
| Field | Recommended |
|---|---|
| identity | yes |
| identity.identityValue | yes |
| location | yes |
| location.incomingIdentifier | yes |
| location.parentIncomingIdentifier | yes |
| pointsValue | either pointsValue or monetaryValue must be provided |
| monetaryValue | either pointsValue or monetaryValue must be provided |
| scheme | yes |
| scheme.reference | yes |
Spend
Use Case - Gemma decides to spend 20k points
Now that Gemma understands that she can spend a maximum of 20,000 points out of her balance of 25,000 points, she decides to go ahead with the spend. The following Spend request and response are produced.
Expand to see request and response JSON payloads.
{
"identity": {
"identityValue": "66c3b7bda01c8756b883390dca9fbb30"
},
"location": {
"incomingIdentifier": "111",
"parentIncomingIdentifier": "AFabulousRetailer"
},
"reference": "20241103080000-111-01-1122",
"lock": true,
"parentWalletTransactionReference": "20241103080000-111-01-1121",
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304699",
"walletId": "217190201",
"operationType": "spend",
"details": null,
"value": 20000,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T22:36:35+00:00"
}
}{
"walletTransactions": [
{
"walletTransactionId": "445816981",
"parentWalletTransactionId": "445816978",
"walletId": "217190201",
"reference": "20241103080000-111-01-1122",
"transactionDateTime": "2025-02-22T22:38:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245110",
"identity": null,
"type": "SPEND",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304699",
"accountTransactionId": "8023748128"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304699",
"walletId": "217190201",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T22:36:35+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 20000,
"debit": 0,
"refund": 0,
"totalPointsTaken": 20000,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 2000
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": "111",
"storeParentId": "AFabulousRetailer"
},
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}
],
"accountTransactions": [
{
"accountTransactionId": "8023748128",
"parentAccountTransactionId": "",
"accountId": "4131304699",
"event": "LOCK",
"value": 20000,
"source": 1,
"balancesBefore": {
"current": 25000,
"lifetime": 0
},
"balancesAfter": {
"current": 25000,
"lifetime": 0
},
"transactionDetails": [],
"properties": [],
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}
]
}At this point, the following actions occur in EE AIR:
1. An ACTIVE wallet transaction of type SPEND is created and is tied to original purchase transaction of type SETTLE as a child transaction.Expand to see payload.
{
"walletTransactionId": "445816978",
"parentWalletTransactionId": "0",
"walletId": "217190201",
"reference": "20241103080000-111-01-1121",
"transactionDateTime": "2025-02-22T22:34:52+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245110",
"identity": null,
"type": "SETTLE",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304697",
"accountTransactionId": "0"
},
{
"accountId": "4131304696",
"accountTransactionId": "0"
}
],
"basket": {
"contents": null,
"summary": null,
"payment": null
},
"channel": "api",
"location": {
"storeId": null,
"storeParentId": null
},
"dateCreated": "2025-02-22T22:34:52+00:00",
"lastUpdated": "2025-02-22T22:34:52+00:00"
},
{
"walletTransactionId": "445816981",
"parentWalletTransactionId": "445816978",
"walletId": "217190201",
"reference": "20241103080000-111-01-1122",
"transactionDateTime": "2025-02-22T22:38:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245110",
"identity": null,
"type": "SPEND",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304699",
"accountTransactionId": "8023748128"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304699",
"walletId": "217190201",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T22:36:35+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 20000,
"debit": 0,
"refund": 0,
"totalPointsTaken": 20000,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 2000
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": "111",
"storeParentId": "AFabulousRetailer"
},
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}2. 1. 20,000 points are locked against this spend wallet transaction which will be debited when this transaction is settled. Expand to see payload.
{
"accountId": "4131304699",
"walletId": "217190201",
"campaignId": "1743751",
"type": "POINTS",
"clientType": "RETAILPOINTS",
"status": "ACTIVE",
"state": "LOADED",
"dates": {
"start": "2025-02-22T22:31:49+00:00",
"end": "2038-01-19T03:14:07+00:00"
},
"meta": [],
"dateCreated": "2025-02-22T22:31:49+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00",
"overrides": [],
"balances": {
"current": 25000,
"usable": 5000,
"locked": 20000,
"lifetime": 25000,
"lifetimeSpend": 0,
"lifetimeSpendValue": 0,
"pending": 0
},
"relationships": [],
"mobileWallet": "https://sb.uk.mypass.is/a/4131304699/ee114a06f9f5553"
}3. An event is generated and sent to the recipient system(s). Expand to see payload.
{
"headers": {
"eventName": "POSCONNECT.WALLET.SPEND",
"eventDate": "2025-02-22T22:38:07.004353",
"eesEnvironmentType": "sandbox-uk",
"eesSubsystemId": "pos.sandbox.uk.eagleeye.com",
"callerIp": "35.244.190.158",
"unitId": "142378",
"unitFriendlyName": "Onboarding Playground",
"clientId": "removed for security",
"clientIdFriendlyName": "api",
"eesEventId": "83b425d9-c264-4e65-9d3d-4d9d483cccfb",
"eesMasterEventId": "Z7pRz4eoklKfZi6DfI0RLQAAAmo",
"externalMessageId": null,
"eesApiVersion": "7.6"
},
"request": {
"resource": "/connect/wallet/spend/spend",
"method": "POST",
"body": "{\n \"identity\": {\n \"identityValue\": \"66c3b7bda01c8756b883390dca9fbb30\"\n },\n \"location\": {\n \"incomingIdentifier\": \"111\",\n \"parentIncomingIdentifier\": \"AFabulousRetailer\"\n },\n \"reference\": \"20241103080000-111-01-1122\",\n \"lock\": true,\n \"parentWalletTransactionReference\": \"20241103080000-111-01-1121\",\n \"spendAdjudicationResults\": {\n \"pointsValue\": 20000,\n \"pointsRemainder\": 5000,\n \"monetaryValue\": 2000,\n \"balanceAfter\": {\n \"current\": 5000,\n \"usable\": 5000,\n \"locked\": 0,\n \"lifetime\": 25000,\n \"lifetimeSpend\": 20000,\n \"lifetimeSpendValue\": 2000,\n \"pending\": 0\n },\n \"appliedTier\": {\n \"bonus\": 0,\n \"ceiling\": 500000,\n \"floor\": 10000,\n \"pointsBack\": 0,\n \"rate\": 0.1,\n \"step\": 10000\n },\n \"operations\": [\n {\n \"resourceType\": \"SCHEME\",\n \"resourceId\": \"1743751\",\n \"accountId\": \"4131304699\",\n \"walletId\": \"217190201\",\n \"operationType\": \"spend\",\n \"details\": null,\n \"value\": 20000,\n \"balances\": {\n \"current\": 20000,\n \"lifetime_spend\": 20000,\n \"lifetime_spend_value\": 2000\n }\n }\n ],\n \"analysedDateTime\": \"2025-02-22T22:36:35+00:00\"\n }\n}",
"contentType": "application/json",
"customHeaders": []
},
"response": {
"code": 200,
"body": "{\"walletTransactions\":[{\"walletTransactionId\":\"445816981\",\"parentWalletTransactionId\":\"445816978\",\"walletId\":\"217190201\",\"reference\":\"20241103080000-111-01-1122\",\"transactionDateTime\":\"2025-02-22T22:38:07+00:00\",\"transactionDateTimeOffset\":\"+00:00\",\"identityId\":\"188245110\",\"identity\":null,\"type\":\"SPEND\",\"status\":\"ACTIVE\",\"meta\":null,\"state\":\"ORIGINAL\",\"expiryDate\":null,\"accounts\":[{\"accountId\":\"4131304699\",\"accountTransactionId\":\"8023748128\"}],\"basket\":{\"contents\":null,\"summary\":{\"totalItems\":null,\"totalBasketValue\":null,\"totalQualifyingAmount\":null,\"totalDiscountAmount\":null,\"totalTaxAmount\":null,\"fulfilledBaseEarn\":null,\"expectedPoints\":null,\"originalQualifiedAccounts\":null,\"spendAdjudicationResults\":{\"pointsValue\":20000,\"pointsRemainder\":5000,\"monetaryValue\":2000,\"balanceAfter\":{\"current\":5000,\"usable\":5000,\"locked\":0,\"lifetime\":25000,\"lifetimeSpend\":20000,\"lifetimeSpendValue\":2000,\"pending\":0},\"appliedTier\":{\"bonus\":0,\"ceiling\":500000,\"floor\":10000,\"pointsBack\":0,\"rate\":0.1,\"step\":10000},\"operations\":[{\"resourceType\":\"SCHEME\",\"resourceId\":\"1743751\",\"accountId\":\"4131304699\",\"walletId\":\"217190201\",\"operationType\":\"spend\",\"value\":20000,\"details\":null,\"balances\":{\"current\":20000,\"lifetime_spend\":20000,\"lifetime_spend_value\":2000}}],\"analysedDateTime\":\"2025-02-22T22:36:35+00:00\",\"excludedProducts\":[]},\"results\":{\"points\":{\"spend\":20000,\"debit\":0,\"refund\":0,\"totalPointsTaken\":20000,\"earn\":0,\"credit\":0,\"totalPointsGiven\":0,\"totalMonetaryValue\":2000},\"pointsByScheme\":null,\"tiers\":null},\"qualifiesResults\":null,\"reporting\":null,\"tierMembershipResults\":null,\"redemptionChannel\":null,\"adjudicationResults\":null,\"adjustmentResults\":null,\"bounceBackResults\":null,\"tenderResults\":null,\"adjustmentRules\":null},\"payment\":null},\"channel\":\"api\",\"location\":{\"storeId\":\"111\",\"storeParentId\":\"AFabulousRetailer\"},\"dateCreated\":\"2025-02-22T22:38:07+00:00\",\"lastUpdated\":\"2025-02-22T22:38:07+00:00\"}],\"accountTransactions\":[{\"accountTransactionId\":\"8023748128\",\"parentAccountTransactionId\":\"\",\"accountId\":\"4131304699\",\"event\":\"LOCK\",\"value\":20000,\"source\":1,\"balancesBefore\":{\"current\":25000,\"lifetime\":0},\"balancesAfter\":{\"current\":25000,\"lifetime\":0},\"transactionDetails\":[],\"properties\":[],\"dateCreated\":\"2025-02-22T22:38:07+00:00\",\"lastUpdated\":\"2025-02-22T22:38:07+00:00\"}]}",
"contentType": "application/json;charset=utf-8"
},
"atomicOperations": [
{
"objectType": "walletTransactionEntity",
"operationType": "CREATE",
"objectValue": {
"walletTransactionId": "445816981",
"parentWalletTransactionId": "0",
"walletId": "217190201",
"reference": "20241103080000-111-01-1122",
"transactionDateTime": "2025-02-22T22:38:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245110",
"identity": null,
"type": "SPEND",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [],
"basket": {
"contents": null,
"summary": null,
"payment": null
},
"channel": "api",
"location": {
"storeId": "111",
"storeParentId": "AFabulousRetailer"
},
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}
},
{
"objectType": "walletAccountTransactionEntity",
"operationType": "UPDATE",
"objectValue": {
"accountTransactionId": "8023748128",
"parentAccountTransactionId": null,
"accountId": "4131304699",
"account": {
"accountId": "4131304699",
"walletId": "217190201",
"campaignId": "1743751",
"type": "POINTS",
"clientType": "RETAILPOINTS",
"status": "ACTIVE",
"state": "LOADED",
"dates": {
"start": "2025-02-22T22:31:49+00:00",
"end": "2038-01-19T03:14:07+00:00"
},
"meta": [],
"dateCreated": "2025-02-22T22:31:49+00:00",
"lastUpdated": "2025-02-22T22:34:36+00:00",
"overrides": [],
"balances": {
"current": 25000,
"usable": 25000,
"lifetime": 25000,
"pending": 0,
"locked": 0,
"lifetimeSpend": 0,
"lifetimeSpendValue": 0
},
"relationships": [],
"mobileWallet": "https://sb.uk.mypass.is/a/4131304699/ee114a06f9f5553"
},
"event": "LOCK",
"value": 20000,
"source": 1,
"balancesBefore": {
"current": 25000,
"lifetime": 0
},
"balancesAfter": {
"current": 25000,
"lifetime": 0
},
"transactionDetails": [],
"properties": [],
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}
},
{
"objectType": "walletTransactionEntity",
"operationType": "UPDATE",
"objectValue": {
"walletTransactionId": "445816981",
"parentWalletTransactionId": "445816978",
"walletId": "217190201",
"reference": "20241103080000-111-01-1122",
"transactionDateTime": "2025-02-22T22:38:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245110",
"identity": null,
"type": "SPEND",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304699",
"accountTransactionId": "8023748128"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304699",
"walletId": "217190201",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T22:36:35+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 20000,
"debit": 0,
"refund": 0,
"totalPointsTaken": 20000,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 2000
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": "111",
"storeParentId": "AFabulousRetailer"
},
"dateCreated": "2025-02-22T22:38:07+00:00",
"lastUpdated": "2025-02-22T22:38:07+00:00"
}
}
]
}
Reduction of Points SpentPoints will continue to remain LOCKED against an ACTIVE wallet transaction of type SPEND until Wallet Settle API is called. Upon Settle, locked points are reduced from the current balance of the points account and
SPENDaccount transaction is performed. Refer to Spend with Settle for more details.
Minimum Recommended Fields for Spend
Below is a list of minimum recommended fields for the Wallet Spend API for a typical POS Connect integration. Refer to Wallet Spend API documentation for field definitions and additional attributes should they be required.
Wallet Transaction Reference
referencefor each wallet transaction should should be a unique string. It is recommended to populate this string using<YYYYMMDDHHMMS>-<storeNo>-<laneNumber>-<transactionNo>for e.g.20241103080000-111-01-1111so that a transaction can easily be tracked back to it's source for troubleshooting an issue.
Request
Body
Expand to see the list of minimum recommended fields.
| Field | Recommended |
|---|---|
| identity | yes |
| identity.identityValue | yes |
| location | yes |
| location.incomingIdentifier | yes |
| location.parentIncomingIdentifier | yes |
| reference | yes |
| spendAdjudicationResults | Map spendAdjudicationResults block from Spend Calculate API response |
Spend Void
Example: Gemma changes her mind
Soon after confirming to spend 20,000 points, Gemma has second thoughts. She thinks to herself, "What if I use these points to buy my favourite brand name perfume when there is a points spend promotion in the future and my points would be worth a higher monetary value?!". Since Gemma's SPEND transaction is still ACTIVE, Spend Void API call is made with the following request and response payloads.
Expand to see request and response JSON payloads.
{
"identity": {
"identityValue": "9a846dc8d0810688330b8832ae93be39"
},
"reference": "20241103080000-111-01-1124"
}{
"walletTransactions": [
{
"walletTransactionId": "445816989",
"parentWalletTransactionId": "0",
"walletId": "217190215",
"reference": "20241103080000-111-01-1124",
"transactionDateTime": "2025-02-22T23:05:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245136",
"identity": null,
"type": "SPEND",
"status": "VOIDED",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304835",
"accountTransactionId": "8023748796"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304835",
"walletId": "217190215",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T23:04:25+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 0,
"debit": 0,
"refund": 0,
"totalPointsTaken": 0,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 0
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": null,
"storeParentId": null
},
"dateCreated": "2025-02-22T23:05:08+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}
],
"accountTransactions": [
{
"accountTransactionId": "8023748796",
"parentAccountTransactionId": "8023748795",
"accountId": "4131304835",
"account": {
"accountId": "4131304835",
"walletId": "217190215",
"campaignId": "1743751",
"type": "POINTS",
"clientType": "RETAILPOINTS",
"status": "ACTIVE",
"state": "LOADED",
"dates": {
"start": "2025-02-22T23:03:19+00:00",
"end": "2038-01-19T03:14:07+00:00"
},
"meta": null,
"dateCreated": "2025-02-22T23:03:19+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00",
"overrides": [],
"balances": {
"current": 25000,
"usable": 25000,
"locked": 0,
"lifetime": 25000,
"pending": 0,
"lifetimeSpend": 0,
"lifetimeSpendValue": 0
},
"relationships": null,
"mobileWallet": "https://sb.uk.mypass.is/a/4131304835/78d320ebb37961e"
},
"event": "VOID",
"value": 20000,
"source": 1,
"balancesBefore": {
"current": 25000,
"lifetime": 0
},
"balancesAfter": {
"current": 25000,
"lifetime": 0
},
"transactionDetails": [],
"properties": [],
"dateCreated": "2025-02-22T23:05:30+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}
]
}At this point, the following actions occur in EE AIR:
1. An ACTIVE spend wallet transaction is VOIDED. Expand to see JSON payload.
{
"walletTransactionId": "445816989",
"parentWalletTransactionId": "0",
"walletId": "217190215",
"reference": "20241103080000-111-01-1124",
"transactionDateTime": "2025-02-22T23:05:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245136",
"identity": null,
"type": "SPEND",
"status": "VOIDED",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304835",
"accountTransactionId": "8023748796"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304835",
"walletId": "217190215",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T23:04:25+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 0,
"debit": 0,
"refund": 0,
"totalPointsTaken": 0,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 0
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": "111",
"storeParentId": "AFabulousRetailer"
},
"dateCreated": "2025-02-22T23:05:08+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}2. 20,000 points are unlocked in the points account and made available to be spent. Expand to see JSON payload.
{
"accountId": "4131304835",
"walletId": "217190215",
"campaignId": "1743751",
"type": "POINTS",
"clientType": "RETAILPOINTS",
"status": "ACTIVE",
"state": "LOADED",
"dates": {
"start": "2025-02-22T23:03:19+00:00",
"end": "2038-01-19T03:14:07+00:00"
},
"meta": [],
"dateCreated": "2025-02-22T23:03:19+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00",
"overrides": [],
"balances": {
"current": 25000,
"usable": 25000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 0,
"lifetimeSpendValue": 0,
"pending": 0
},
"relationships": [],
"mobileWallet": "https://sb.uk.mypass.is/a/4131304835/78d320ebb37961e"
}3. An event is generated and sent to the recipient system(s). Expand to see JSON payload.
{
"headers": {
"eventName": "POSCONNECT.WALLET.SPEND.VOID",
"eventDate": "2025-02-22T23:05:30.265391",
"eesEnvironmentType": "sandbox-uk",
"eesSubsystemId": "pos.sandbox.uk.eagleeye.com",
"callerIp": "35.244.190.158",
"unitId": "142378",
"unitFriendlyName": "Onboarding Playground",
"clientId": "removed for security",
"clientIdFriendlyName": "api",
"eesEventId": "c66e4498-59dd-4160-91c6-e96a6ffd15c6",
"eesMasterEventId": "Z7pYOgJPsoTH794ZU2n_AAAAAMU",
"externalMessageId": null,
"eesApiVersion": "7.6"
},
"request": {
"resource": "/connect/wallet/spend/void",
"method": "POST",
"body": "{\n \"identity\": {\n \"identityValue\": \"9a846dc8d0810688330b8832ae93be39\"\n },\n \"reference\": \"20241103080000-111-01-1124\"\n}",
"contentType": "application/json",
"customHeaders": []
},
"response": {
"code": 200,
"body": "{\"walletTransactions\":[{\"walletTransactionId\":\"445816989\",\"parentWalletTransactionId\":\"0\",\"walletId\":\"217190215\",\"reference\":\"20241103080000-111-01-1124\",\"transactionDateTime\":\"2025-02-22T23:05:07+00:00\",\"transactionDateTimeOffset\":\"+00:00\",\"identityId\":\"188245136\",\"identity\":null,\"type\":\"SPEND\",\"status\":\"VOIDED\",\"meta\":null,\"state\":\"ORIGINAL\",\"expiryDate\":null,\"accounts\":[{\"accountId\":\"4131304835\",\"accountTransactionId\":\"8023748796\"}],\"basket\":{\"contents\":null,\"summary\":{\"totalItems\":null,\"totalBasketValue\":null,\"totalQualifyingAmount\":null,\"totalDiscountAmount\":null,\"totalTaxAmount\":null,\"fulfilledBaseEarn\":null,\"expectedPoints\":null,\"originalQualifiedAccounts\":null,\"spendAdjudicationResults\":{\"pointsValue\":20000,\"pointsRemainder\":5000,\"monetaryValue\":2000,\"balanceAfter\":{\"current\":5000,\"usable\":5000,\"locked\":0,\"lifetime\":25000,\"lifetimeSpend\":20000,\"lifetimeSpendValue\":2000,\"pending\":0},\"appliedTier\":{\"bonus\":0,\"ceiling\":500000,\"floor\":10000,\"pointsBack\":0,\"rate\":0.1,\"step\":10000},\"operations\":[{\"resourceType\":\"SCHEME\",\"resourceId\":\"1743751\",\"accountId\":\"4131304835\",\"walletId\":\"217190215\",\"operationType\":\"spend\",\"value\":20000,\"details\":null,\"balances\":{\"current\":20000,\"lifetime_spend\":20000,\"lifetime_spend_value\":2000}}],\"analysedDateTime\":\"2025-02-22T23:04:25+00:00\",\"excludedProducts\":[]},\"results\":{\"points\":{\"spend\":0,\"debit\":0,\"refund\":0,\"totalPointsTaken\":0,\"earn\":0,\"credit\":0,\"totalPointsGiven\":0,\"totalMonetaryValue\":0},\"pointsByScheme\":null,\"tiers\":null},\"qualifiesResults\":null,\"reporting\":null,\"tierMembershipResults\":null,\"redemptionChannel\":null,\"adjudicationResults\":null,\"adjustmentResults\":null,\"bounceBackResults\":null,\"tenderResults\":null,\"adjustmentRules\":null},\"payment\":null},\"channel\":\"api\",\"location\":{\"storeId\":null,\"storeParentId\":null},\"dateCreated\":\"2025-02-22T23:05:08+00:00\",\"lastUpdated\":\"2025-02-22T23:05:30+00:00\"}],\"accountTransactions\":[{\"accountTransactionId\":\"8023748796\",\"parentAccountTransactionId\":\"8023748795\",\"accountId\":\"4131304835\",\"account\":{\"accountId\":\"4131304835\",\"walletId\":\"217190215\",\"campaignId\":\"1743751\",\"type\":\"POINTS\",\"clientType\":\"RETAILPOINTS\",\"status\":\"ACTIVE\",\"state\":\"LOADED\",\"dates\":{\"start\":\"2025-02-22T23:03:19+00:00\",\"end\":\"2038-01-19T03:14:07+00:00\"},\"meta\":null,\"dateCreated\":\"2025-02-22T23:03:19+00:00\",\"lastUpdated\":\"2025-02-22T23:05:30+00:00\",\"overrides\":[],\"balances\":{\"current\":25000,\"usable\":25000,\"locked\":0,\"lifetime\":25000,\"pending\":0,\"lifetimeSpend\":0,\"lifetimeSpendValue\":0},\"relationships\":null,\"mobileWallet\":\"https:\\/\\/sb.uk.mypass.is\\/a\\/4131304835\\/78d320ebb37961e\"},\"event\":\"VOID\",\"value\":20000,\"source\":1,\"balancesBefore\":{\"current\":25000,\"lifetime\":0},\"balancesAfter\":{\"current\":25000,\"lifetime\":0},\"transactionDetails\":[],\"properties\":[],\"dateCreated\":\"2025-02-22T23:05:30+00:00\",\"lastUpdated\":\"2025-02-22T23:05:30+00:00\"}]}",
"contentType": "application/json;charset=utf-8"
},
"atomicOperations": [
{
"objectType": "walletAccountTransactionEntity",
"operationType": "UPDATE",
"objectValue": {
"accountTransactionId": "8023748796",
"parentAccountTransactionId": "8023748795",
"accountId": "4131304835",
"account": {
"accountId": "4131304835",
"walletId": "217190215",
"campaignId": "1743751",
"type": "POINTS",
"clientType": "RETAILPOINTS",
"status": "ACTIVE",
"state": "LOADED",
"dates": {
"start": "2025-02-22T23:03:19+00:00",
"end": "2038-01-19T03:14:07+00:00"
},
"meta": [],
"dateCreated": "2025-02-22T23:03:19+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00",
"overrides": [],
"balances": {
"current": 25000,
"usable": 25000,
"locked": 0,
"lifetime": 25000,
"pending": 0,
"lifetimeSpend": 0,
"lifetimeSpendValue": 0
},
"relationships": [],
"mobileWallet": "https://sb.uk.mypass.is/a/4131304835/78d320ebb37961e"
},
"event": "VOID",
"value": 20000,
"source": 1,
"balancesBefore": {
"current": 25000,
"lifetime": 0
},
"balancesAfter": {
"current": 25000,
"lifetime": 0
},
"transactionDetails": [],
"properties": [],
"dateCreated": "2025-02-22T23:05:30+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}
},
{
"objectType": "walletTransactionEntity",
"operationType": "UPDATE",
"objectValue": {
"walletTransactionId": "445816989",
"parentWalletTransactionId": "0",
"walletId": "217190215",
"reference": "20241103080000-111-01-1124",
"transactionDateTime": "2025-02-22T23:05:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245136",
"identity": null,
"type": "SPEND",
"status": "ACTIVE",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304835",
"accountTransactionId": "8023748795"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304835",
"walletId": "217190215",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T23:04:25+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 0,
"debit": 0,
"refund": 0,
"totalPointsTaken": 0,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 0
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": null,
"storeParentId": null
},
"dateCreated": "2025-02-22T23:05:08+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}
},
{
"objectType": "walletTransactionEntity",
"operationType": "UPDATE",
"objectValue": {
"walletTransactionId": "445816989",
"parentWalletTransactionId": "0",
"walletId": "217190215",
"reference": "20241103080000-111-01-1124",
"transactionDateTime": "2025-02-22T23:05:07+00:00",
"transactionDateTimeOffset": "+00:00",
"identityId": "188245136",
"identity": null,
"type": "SPEND",
"status": "VOIDED",
"meta": null,
"state": "ORIGINAL",
"expiryDate": null,
"accounts": [
{
"accountId": "4131304835",
"accountTransactionId": "8023748796"
}
],
"basket": {
"contents": null,
"summary": {
"totalItems": null,
"totalBasketValue": null,
"totalQualifyingAmount": null,
"totalDiscountAmount": null,
"totalTaxAmount": null,
"fulfilledBaseEarn": null,
"expectedPoints": null,
"originalQualifiedAccounts": null,
"spendAdjudicationResults": {
"pointsValue": 20000,
"pointsRemainder": 5000,
"monetaryValue": 2000,
"balanceAfter": {
"current": 5000,
"usable": 5000,
"locked": 0,
"lifetime": 25000,
"lifetimeSpend": 20000,
"lifetimeSpendValue": 2000,
"pending": 0
},
"appliedTier": {
"bonus": 0,
"ceiling": 500000,
"floor": 10000,
"pointsBack": 0,
"rate": 0.1,
"step": 10000
},
"operations": [
{
"resourceType": "SCHEME",
"resourceId": "1743751",
"accountId": "4131304835",
"walletId": "217190215",
"operationType": "spend",
"value": 20000,
"details": null,
"balances": {
"current": 20000,
"lifetime_spend": 20000,
"lifetime_spend_value": 2000
}
}
],
"analysedDateTime": "2025-02-22T23:04:25+00:00",
"excludedProducts": []
},
"results": {
"points": {
"spend": 0,
"debit": 0,
"refund": 0,
"totalPointsTaken": 0,
"earn": 0,
"credit": 0,
"totalPointsGiven": 0,
"totalMonetaryValue": 0
},
"pointsByScheme": null,
"tiers": null
},
"qualifiesResults": null,
"reporting": null,
"tierMembershipResults": null,
"redemptionChannel": null,
"adjudicationResults": null,
"adjustmentResults": null,
"bounceBackResults": null,
"tenderResults": null,
"adjustmentRules": null
},
"payment": null
},
"channel": "api",
"location": {
"storeId": null,
"storeParentId": null
},
"dateCreated": "2025-02-22T23:05:08+00:00",
"lastUpdated": "2025-02-22T23:05:30+00:00"
}
}
]
}Minimum Recommended Fields for Spend Void
Below is a list of minimum recommended fields for the Wallet Spend Void API for a typical POS Connect integration. Refer to Spend Void API documentation for field definitions and additional attributes should they be required.
Body
Expand to see the list of minimum recommended fields.
| Field | Recommended |
|---|---|
| identity | yes |
| identity.identityValue | yes |
| reference | yes |
Updated about 4 hours ago
What’s Next
Visit the below pages to learn about:
- High level POS Connect integration
- Adjudication using POS Connect
- Settle a POS Connect transaction