Contents
Desired In-store Loyalty User Flow
User identifies themselves as a loyalty user at the POS using identification mechanism (i.e. 6-digit short, code, QR code, etc.)
The identification may include pre-selecting rewards and/or offers within the app similar to the in-store loyalty experience
Upon successful identification:
Any pre-selected rewards and/or offers are injected into the POS order
User’s information is populated within the POS terminal (i.e. name, points balance)
User is able to proceed with placing their order by selecting desired items/combos
User completes order at POS and gets their food
Assumptions
There will be no specific reward PLUs setup for Winrest - instead a generic discount PLU will be used by the POS to apply a 100% towards the reward item
Reward sanity documents will have the reward item PLU mapped in the respective vendor config - this PLU will be sent back to the POS
Out of scope
Supporting multiple offer redemptions per order
Supporting offer redemptions at kiosk
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://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/identify
Expected Request Payload:
{
"identifier": "123456",
"posVendor": {
"operator": "300",
"posType": "Winrest" or "Tillster",
"supportingPos": "Partner",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
}
}
Expected Response Payload:
{
"balances": [
{
"amount": 14464,
"currency": "points"
}
],
"loyaltyUser": {
"created": "2021-08-10T12:18:39.180Z",
"id": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
"name": "Farhan"
},
"order": [
{
"productId": "$incentivePlu",
"incentiveId": "sanity id of reward or offer",
"quantity": "1"
"referenceId": "00",
"productType": "REWARD or OFFER",
"price": "0" (price field only returned back for rewards)
},
],
"transactionId": "f4190848-169d-4c69-9f53-f916318c432b"
}
Transaction Validation (POST)
Use Case: POS sends the Loyalty API a preliminary version of the user’s order so that the Loyalty Platform can evaluate the order and determine if the user meets eligibility requirements of any included incentives (Rewards or Offers). This request should be an exact mirror of what the POS expects to send when they actually claim the transaction.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/validate/{loyaltyTransactionId}
Expected Request Payload:
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"serviceMode": "Eatin",
"status": "CLAIMED",
"transactionDetails": {
"currency": "USD",
"order": [
{
"name": "some incentive name",
"price": 5.00,
"productId": "$incentivePlu",
"productType": "offer",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "med whopper combo",
"price": 5.00,
"productId": "$plu",
"productType": "combo",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "whopper",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu:,
"productType": "item",
"quantity": 1,
"referenceId": "2",
"tax": 0
},
{
"name": "med fries",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "3",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CASH" or "CARD",
"ccToken": "optional PAN token"
}
],
"posVendor": {
"operator": "300",
"posType": "POS/Kiosk vendor name",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
},
}
}
Expected Response Payload:
{
"points": 14464,
"pointsEarned": 50,
"pointsRedeemed": 750,
"loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
"transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142"
}
Expected Error Response:
{
"code": "RulesError",
"details": {
"ruleEvaluation": [
{
"code": "insufficient-point-balance",
"currentValue": 0,
"message": "User does not have sufficient funds to redeem reward",
"ruleId": "point-balance",
"targetValue": 250
}
],
"isEngineError": true,
"errorConfig": {
"timeout": 0,
"method": "put",
"data": "__REDACTED__",
"url": $url
}
},
"message": "Rule evaluation failed"
}
Note: A more thorough list of error codes can be provided by RBI upon request.
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://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}
Expected Request Payload:
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"serviceMode": "Eatin",
"status": "CLAIMED",
"transactionDetails": {
"currency": "USD",
"order": [
{
"name": "some incentive name",
"price": 5.00,
"productId": "$incentivePlu",
"productType": "offer",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "med whopper combo",
"price": 5.00,
"productId": "$plu",
"productType": "combo",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "whopper",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "2",
"tax": 0
},
{
"name": "med fries",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "3",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CASH" or "CARD",
"ccToken": "optional PAN token"
}
],
"posVendor": {
"operator": "300",
"posType": "POS/Kiosk vendor name",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
},
}
}
Expected Response Payload:
{
"points": 14464,
"pointsEarned": 50,
"pointsRedeemed": 750,
"loyaltyId": "$loyaltyUserId",
"transactionId": "$transactionId"
}
Unclaimed Transaction (POST)
Use Case: POS sends the RBI Loyalty Platform a copy of the transaction that takes place without a loyalty user initially identified.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos
Expected Request Payload:
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"serviceMode": "Eatin",
"status": "CLAIMED",
"transactionDetails": {
"currency": "USD",
"order": [
{
"name": "med whopper combo",
"price": 5.00,
"productId": "$plu",
"productType": "combo",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "whopper",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "2",
"tax": 0
},
{
"name": "med fries",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "3",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CASH" or "CARD",
"ccToken": "optional PAN token"
}
],
"posVendor": {
"operator": "300",
"posType": "POS/Kiosk vendor name",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
},
}
}
Expected Response Payload:
{
"presentation": {
"footer": "receipt footer",
"header": "receipt header",
"marketing": "receipt marketing promo",
"identifier": "Transaction ID: $transactionId"
},
"transactionId": "$transactionId"
}
Void Transaction (PUT)
Use Case: Loyalty transaction needs to be voided/refunded.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}/void
Expected Request Payload:
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"serviceMode": "Eatin",
"status": "CLAIMED",
"transactionDetails": {
"currency": "USD",
"order": [
{
"name": "some incentive name",
"price": 5.00,
"productId": "$incentivePlu",
"productType": "offer",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "med whopper combo",
"price": 5.00,
"productId": "$plu",
"productType": "combo",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "whopper",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "2",
"tax": 0
},
{
"name": "med fries",
"parentReferenceId"?: "1",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "3",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CASH" or "CARD",
"ccToken": "optional PAN token"
}
],
"posVendor": {
"operator": "300",
"posType": "POS/Kiosk vendor name",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
},
}
}
Expected Response Payload:
{
"transactionId": "$transactionId"
}