Overview

This document explains how Loyalty API endpoints must be used with Reward combos for NCR point of sale system.

Identify

When a guest scans an identification code on a POS or Kiosk, they may pre-select offers or rewards. For Rewards, NCR expects use to provide them w/ a new field called eligibleDiscounts that tells their system which item needs to be marked as free.

Note: This field is completely optional, it helps the cashier register a reward at an earlier step, but we can still provide this property for any of the subsequent update calls.

Example Request

{
    "identifier": "$digitCode or $loyaltyId",
    "posVendor": {
        "matchingId": "$smgCode",
        "operator": "$operatorId",
        "posType": "$posVendorName",
        "storeId": "$rbiStoreId",
        "terminal": "$terminalNumber",
        "transactionId": "$posTransactionId"
    }
}

Example Response

{
    "balances": [
        {
            "amount": 14464,
            "currency": "points"
        }
    ],
    "eligibleDiscounts": [
        {
            "details": {
                "displayName": "some display name",
                "type": "REWARD or OFFER"
            },
            "productId": "$benefitPlu",
            "referenceId": "$loyaltyIncentiveId"
        }
    ],
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "$loyaltyUserId",
        "name": "$loyaltyUserName"
    },
    "order": [
        {
            "name": "Whopper",
            "productId": "$incentivePlu",
            "referenceId": "00"
        }
    ],
    "transactionId": "$loyaltyTransactionId"
}

Update (Pending)

NCR will call us with two update calls. The first one will send a status of PENDING. This first call will have appliedDiscounts with no referenceId (engine id which will later use to apply the discount on our side). If the user pre-selected a reward prior to identifying OR the cart contains an upsize plu, NCR expects us to return an eligibleDiscounts field that points to the entry being discounted, the pointer used is the orderReferenceId. The orderReferenceId must match the referenceId of the cart entry that needs to be discounted from the request body.

For combos, NCR will provide all the combo slots in the appliedDiscounts array. Each entry will have a comboId (the combo document plu) and comboInstanceId which will be unique identifier for us to group all of the slots for one particular combo entry.

Example request

{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serivceMode",
    "status": "PENDING",
    "transactionDetails": {
        "currency": "USD",
        "appliedDiscounts": [
            {
                "comboId": "$comboPlu",
                "comboInstanceId": "$uniqueIdPerCombo",
                "details": {
                    "displayName": "WHOPPER Meal",
                    "type": "REWARD"
                },
                "orderReferenceId": "1",
                "productId": "9088",
                "referenceId": ""
            },
            {
                "comboId": "$comboPlu",
                "comboInstanceId": "$uniqueIdPerCombo",
                "details": {
                    "displayName": "WHOPPER",
                    "type": "REWARD"
                },
                "orderReferenceId": "2",
                "productId": "110",
                "referenceId": ""
            },
            {
                "comboId": "$comboPlu",
                "comboInstanceId": "$uniqueIdPerCombo",
                "details": {
                    "displayName": "REGULAR FRIES ML",
                    "type": "REWARD"
                },
                "orderReferenceId": "3",
                "productId": "713",
                "referenceId": ""
            },
            {
                "details": {
                    "displayName": "REGULAR COKE",
                    "type": "REWARD"
                },
                "comboInstanceId": "$uniqueIdPerCombo",
                "comboId": "$comboPlu",
                "orderReferenceId": "4",
                "productId": "400102",
                "referenceId": ""
            }
        ],
        "order": [
            {
                "name": "Meal selection",
                "price": 0,
                "productId": "9088",
                "productType": "product",
                "quantity": 1,
                "referenceId": "6",
                "tax": 0
            },
            {
                "name": "WHOPPER",
                "price": 6.49,
                "productId": "110",
                "productType": "product",
                "quantity": 1,
                "referenceId": "7",
                "tax": 0
            },
            {
                "name": "REGULAR FRIES ML",
                "price": 2.39,
                "productId": "713",
                "productType": "product",
                "quantity": 1,
                "referenceId": "8",
                "tax": 0
            },
            {
                "name": "REGULAR COKE",
                "price": 2.82,
                "productId": "400102",
                "productType": "product",
                "quantity": 1,
                "referenceId": "9",
                "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"
}

Example response

Update (Claimed)

NCR will call us with two update calls. The second call will send a status of CLAIMED which will include any appliedDiscounts for rewards / upsizes that was given to the user. Unlike the first call, these entries will contain a referenceId for us to reconcile with the customer’s preselected rewards.

RBI Developer Portal

Loyalty API - NCR Reward Combos

Overview

Identify

Example Request

Example Response

Update (Pending)

Example request

Example response

Update (Claimed)

Example request

Example response