Identify (POST)
Use Case: Successfully identify the loyalty user along with any potential rewards/offers that they had pre-selected within the app.
Endpoint URL: https://{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/identify
Variation: NCR expects use Contents
Table of Contents | ||
---|---|---|
|
Overview
This document explains how Loyalty API endpoints must be used with 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. In that case, the Loyalty API v1 - Identify endpoint will return an eligibleDiscounts
field on the response. This will contain any offer or reward that was pre-selected.
Info |
---|
Note: NCR expects us to provide them a field called |
...
products needs to be repriced. |
...
This field is completely optional, it helps the cashier register an incentive at an earlier step, but we can still provide this property for any of the subsequent update calls. |
...
Example request
Info |
---|
Note: This first version should not contain an |
...
Info |
---|
Note: For Pickers, the same |
Info |
---|
...
Note: For an NCR incentive to appear on lookup. The item must already be added to the cart. Otherwise the cashier should expect to receive a notification what they should add that item to the cart and the redemption will be applied at a later step |
...
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
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://{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}
...
],
"transactionId": "$loyaltyTransactionId"
} |
Update (Pending)
NCR will call us with two update calls. The first one will send a status of PENDING
and will not have any discounts applied. If the user pre-selected an incentive 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.NOTE
Info |
---|
Note: On this first call, the |
...
Example request
Code Block |
---|
{ "channel": "Restaurant", "created": "2021-05-04T13:39:47Z", "loyaltyId": "$loyaltyUserId", "serviceMode": "$serivceMode", "status": "PENDING", "transactionDetails": { "currency": "USD", "appliedDiscounts": [ { "details": { "displayName": "some display name" }, "orderReferenceId": "1", "productId": "$benefitPlu", "referenceId": "" } ], "order": [ { "name": "some incentive name", "price": 0, "productId": "$benefitPlu", "productType": "item", "quantity": 1, "referenceId": "1", "tax": 0 }, { "name": "med fries", "price": 0, "productId": "$plu", "productType": "item", "quantity": 1, "referenceId": "2", "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" } |
...
Example response
Code Block |
---|
{
"eligibleDiscounts": [
{
"details": {
"displayName": "some display name",
"type": "REWARD or OFFER",
},
"orderReferenceId": "1", // this will be the referenceId on the request order entry
"productId": "$benefitPlu",
"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"
} |
Transaction Update (PUT) - Claim / Commit
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://{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}
...
"transactionId": "$loyaltyTransactionId"
} |
Update (Claimed)
NCR will call us with two update calls. The second call will send a status of CLAIMED
which will include any appliedDiscounts
for incentives that was given to the user on the final cart state. Using the referenceId
on each entry, we can determine which incentives we should keep as applied on our final transaction stateExpected Request Payload:.
Example request
Code Block |
---|
{ "channel": "Restaurant", "created": "2021-05-04T13:39:47Z", "loyaltyId": "$loyaltyUserId", "serviceMode": "$serviceMode", "status": "CLAIMED", "transactionDetails": { "currency": "USD", "appliedDiscounts": [ { "details": { "displayName": "some display name" }, "orderReferenceId": "1", "productId": "$benefitPlu", "referenceId": "$loyaltyIncentiveId" } ], "order": [ { "name": "some incentive name", "price": 0, "productId": "$benefitPlu", "productType": "item", "quantity": 1, "referenceId": "1", "tax": 0 }, { "name": "med fries", "price": 0, "productId": "$plu", "productType": "item", "quantity": 1, "referenceId": "2", "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" } |
...
Example response
Code Block |
---|
{ "eligibleDiscounts": [ { "details": { "displayName": "some display name", "type": "REWARD or OFFER", }, "orderReferenceId": "1", // this will be the referenceId on the request order entry "productId": "$benefitPlu", "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" } |
...