Identify (POST) - Rewards
Use Case: Successfully identify the loyalty user along with any potential rewards/offers that they had pre-selected within the app.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/identify
Variation: Contents
| Table of Contents | ||
|---|---|---|
|
Overview
This document explains how Loyalty API endpoints must be used with Reward combos for NCR point of sale system.
Identify
When a guest scans an identification code on a POS or Kiosk, they may pre-select offers or rewards. For Rewards, NCR expects use to provide them w/ a new field called eligibleDiscounts that tells their system which item needs to be marked as free. NOTE
| Info |
|---|
Note: This field is completely optional, it helps the cashier register a reward at an earlier step, but we can still provide this property for any of the subsequent update calls. |
...
Example Request
...
| Code Block |
|---|
{
"identifier": "$digitCode or $loyaltyId",
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
} |
...
Example Response
...
| Code Block |
|---|
{
"balances": [
{
"amount": 14464,
"currency": "points"
}
],
"eligibleDiscounts": [
{
"details": {
"displayName": "some display name",
"type": "REWARD or OFFER"
},
"productId": "$benefitPlu",
"referenceId": "$loyaltyIncentiveId"
}
],
"loyaltyUser": {
"created": "2021-08-10T12:18:39.180Z",
"id": "$loyaltyUserId",
"name": "$loyaltyUserName"
},
"order": [
{
"name": "Whopper",
"productId": "$incentivePlu",
"referenceId": "00"
}
],
"transactionId": "$loyaltyTransactionId"
} |
Transaction Update (PUT) - Pending - Rewards / Upsize
Use Case: POS sends this transaction request with the order details to update the loyalty transaction. If the POS states this transaction should be claimed, this will result in the user earning and redeeming eligible points.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}
...
: "$loyaltyTransactionId"
} |
Update (Pending)
NCR will call us w/ two update calls. The first one will send a status of PENDING. This first call will have appliedDiscounts with no referenceId (engine id which will later use to apply the discount on our side). If the user pre-selected a reward prior to identifying OR the cart contains an upsize plu, NCR expects us to return an eligibleDiscounts field that points to the entry being discounted, the pointer used is the orderReferenceId. The orderReferenceId must match the referenceId of the cart entry that needs to be discounted from the request body.
For combos, NCR will provide all the combo slots in the appliedDiscounts array. Each entry will have a comboId (the combo document plu) and comboInstanceId which will be unique identifier for us to group all of the slots for one particular combo entry.
Expected Request
...
| Code Block |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serivceMode",
"status": "PENDING",
"transactionDetails": {
"currency": "USD",
"appliedDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": ""
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": ""
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": ""
},
{
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"comboInstanceId": "$uniqueIdPerCombo",
"comboId": "$comboPlu",
"orderReferenceId": "4",
"productId": "400102",
"referenceId": ""
}
],
"order": [
{
"name": "Meal selection",
"price": 0,
"productId": "9088",
"productType": "product",
"quantity": 1,
"referenceId": "6",
"tax": 0
},
{
"name": "WHOPPER",
"price": 6.49,
"productId": "110",
"productType": "product",
"quantity": 1,
"referenceId": "7",
"tax": 0
},
{
"name": "REGULAR FRIES ML",
"price": 2.39,
"productId": "713",
"productType": "product",
"quantity": 1,
"referenceId": "8",
"tax": 0
},
{
"name": "REGULAR COKE",
"price": 2.82,
"productId": "400102",
"productType": "product",
"quantity": 1,
"referenceId": "9",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CREDIT",
"ccToken": "$panToken"
},
{
"amount": 400,
"type": "CASH"
},
{
"amount": 1000,
"type": "SUBTOTAL"
},
{
"amount": 300,
"type": "DISCOUNTS"
},
{
"amount": 200,
"type": "TAXES"
}
],
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
},
"transactionId": "$loyaltyTransactionId"
} |
Expected Response
...
| Code Block |
|---|
{
"eligibleDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"points": 102220,
"pointsEarned": 5000,
"pointsRedeemed": 0,
"loyaltyId": "$loyaltyUserId",
"presentation": {
"footer": "Crowns expire 180 days from last purchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms",
"header": "Royal Perks",
"identifier": "Transaction ID: $loyaltyTransactionId-terms",
"pointsEarnedheader": "Earned:Royal 5000Perks",
"totalPointsidentifier": "BalanceTransaction ID: 102220$loyaltyTransactionId",
}, "receiptCodepointsEarned": "J25QL1WAH5KJ7P75Earned: 5000",
"transactionId": "$loyaltyTransactionId"
} |
Transaction Update (PUT) - Claim / Commit - Rewards / Upsize
Use Case: POS sends this transaction request with the order details to update the loyalty transaction. If the POS states this transaction should be claimed, this will result in the user earning and redeeming eligible points.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}
...
totalPoints": "Balance: 102220"
},
"receiptCode": "J25QL1WAH5KJ7P75",
"transactionId": "$loyaltyTransactionId"
} |
Update (Claimed)
NCR will call us w/ two update calls. The second call will send a status of CLAIMED which will include any appliedDiscounts for rewards / upsizes that was given to the user. Unlike the first call, these entries will contain a referenceId for us to reconcile with the customer’s preselected rewards.
Expected Request
...
| Code Block |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serivceMode",
"status": "PENDING",
"transactionDetails": {
"currency": "USD",
"appliedDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"order": [
{
"name": "Meal selection",
"price": 0,
"productId": "9088",
"productType": "product",
"quantity": 1,
"referenceId": "6",
"tax": 0
},
{
"name": "WHOPPER",
"price": 6.49,
"productId": "110",
"productType": "product",
"quantity": 1,
"referenceId": "7",
"tax": 0
},
{
"name": "REGULAR FRIES ML",
"price": 2.39,
"productId": "713",
"productType": "product",
"quantity": 1,
"referenceId": "8",
"tax": 0
},
{
"name": "REGULAR COKE",
"price": 2.82,
"productId": "400102",
"productType": "product",
"quantity": 1,
"referenceId": "9",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CREDIT",
"ccToken": "$panToken"
},
{
"amount": 400,
"type": "CASH"
},
{
"amount": 1000,
"type": "SUBTOTAL"
},
{
"amount": 300,
"type": "DISCOUNTS"
},
{
"amount": 200,
"type": "TAXES"
}
],
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
},
"transactionId": "$loyaltyTransactionId"
} |
Expected Response
...
| Code Block |
|---|
{
"eligibleDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"points": 102220,
"pointsEarned": 5000,
"pointsRedeemed": 0,
"loyaltyId": "$loyaltyUserId",
"presentation": {
"footer": "Crowns expire 180 days from last purchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms",
"header": "Royal Perks",
"identifier": "Transaction ID: $loyaltyTransactionId",
"pointsEarned": "Earned: 5000",
"totalPoints": "Balance: 102220"
},
"receiptCode": "J25QL1WAH5KJ7P75",
"transactionId": "$loyaltyTransactionId"
} |
...