Contents
Purpose
The Validate Transaction endpoint is used to validate a loyalty order at a client device (typically a POS or Kiosk terminal). The Loyalty Platform will evaluate the order and determine if the user meets eligibility requirements of any included Rewards and Offers. This request should be an exact mirror of what the client device expects to send when they actually claim the transaction when calling the update endpoint Loyalty API v1 - Update.
Request format
Endpoint
PUT /loyalty/transaction/pos/validate/{loyaltyTransactionId}
Headers
As documented here: Loyalty API - Getting Started.
Body
loyaltyId<string>: unique identifier of the loyalty user in UUID format.transactionId<string>: unique identifier of the loyalty transaction created in UUID format.channel<string>: “Restaurant”, “App”, or “Web”. Always use “Restaurant” for In-Restaurant orders.created<string>: string that represents the current date and time of the request.serviceMode<string>: service mode of the order being placed. This can be “EAT_IN”, “TAKEOUT”, ”DRIVE_THRU”, “CURBSIDE”, or “TABLE_SERVICE”.status<string>: status of the order that indicates if the order is still pending or if it has been completed. This can be “PENDING” for orders not yet completed and “CLAIMED” for orders that were completed.transactionDetails: object identifying order information from the request (POS or Kiosk):currency<string>: the ISO currency code used in the market.order: array identifying all products inside the order. each product is an object with these fields:name<string>: name of the product.price<number>: price of the product.productId<string>: PLU of the product.productType<string>: type of the product. This can be “combo”, “item”, “reward” or “offer”.quantity<number>: number of times this product was ordered.referenceId<string>: line ID of producttax<number>: tax amount attributed to this product.parentReferenceId<number> (optional): line id of parent product. Only relevant for children products (e.g. a coke drink that was ordered as part of a whopper medium meal combo).incentiveId<string> (optional): Sanity ID of the offer or reward. Only needs to be sent for offers and rewards.loyaltyEngineId<string> (optional): Loyalty Engine ID of the personalized offer. Only needs to be sent for personalized offers, but it can be sent for all offers. When this field is sent for a personalized offer, theincentiveIddoes not need to be sent. Read more about this here: https://rbictg.atlassian.net/wiki/x/iABm-g.
payments: array with an object identifying payment information of the order:amount<number>: total cost of the order in cents.type<string>: type of payment method that was used during payment for order. This can be “CASH”, “VISA”, “MASTERCARD”, ”AMEX”.
posVendor: object identifying system making the request (POS or Kiosk):transactionId<string>: the POS transaction identifier.storeId<integer>: uniquely identifies the store where the guest is identifying from.terminal<string>: identifies the POS or Kiosk terminal used in the restaurantoperator<string>: identifies the POS operator (only applicable for orders made on a POS terminal)posType<string>: identified the type of POS or Kiosk system making the request. This value must have been previously agreed between the vendor and RBI, so that the correct integration configuration is applied. In most cases, this will be set to a value of “Partner”.supportingPos<string> (optional): used mainly by kiosk vendors, this field will need to refer to the POS vendor of the store the kiosk is sending the request from.
Example request
{
"loyaltyId": "{{loyaltyUserId}}",
"transactionId": "{{loyaltyTransactionId}}",
"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", // required
"productType": "combo", // required
"quantity": 1,
"referenceId": "1", // line id
"tax": 0
},
{
"name": "whopper",
"parentReferenceId"?: "1", // line id of parent (for children elements)
"price": 0,
"productId": "$plu", // required
"productType": "item", // required
"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",
"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": "CASH",
"ccToken": "optional PAN token"
}
],
"posVendor": {
"operator": "300", // cashier / operator id
"posType": "Kiosk vendor name",
"supportingPos": "POS vendor name (optional field)", // vendor to return plu for
"storeId": "9999",
"terminal": "0", // terminal id
"transactionId": "000000000257" // pos transaction id
},
}
}
Response format
Success response body
points<number>: this represents the number of loyalty points the user has. If the order has a status of “PENDING” and includes rewards, then this number already has those loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final point balance of the guest after the order is completed.pointsEarned<number>: this represents the number of loyalty points the user has earned. If the order has a status of “PENDING”, then this number will always be 0 since we don’t update the guests earned loyalty points until the order is completed. If the order has a status of “CLAIMED” this is the total number of points that were earned in this order.pointsRedeemed<number>: this represents the number of loyalty points the user has redeemed. If the order has a status of “PENDING” and includes rewards, then this number is the total loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final number of points that were deducted / burned in this order.loyaltyId<string>: unique identifier of the loyalty user in UUID format.transactionId<string>: unique identifier of the loyalty transaction created in UUID format.
Success response example
{
"points": 14464,
"pointsEarned": 50,
"pointsRedeemed": 750,
"loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of the loyalty user
"transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142" // uuid of the loyalty order/transaction
}
Error responses
All error responses use the standard https://rbictg.atlassian.net/wiki/spaces/RDP/pages/4231725617/LLoyalty+API+v1+-+Error+Responses format.
HTTP
400 (Bad Request)if the request body has an incorrect format. In this case, the response will include details about which specific field or fields have an incorrect format.HTTP
401 (Unauthorized)if authentication headers are missing or not valid.HTTP
404 (Not Found): in the following scenarios indicated in thecodefield of the error response:"UserNotFoundError": the Loyalty user (specifically the loyalty id) was not found."TransactionNotFoundError": the transaction (specifically the transaction id) was not found."RewardNotFoundError": the reward was not found."OfferNotFoundError": the offer was not found.
Error response example
{
"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"
}