Versions Compared

Old Version 2

changes.mady.by.user Lopes da Costa, Valentina

Saved on

compared with

New Version Current

changes.mady.by.user Silva, Carlos

Saved on

Key

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

...

Table of Contents
stylenone

Overview

This document explains how Loyalty API endpoints must be used with 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. In that case, the Loyalty API v1 - Identify endpoint will return an eligibleDiscounts field on the response. This will contain any offer or reward that was pre-selected.

Info

Note: NCR expects us to provide them a field called eligibleDiscounts that tells their system which products needs to be repriced. This field is completely optional, it helps the cashier register an incentive at an earlier step, but we can still provide this property for any of the subsequent update calls.

Example request

Info

Note: This first version should not contain an orderReferenceId. This is used to tell NCR’s system which order line this discount should be applied to. We won’t know this till later steps when NCR provides us with a cart.

...

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

Example response

Code Block
{
    "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 w/ with two update calls. The first one will send a status of PENDING and will not have any discounts applied. If the user pre-selected an incentive 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.

Info

Note: On this first call, the referenceId for each appliedDiscounts entry will be blank. They will stamp whatever we provide for that field within eligibleDiscounts on the response on any subsequent calls

Example request

Code Block
{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serivceMode",
    "status": "PENDING",
    "transactionDetails": {
        "currency": "USD",
        "appliedDiscounts": [
            {
                "details": {
                    "displayName": "some display name"
                },
                "orderReferenceId": "1",
                "productId": "$benefitPlu",
                "referenceId": ""
            }
        ],
        "order": [
            {
                "name": "some incentive name",
                "price": 0,
                "productId": "$benefitPlu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "1",
                "tax": 0
            },
            {
                "name": "med fries",
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2",
                "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

Code Block
{
    "eligibleDiscounts": [
      {
        "details": {
          "displayName": "some display name",
          "type": "REWARD or OFFER",
        },
        "orderReferenceId": "1", // this will be the referenceId on the request order entry
        "productId": "$benefitPlu",
        "referenceId": "$loyaltyIncentiveId"
      }
    ],
    "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"
}

 

Update (Claimed)

NCR will call us w/ with two update calls. The second call will send a status of CLAIMED which will include any appliedDiscounts for incentives that was given to the user on the final cart state. Using the referenceId on each entry, we can determine which incentives we should keep as applied on our final transaction state.

Example request

Code Block
{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "CLAIMED",
    "transactionDetails": {
        "currency": "USD",
        "appliedDiscounts": [
          {
            "details": {
              "displayName": "some display name"
            },
            "orderReferenceId": "1",
            "productId": "$benefitPlu",
            "referenceId": "$loyaltyIncentiveId"
          }
        ],
        "order": [
            {
                "name": "some incentive name",
                "price": 0,
                "productId": "$benefitPlu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "1",
                "tax": 0
            },
            {
                "name": "med fries",
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2",
                "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

Code Block
{
    "eligibleDiscounts": [
      {
        "details": {
          "displayName": "some display name",
          "type": "REWARD or OFFER",
        },
        "orderReferenceId": "1", // this will be the referenceId on the request order entry
        "productId": "$benefitPlu",
        "referenceId": "$loyaltyIncentiveId"
      }
    ],
    "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"
}

...