📌 Purpose

Personal Reward Banks allow you to target offers or rewards to individual customers. In this setup, rewards are only available to a specific wallet after a link is created, using the Create Link API. Once linked, customers can redeem their points for a reward via the Exchange API.

🖼 Recipe Overview

This recipe covers how to:

Link a personal reward bank to an individual customer’s wallet
Retrieve the reward ID available for exchange
Execute a points-to-coupon exchange using the appropriate API

Once complete, your customer will have a reward coupon issued in exchange for points.

📋 Prerequisites

Eagle Eye API credentials
An active company unit with 3-level hierarchy
A wallet (walletId) with an active loyalty points account
A points-enabled scheme
A personal reward bank set to mode: PERSONAL

📤 Outputs

After completing this recipe, capture the following output:

Output Name	Purpose
walletTransactionId	Unique reference for the wallet transaction used to locate a transaction
accountTransactionId	Used to reference the specific movement of points and coupon issue
pointsRewardBankWalletLinkId	Used to identify for the wallet-specific reward link

📒 Steps

Step 1: Setup the Personal Reward Bank Link

A link must be present in the wallet before a customer can access a reward from a personal reward bank.

1.1 Use the following default values for your link create request body:
- status: ACTIVE
- type: CAMPAIGN
- state: LOADED
1.2 Select validFrom (start) and validTo (end) dates to define when the link will be active in the wallet

Step 2: Call POST /wallet/{walletId}/link/bank/pointsreward/{rewardBankId}

{
	"status": "ACTIVE",
	"type": "CAMPAIGN",
	"state": "LOADED",
	"validFrom": "2025-06-22T00:00:00+00:00",
	"validTo": "2025-06-28T23:59:59+00:00"
}

{
	"pointsRewardBankWalletLinkId": "98855",
	"walletId": "241998582",
	"pointsRewardBankId": "84593",
	"pointsRewardBankRewardId": null,
	"status": "ACTIVE",
	"state": "LOADED",
	"type": "CAMPAIGN",
	"validFrom": "2025-06-22T00:00:00+00:00",
	"validTo": "2025-06-28T23:59:59+00:00",
	"dateCreated": "2025-06-23T12:50:00+00:00",
	"lastUpdated": "2025-06-23T12:50:00+00:00"
}

Step 3: Retrieve Available Rewards using GET /banks/pointsreward/{rewardBankId}/rewards

Retrieve the list of available rewards tied to the reward bank. You will need the pointsRewardBankRewardId for the next step.

{
	"total": 1,
	"orderBy": [
		{
			"name": "pointsRewardBankRewardId",
			"order": "ASC"
		}
	],
	"limit": 100,
	"offset": 0,
	"results": [
		{
			"pointsRewardBankRewardId": "186253",
			"pointsRewardBankId": "84593",
			"resourceType": "CAMPAIGN",
			"resourceId": "101161514",
			"threshold": 2000,
			"cost": 2000,
			"status": "ACTIVE",
			"dateCreated": "2025-06-18T16:42:05+00:00",
			"lastUpdated": "2025-06-18T16:42:05+00:00",
			"reasonCode": null
		}
	]
}

Step 4: Prepare the Exchange payload

Now that a link is available for the personal reward bank in the wallet, the following steps will allow the customer to exchange the required points for the reward in the bank. Ensure the points account in wallet has an available balance to cover the cost of the exchange (see the results.cost from step 3 for the number of points required).

4.1 Input the wallet's points accountId in the request, along with the pointsRewardBankId and the pointsRewardBankRewardId from step 3

Step 5: Call POST /services/wallet/{walletId}/transaction/exchange/pointsreward

{
    "accountId": "4457858125",
    "pointsRewardBankId": "84593",
    "pointsRewardBankRewardId": "186253"
}

