Versions Compared

Old Version 4

changes.mady.by.user Silva, Carlos

Saved on

compared with

New Version Current

changes.mady.by.user Lopes da Costa, Valentina

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
stylenone

Desired In-store Loyalty User Flow

  1. User identifies themselves as a loyalty user at the POS using identification mechanism (i.e. 6-digit short, code, QR code, etc.)

    1. The identification may include pre-selecting rewards and/or offers within the app similar to the in-store loyalty experience

  2. Upon successful identification:

    1. Any pre-selected rewards and/or offers are injected into the POS order

    2. User’s information is populated within the POS terminal (i.e. name, points balance)

  3. User is able to proceed with placing their order by selecting desired items/combos

  4. 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"
}

...