Note
Version 2 of the Loyalty API is work in progress, not released yet.

Contents

Table of Contentschildren

minLevel	1
maxLevel	6
outline	false
style	none
type	list
printable	true

Brands and markets want either their pre-existing or new kiosk implementations to work within the in-store loyalty experience. The kiosk user experience will have some slight nuances that we need to account for relating to the Loyalty APIs how Kiosks integrate with them.

Desired Kiosk User Flow

User identifies themselves as a loyalty user at kiosk 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
Upon successful identification:
1. Any pre-selected rewards and/or offers are injected into the Kiosk order
2. User’s information is populated within the Kiosk (i.e. name, points balance)
User is able to proceed with placing their order by selecting desired items/combos
User is able to browse and select additional rewards they wish to redeem
1. Kiosk will display rewards based on user’s available point balance
User completes order at Kiosk
User picks up food at pick-up counter

General API Guidelines

Region {reg} variables:

euc1 EU Timezone Markets
apse1 APAC Timezone Markets
euw3 Iberia Timezone Market

Environment {env} variables:

dev
staging
qa
prod

Brand {brand} variables:

bk
plk
fhs

All API requests should include the following in the header:

x-region field. The value passed in this field should be the 2-character iso country code.
x-api-key field. The value passed in this field will be an environment, vendor and brand specific API key.
x-user-datetime field. The value passed in this field should be the local iso datetime string.

Partner API

We will use the same headers as the Partner API.

Authentication and authorization will use the bearer token in JWT format, which includes the API key, and identifies the following, based on this documentation: /wiki/spaces/IN/pages/3739288100

Brand (e.g. BK)
Region (e.g. UK)
Sub, which is the integration partner (e.g. NCR, Khumbu)
Partner ID, which uniquely identifies the partner configuration which will give us more details if we need.

Endpoints

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: /loyalty/v2/identify

First call

Code Block

{
    "identifier": "123456", // OTP or Loyalty ID, no change to today
    "location": {
        "storeId": "9999",
        "terminalId": "0", // Optional, identifies the POS or Kiosk terminal
        "hasLoyalty": true // Optional, defaults to true. If false, then no points will be earned or burned for transaction and no rewards can be ordered.
    }
}

Subsequent calls

Code Block
{ "identifier": "123456", // OTP or Loyalty ID, no change to today "transactionId": "000000000257" // Optional, only sent on second and subsequent calls }

Expected Request Payload:

Code Block

{
    "identifier": "123456", // No change to today
    "transactionId": "000000000257" // Optional, only sent on second and subsequent calls
    "location": {
        "storeId": "9999",
        "terminalId": "0", // Optional, identifies the POS or Kiosk terminal
        "hasLoyalty": true // Optonal, defaults to true. If false, then no points will be earned or burned for transaction and no rewards can be ordered.
    }
}

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": "Reward PLU",
            "incentiveId": "Sanity ID of Reward"
            "quantity": 1,
            "price": 0,
            "productType": "reward",
            "referenceId": "00", // unique line id
        },
        {
            "productId": "Offer PLU",
            "incentiveId": "Sanity ID of Offer"
            "quantity": 1,
            "productType": "offer",
            "referenceId": "00", // unique line id
        },
    ],
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b" // uuid of the loyalty order/transaction
}

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"
    "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",
                "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",
            "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // pos transaction id
        },
    }
}

Expected Response Payload:

Code Block

{
    "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
}

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"
    "serviceMode": "Eatin",
    "status": "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 element (for children entries)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent element (for children entries)
                "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",
                "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", // operator / cashier name
            "posType": "Kiosk vendor name",
            "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // vendor transaction id
        },
    }
}

Expected Response Payload:

Code Block

{
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of loyalty user
    "presentation": {
        "footer": "Crowns expire 180 days from last purjchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms.",
        "header": "Royal Perks",
        "identifier": "Transaction ID: 07e5c312-9e8e-4e67-8980-f42fc499a142",
        "pointsEarned": "Earned: 50",
        "totalPoints": "Balance: 14464"
    },
    "receiptCode": "NCGXOZOIY2RUX5VR",
    "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142" // uuid of loyalty transaction/order
}

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": "Eatin",
    "status": "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 element (for children entries)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1, 
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent element (for children entries)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "3", // line id
                "tax": 0
            }
        ],
        "payments": [
            {
                "amount": 500,
                "type": "CASH",
                "ccToken": "optional PAN token"
            }
        ],
        "posVendor": {
            "operator": "300", // operator / cashier id
            "posType": "Kiosk vendor name",
            "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // vendor transaction id
        },
    }
}

Expected Response Payload:

Code Block

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

Void Transaction

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": "Eatin",
    "status": "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 element (for children entries)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1, 
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent element (for children entries)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "3", // line id
                "tax": 0
            }
        ],
        "payments": [
            {
                "amount": 500,
                "type": "CASH",
                "ccToken": "optional PAN token"
            }
        ],
        "posVendor": {
            "operator": "300", // operator / cashier id
            "posType": "Kiosk vendor name",
            "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // vendor transaction id
        },
    }
}

Expected Response Payload:

Code Block
{ "transactionId": "$transactionId" // uuid of the loyalty order/transaction }

...

allChildren	true

Versions Compared

Old Version 3

New Version 4

Key

General API Guidelines

Partner API

Endpoints

Identify (POST)

First call

Subsequent calls

Transaction Validation (POST)

Transaction Update (PUT) - Claim / Commit

Unclaimed Transaction (POST)

Void Transaction

Page Comparison

Versions Compared

Old Version 3

New Version 4

Key

General API Guidelines

Partner API

Endpoints

Identify (POST)

First call

Subsequent calls

Transaction Validation (POST)

Transaction Update (PUT) - Claim / Commit

Unclaimed Transaction (POST)

Void Transaction