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 to provide them a field called eligibleDiscounts that tells their system which item needs to be repriced.
NOTE: 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.
NOTE: This first version should not contain an orderReferenceId. This is used to tell NCR’s system which order line this discount should be applied to. We won’t know this till later steps when NCR provides us with a cart.
NOTE: For Pickers, the same eligibleDiscounts object will be returned in the response along with all potential picker options. On a later step, we will attempt to reconcile these options with what NCR provides on appliedDiscounts, which tells us which picker option was selected
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
Expected Request Payload:
{
"identifier": "$digitCode or $loyaltyId",
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
}
Expected Response Payload:
{
"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}
Variation: NCR will call us w/ 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: On this first call, the referenceId for each appliedDiscounts entry will be blank. They will stamp whatever we provide for that field within eligibleDiscounts on the response on any subsequent calls
Expected Request Payload:
{
"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"
}
Expected Response Payload:
{
"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}
Variation: NCR will call us w/ 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 state
Expected Request Payload:
{
"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"
}
Expected Response Payload:
{
"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"
}