...
Table of 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:
Code Block |
---|
{
"identifier": "123456",
"posVendor": {
"operator": "300",
"posType": "Winrest" or "Tillster",
"supportingPos": "Partner",
"storeId": "9999",
"terminal": "0",
"transactionId": "000000000257"
}
}
|
Expected Response Payload:
Code Block |
---|
{
"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:
...
Overview
The Winrest integration to the Loyalty API uses the same endpoints listed under Loyalty API v1 - Endpoint Reference, however it returns prices for rewards in the Identify request. Therefore, when calling Loyalty API v1 - Identify :
The price of the reward will be returned if a reward with price is pre-selected.
See examples in the next section below.
Identify
Example request
Code Block |
---|
{ "identifier": "123456", "posVendor": { "productIdoperator": "$plu300", "productType"posType": "itemWinrest", or "Tillster", "quantity"supportingPos": 1"Partner", "storeId": "9999", "referenceIdterminal": "30", "transactionId": "000000000257" } "tax": 0 } |
Example response
Code Block |
---|
{ "balances": [ } { ], "paymentsamount": [14464, { "currency": "points" } "amount": 500], "loyaltyUser": { "typecreated": "CASH" or "CARD",2021-08-10T12:18:39.180Z", "id": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", "ccTokenname": "optional PAN tokenFarhan" }}, "order": [ ], "posVendor": { "operatorproductId": "300$incentivePlu", "posTypeincentiveId": "POS/Kiosk vendor namesanity id of reward or offer", "storeIdquantity": "99991", "terminalreferenceId": "000", "transactionId": "000000000257" "productType": "REWARD or }OFFER", } } |
Expected Response Payload:
Code Block |
---|
{ "pointsprice": 14464,"300" "pointsEarned": 50, "pointsRedeemed": 750}, "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7"], "transactionId": "07e5c312f4190848-9e8e169d-4e674c69-89809f53-f42fc499a142f916318c432b" } |
Validate
Expected
...
Request
Code Block |
---|
{ "codechannel": "RulesErrorRestaurant", "detailscreated": {"2021-05-04T13:39:47Z", "ruleEvaluationserviceMode": ["Eatin", {"status": "CLAIMED", "codetransactionDetails": "insufficient-point-balance",{ "currentValuecurrency": 0"USD", "messageorder": "User does not have sufficient funds to redeem reward", [ { "ruleId": "point-balance", "targetValuename": 250 "some incentive name", } ], "isEngineErrorprice": true5.00, "errorConfig": { "timeoutproductId": 0"$incentivePlu", "method": "put", "dataproductType": "__REDACTED__offer", "url": $url } }, "messagequantity": "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:
Code Block |
---|
{1, "referenceId": "1", "tax": 0 }, { "name": "med whopper combo", "price": 5.00, "channelproductId": "Restaurant$plu", "created "productType": "2021-05-04T13:39:47Zcombo", "serviceMode": "Eatin", "statusquantity": "CLAIMED"1, "transactionDetails": { "currencyreferenceId": "USD1", "order": [ "tax": 0 { }, "name": "some incentive name",{ "pricename": 5.00"whopper", "productIdparentReferenceId"?: "$incentivePlu1", "productTypeprice": "offer"0, "quantityproductId": 1"$plu:, "referenceIdproductType": "1item", "taxquantity": 01, }, "referenceId": "2", { "tax": 0 "name": "med whopper combo", }, "price": 5.00,{ "productIdname": "$plumed fries", "productTypeparentReferenceId"?: "combo1", "quantityprice": 10, "referenceIdproductId": "1$plu", "tax": 0 "productType": "item", }, {"quantity": 1, "namereferenceId": "whopper3", "parentReferenceIdtax"?: "1",0 } "price": 0], "payments": [ "productId": "$plu", { "productTypeamount": "item"500, "type": "CASH" or "quantityCARD": 1, "referenceIdccToken": "2",optional PAN token" } "tax": 0 ], }, "posVendor": { { "operator": "300", "nameposType": "med friesPOS/Kiosk vendor name", "parentReferenceIdstoreId"?: "19999", "priceterminal": "0", "productIdtransactionId": "$plu000000000257", }, } } |
Example Response
Code Block |
---|
{ "productTypepoints": "item"14464, "pointsEarned": 50, "pointsRedeemed": 750, "quantityloyaltyId": 1"4711fc2a-3a8f-414f-a9e7-44dd5231dca7", "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142" } |
Example Error Response
Code Block |
---|
{ "referenceIdcode": "3RulesError", "details": { "ruleEvaluation": [ "tax":{ 0 "code": "insufficient-point-balance", } ]"currentValue": 0, "paymentsmessage": ["User does not have sufficient funds to redeem reward", { "ruleId": "point-balance", "amounttargetValue": 500,250 } ], "typeisEngineError": "CASH" ortrue, "CARDerrorConfig",: { "timeout": 0, "ccTokenmethod": "optionalput", PAN token" "data": "__REDACTED__", }"url": $url } ]}, "posVendormessage": { "Rule evaluation failed" } |
Info |
---|
Note: A more thorough list of error codes can be found here: Loyalty API v1 - Error Responses |
Update
Example Request
Code Block |
---|
{ "operatorchannel": "300Restaurant", "posType"created": "POS/Kiosk vendor name2021-05-04T13:39:47Z", "serviceMode": "Eatin", "storeIdstatus": "9999CLAIMED", "transactionDetails": { "terminalcurrency": "0USD", "order": [ "transactionId": "000000000257" },{ } } |
Expected Response Payload:
Code Block |
---|
{ "points": 14464, "pointsEarnedname": 50 "some incentive name", "pointsRedeemed": 750, "loyaltyId": "$loyaltyUserId", "transactionIdprice": "$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:
Code Block |
---|
{ 5.00, "channelproductId": "Restaurant$incentivePlu", "created": "2021-05-04T13:39:47Z", "productType": "offer", "quantity": 1, "serviceMode": "Eatin", "statusreferenceId": "CLAIMED1", "transactionDetails": { "currencytax": "USD", 0 "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" }, } } |
...
Example Response
...
Code Block |
---|
{ "presentation": { "footerpoints": "receipt footer"14464, "headerpointsEarned": "receipt header"50, "marketingpointsRedeemed": "receipt marketing promo"750, "identifierloyaltyId": "Transaction ID: $transactionId"$loyaltyUserId", }, "transactionId": "$transactionId" } |
Void
...
Use Case: Loyalty transaction needs to be voided/refunded.
Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/{loyaltyTransactionId}/void
...
Example Request
Code Block |
---|
{ "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" }, } } |
...
Example Response
...
Code Block |
---|
{ "transactionId": "$transactionId" } |
...