Versions Compared

Old Version 10

changes.mady.by.user Silva, Carlos

Saved on

compared with

New Version 11

changes.mady.by.user Silva, Carlos

Saved on

Key

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

...

This section explains how the Loyalty API endpoints must be used to process orders that contain personalized offers.

Identify

...

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

...

This endpoint can be used without any changes to support personalised offers.

Validate and Update

When sending a request containing personalized offers to Loyalty API v1 - Validate or Loyalty API v1 - Update, it’s important to include the personalized offer’s loyaltyEngineId. In this case, the incentiveId does not need to be sent.

Example request

Code Block
{
    "identifierchannel": "$6digitCode or $loyaltyIdRestaurant",
     "posVendorcreated": {"2021-05-04T13:39:47Z",
        "matchingIdloyaltyId": "$smgCode$loyaltyUserId",
        "operatorserviceMode": "$operatorId$serviceMode",
    "status": "PENDING or CLAIMED",
    "posTypetransactionDetails": "$posVendorName",{
        "storeIdcurrency": "$rbiStoreIdUSD",
        "supportingPosorder": "POS vendor name (optional field)", // vendor to return plu for [
            {
                "terminalname": "$terminalNumbermed whopper combo",
        "transactionId": "$posTransactionId"     } }

Expected Response Payload:

Code Block
{     "balancesprice": [5.00,
        {        "productId": "$plu",
   "amount": 14464,             "currencyproductType": "pointscombo",
        }     ],     "loyaltyUserquantity": {1,
        "created": "2021-08-10T12:18:39.180Z",         "idreferenceId": "$loyaltyUserId1", // line id
     "name": "$loyaltyUserName"     },     "ordertax": [0
        {             "incentiveId": "$rewardSanityId"},
            "loyaltyEngineId": "$rewardLoyaltyEngineId",{
             "price": 0,
            "productId": "$rewardPlu",
            "productType": "REWARD",
            "quantity": 1,
            "referenceId": "01" // unique line id
        },
        {
            "incentiveId": "$offerSanityId",
            "loyaltyEngineId": "$offerLoyaltyEngineId",
            "productId": "$offerPlu",
            "productType": "OFFER",
            "quantity": 1,
            "referenceId": "02" // unique line id
        }
    ],
    "transactionId": "$loyaltyTransactionId"
}

Transaction Validation (POST)

Use Case: Kiosk 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:

Code Block
{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "PENDING or CLAIMED",
    "transactionDetails": {
        "currency": "USD",
        "order": [
            {
                "name": "med whopper combo",
                "price": 5.00,
                "productId": "$plu",
                "productType": "combo",
                "quantity": 1,
                "referenceId": "1", // line id
                "tax": 0
            },
            {
                "name": "whopper",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "3", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityRewardId",
                "name": "free drink reward",
                "price": 0,
                "productId": "$rewardPlu",
                "productType": "REWARD",
                "quantity": 1,
                "referenceId": "4", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityOfferId",
                "loyaltyEngineId": "$offerLoyaltyEngineId", // (Optional) Use this field for all Offers if supporting Personalized Offers
                "name": "$2.99 chicken sandwich meal",
                "price": 2.99,
                "productId": "$offerPlu",
                "productType": "OFFER",
                "quantity": 1,
                "referenceId": "5", // line id
                "tax": 0.50
            }
        ],
        "payments": [
            {
                "amount": 500,
                "type": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "matchingId": "$smgCode",
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    },
    "transactionId": "$loyaltyTransactionId"
}

Expected Response Payload:

Code Block
{
    "loyaltyId": "$loyaltyUserId",
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "transactionId": "$loyaltyTransactionId"
}

Expected Error Response:

Code Block
{
  "code": "RulesError",
  "details": {
    "ruleEvaluation": [
      {
        "code": "insufficient-point-balance", // reason for rule failure
        "currentValue": 0, // what value was provided
        "message": "User does not have sufficient funds to redeem reward",
        "ruleId": "point-balance", // name of the rule
        "targetValue": 250 // what value is needed
      }
    ]
  },
  "message": "Rule evaluation failed"
}

 

Transaction Update (PUT) - Claim / Commit

Use Case: Kiosk sends this transaction request with the order details to update the loyalty transaction. If the Kiosk 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
{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "PENDING or CLAIMED",
    "transactionDetails": {
        "currency": "USD",
        "order": [
            {
                "name": "med whopper combo",
                "price": 5.00,
                "productId": "$plu",
                "productType": "combo",
                "quantity": 1,
                "referenceId": "1", // line id
                "tax": 0
            },
            {
                "name": "whopper",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "3", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityRewardId",
                "name": "free drink reward",
                "price": 0,
                "productId": "$rewardPlu",
                "productType": "REWARD",
                "quantity": 1,
                "referenceId": "4", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityOfferReward", // (Optional) Don't send this field for Personalized Offer, should send loyaltyEngineId
                "loyaltyEngineId": "$offerLoyaltyEngineId", // (Optional) Use this field for all Offers if supporting Personalized Offers
                "name": "$2.99 chicken sandwich meal",
                "price": 2.99,
                "productId": "$offerPlu",
                "productType": "OFFER",
                "quantity": 1,
                "referenceId": "5", // line id
                "tax": 0.50
            }
        ],
        "payments": [
            {
                "amount": 500,
                "type": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "matchingId": "$smgCode",
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    },
    "transactionId": "$loyaltyTransactionId"
}

Expected Response Payload:

Code Block
{
    "loyaltyId": "$loyaltyUserId",
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "transactionId": "$loyaltyTransactionId"
}

 

Unclaimed Transaction (POST)

Use Case: Kiosk sends a request to Loyalty even when a user does not identify w/ the Loyalty program. This allows us to still create a transaction for the purpose of metrics, analytics, and potentially receipt code claiming

Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos

Expected Request Payload:

Code Block
{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "serviceMode": "$serviceMode",
    "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": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "matchingId": "$smgCode",
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    }
}

Expected Response Payload:

Code Block
{
  "presentation": {
    "footer": "receipt footer",
    "header": "receipt header",
    "marketing": "receipt marketing promo",
    "identifier": "Transaction ID: "$loyaltyTransactionId"
  },
  "transactionId": "$loyaltyTransactionId"
}

 

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

Info

Order information does not need to be included in the Void Transaction Request

Expected Request Payload:

Code Block
{      "channelname": "Restaurantwhopper",
    "created": "2021-05-04T13:39:47Z",            "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
          "serviceMode": "$serviceMode",     "statusproductId": "$plu"PENDING,
or CLAIMED",     "transactionDetails": {         "currencyproductType": "USDitem",
                "orderquantity": [1,
            {    "referenceId": "2", // line id
        "name": "some incentive name",        "tax": 0
           "price": 5.00 },
            {
   "productId": "$incentivePlu",                 "productTypename": "offermed fries",
                "quantityparentReferenceId"?: "1", // line id of parent (for children elements)
        "referenceId": "1",       "price": 0,
        "tax": 0       "productId": "$plu",
    },             {"productType": "item",
                "namequantity": "med whopper combo"1,
                "pricereferenceId": 5.00,
 "3", // line id
                "productIdtax": "$plu", 0
            },
           "productType": "combo", {
                "quantityincentiveId": 1"$sanityRewardId",
                "referenceIdname": "1free drink reward",
                "taxprice": 0,
            },    "productId": "$rewardPlu",
       {                 "name"productType": "whopperREWARD",
                "parentReferenceIdquantity"?: "1",
                "pricereferenceId": 0,"4", // line id
                "productIdtax": "$plu",0
            },
           "productType": "item", {
                "quantityincentiveId": 1"$sanityOfferId",
                "referenceIdloyaltyEngineId": "2$offerLoyaltyEngineId", // (Optional) Use this field for all Offers if supporting Personalized Offers
    "tax": 0            "name": "$2.99 chicken sandwich }meal",
              {  "price": 2.99,
                "nameproductId": "med fries$offerPlu",
                "parentReferenceIdproductType"?: "1OFFER",
                "pricequantity": 01,
                "productIdreferenceId": "$plu5", // line id
                "productTypetax": "item",0.50
            }
   "quantity": 1,        ],
        "referenceIdpayments": "3",[
            {
   "tax": 0             }"amount": 500,
        ],        "type": "payments$paymentMethod":,
[             {   "ccToken"?: "$panToken"
            "amount": 500,}
        ],
        "typeposVendor": "$paymentMethod",{
                "ccTokenmatchingId"?: "$panToken$smgCode",
            }
"operator": "$operatorId",
       ],         "posVendorposType": {"$posVendorName",
            "matchingIdstoreId": "$smgCode$rbiStoreId",
            "operatorsupportingPos": "$operatorId",POS vendor name (optional field)", // vendor to return plu for
            "posTypeterminal": "$posVendorName$terminalNumber",
            "storeIdtransactionId": "$rbiStoreId",$posTransactionId"
        }
    },
    "terminaltransactionId": "$terminalNumber$loyaltyTransactionId",

}

Example response

Code Block
{
      "loyaltyId": "$loyaltyUserId",
    "transactionIdpoints": "$posTransactionId"14464,
    "pointsEarned": 50,
  }     }
}

Expected Response Payload:

Code Block
{"pointsRedeemed": 750,
    "transactionId": "$loyaltyTransactionId"
}

...