Contents
| Table of Contents |
|---|
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
...
|
Overview
The SICOM integration to the Loyalty API uses the same endpoints listed under Loyalty API v1 - Endpoint Reference, however it relies on PLU’s only for item mapping. Therefore, when calling Loyalty API v1 - Validate and Loyalty API v1 - Update:
The PLU should be sent under productId;
The incentiveId field should not be sent.
See examples in the next section below.
Validate and Update
Example request
| Code Block |
|---|
{
"identifierchannel": "Restaurant"$6digitCode,
or $loyaltyId", "posVendorcreated": {"2021-05-04T13:39:47Z",
"matchingIdloyaltyId": "$smgCode$loyaltyUserId",
"operatorserviceMode": "$operatorId$serviceMode",
"posTypestatus": "$posVendorNamePENDING",
"storeIdtransactionDetails": "$rbiStoreId",{
"terminalcurrency": "$terminalNumberUSD",
"transactionIdorder": "$posTransactionId"[
} } |
Expected Response Payload:
| Code Block |
|---|
{ "balances": [ { "amount": 14464, "currencyname": "points"some incentive name", } ], "loyaltyUserprice": { "created": "2021-08-10T12:18:39.180Z", "id": "$loyaltyUserId", "name": "$loyaltyUserName" }, "order": [ { "productId": "$incentivePlu", "quantity": "1" "referenceId": "00", "productType": "REWARD or OFFER" }, ], "transactionId": "$loyaltyTransactionId" } |
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:
| Code Block |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serviceMode",
"status": "PENDING",
"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": "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:
| Code Block |
|---|
{
"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"
} |
Expected Error Response:
| Code Block |
|---|
{
"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"
} |
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 |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"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": "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:
| Code Block |
|---|
{
"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"
} |
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 |
|---|
{
"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": "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"
}
}
} |
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
Expected Request Payload:
| Code Block |
|---|
{ "channel": "Restaurant", "created": "2021-05-04T13:39:47Z", "serviceMode": "$serviceMode", "status": "PENDING or CLAIMED", "transactionDetails": {5.00, "productId": "$incentivePlu", "productType": "offer", "quantity": 1, "referenceId": "1", "currencytax": "USD",0 "order": [ }, { "name": "somemed incentivewhopper namecombo", "price": 5.00, "productId": "$incentivePlu$plu", "productType": "offercombo", "quantity": 1, "referenceId": "1", "tax": 0 }, { { "name": "whopper", "nameparentReferenceId"?: "med whopper combo1", "price": 5.000, "productId": "$plu", "productType": "comboitem", "quantity": 1, "referenceId": "12", "tax": 0 }, { "name": "whoppermed fries", "parentReferenceId"?: "1", "price": 0, "productId": "$plu", "productType": "item", "quantity": 1, "referenceId": "23", "tax": 0 }, { "name": "med fries", } ], "parentReferenceId"?: "1", "payments": [ "price": 0, { "productIdamount": "$plu"500, "productTypetype": "itemCREDIT", "quantityccToken": 1,"$panToken" "referenceId": "3"}, { "tax": 0 } "amount": 400, ], "paymentstype": ["CASH" {}, "amount": 500,{ "typeamount": "CREDIT"1000, "ccTokentype": "$panTokenSUBTOTAL" }, { "amount": 400300, "type": "CASHDISCOUNTS" }, { "amount": 1000200, "type": "SUBTOTALTAXES" } ], "posVendor": { { "matchingId": "$smgCode", "amountoperator": 300"$operatorId", "typeposType": "DISCOUNTS$posVendorName", }"storeId": "$rbiStoreId", { "terminal": "$terminalNumber", "transactionId": "amount$posTransactionId": 200, } }, "typetransactionId": "TAXES$loyaltyTransactionId" } |
Example response
| Code Block |
|---|
{ "points": 102220, "pointsEarned": 5000, } "pointsRedeemed": 0, ], "loyaltyId": "$loyaltyUserId", "posVendorpresentation": { "matchingIdfooter": "$smgCode",Crowns expire 180 days from last purchase. At participating U.S. restaurants. Terms "operator": "$operatorId", at bk.com/rewards-terms", "posTypeheader": "$posVendorNameRoyal Perks", "storeIdidentifier": "$rbiStoreIdTransaction ID: $loyaltyTransactionId", "terminalpointsEarned": "$terminalNumberEarned: 5000", "transactionIdtotalPoints": "$posTransactionIdBalance: 102220" }, } "receiptCode": "J25QL1WAH5KJ7P75", } } |
Expected Response Payload:
| Code Block |
|---|
{
"transactionId": "$loyaltyTransactionId"
} |
...