{
	"walletTransactionId": "480330887",
	"parentWalletTransactionId": "0",
	"walletId": "241998582",
	"reference": "EXCHANGE_6855cd4f7daa09.70750952",
	"transactionDateTime": "2025-06-20T21:06:23+00:00",
	"transactionDateTimeOffset": "+00:00",
	"identityId": null,
	"identity": null,
	"type": "EXCHANGE",
	"status": "SETTLED",
	"meta": null,
	"state": "ORIGINAL",
	"expiryDate": null,
	"accounts": [
		{
			"accountTransactionId": "8763645343",
			"parentAccountTransactionId": "",
			"accountId": "4457858125",
			"account": {
				"accountId": "4457858125",
				"walletId": "241998582",
				"campaignId": "101159001",
				"type": "POINTS",
				"clientType": "RETAILPOINTS",
				"status": "ACTIVE",
				"state": "EARNBURN",
				"dates": {
					"start": "2025-06-20T21:04:58+00:00",
					"end": "2038-01-19T03:14:07+00:00"
				},
				"meta": [],
				"dateCreated": "2025-06-20T21:04:58+00:00",
				"lastUpdated": "2025-06-20T21:06:23+00:00",
				"overrides": [],
				"balances": {
					"current": 10500,
					"usable": 10500,
					"lifetime": 12500,
					"pending": 0,
					"locked": 0,
					"lifetimeSpend": 0,
					"lifetimeSpendValue": 0
				},
				"relationships": [],
				"mobileWallet": "https://sb.uk.mypass.is/a/4457858125/a032e3455108fcd"
			},
			"event": "EXCHANGE",
			"value": 2000,
			"source": 1,
			"balancesBefore": {
				"current": 12500,
				"lifetime": 0
			},
			"balancesAfter": {
				"current": 10500,
				"lifetime": 0
			},
			"transactionDetails": {
				"pointsRewardBankId": 84593,
				"pointsRewardBankRewardId": 186253,
				"rewardBankLoyaltyPointsBankId": 84593
			},
			"properties": [],
			"dateCreated": "2025-06-20T21:06:23+00:00",
			"lastUpdated": "2025-06-20T21:06:23+00:00"
		},
		{
			"accountTransactionId": "8763645344",
			"parentAccountTransactionId": "8763645343",
			"accountId": "4457858132",
			"account": {
				"accountId": "4457858132",
				"walletId": "241998582",
				"campaignId": "101161514",
				"type": "ECOUPON",
				"clientType": "OFFER",
				"status": "ACTIVE",
				"state": "UNLOADED",
				"dates": {
					"start": "2025-06-20T21:06:23+00:00",
					"end": "2025-07-04T23:59:59+00:00"
				},
				"meta": [],
				"dateCreated": "2025-06-20T21:06:23+00:00",
				"lastUpdated": "2025-06-20T21:06:23+00:00",
				"overrides": [],
				"balances": {
					"available": 0,
					"refundable": 0
				},
				"relationships": {
					"LOYALTY_POINTS_REWARD_OF": {
						"POINTS": [
							{
								"accountId": "4457858125",
								"dateCreated": "2025-06-20T21:06:23+00:00"
							}
						]
					}
				},
				"mobileWallet": "https://sb.uk.mypass.is/a/4457858132/9dd6d019806cb87"
			},
			"event": "CREATE",
			"value": 0,
			"source": 1,
			"balancesBefore": {
				"available": 0,
				"refundable": 0
			},
			"balancesAfter": {
				"available": 0,
				"refundable": 0
			},
			"transactionDetails": [],
			"properties": [],
			"dateCreated": "2025-06-20T21:06:23+00:00",
			"lastUpdated": "2025-06-20T21:06:23+00:00"
		}
	],
	"basket": {
		"contents": null,
		"summary": null,
		"payment": null
	},
	"channel": "api",
	"location": {
		"storeId": null,
		"storeParentId": null
	},
	"dateCreated": "2025-06-20T21:06:23+00:00",
	"lastUpdated": "2025-06-20T21:06:23+00:00"
}

✅ Business Readiness Checklist

Use these steps to validate the setup of your wallet and accounts:

Call GET /wallet/{walletId}/bank/pointsreward/links/available to check for the personal link in the wallet.
Confirm the coupon account was created using GET wallet/{walletId}/account/{accountId}.

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
Coupon not issued	Ensure the reward bank and campaign reward are active
Exchange rejected	Confirm that the customer’s points balance meets or exceeds the reward cost
Customer exceeds issuance limit	Review any reward bank exchange caps and ensure the wallet is not already holding a similar coupon