Versions Compared

Old Version 13

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

Saved on

compared with

New Version Current

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

Saved on

Key

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

This is the top level page for the current version we recommend using for Loyalty API integration for both POS and Kiosk vendors. This supports multi-scanning and showing offers on the Kiosk UI.

Table of Contents
minLevel1
maxLevel6
outlinefalse
styledefault
typelist
printabletrue

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: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/identify

Expected Request Payload:

Code Block
{
    "identifier": "123456",
    "posVendor": {
        "operator": "300", // operator id
        "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
        "posType": "Kiosk vendor name",
        "storeId": "9999",
        "terminal": "0", // terminal id
        "transactionId": "000000000257" // vendor transaction id
    }
}

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

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
{
    "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",
                "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",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "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",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "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
{
    "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",
                "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",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // vendor transaction id
        },
    }
}

Expected Response Payload:

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

Redeem Promo Code

Use Case: Redeem Promo Code and unlock Loyalty Offer for a loyalty user

Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/promo-code/redeem

Expected Request Payload:

Code Block
{
  "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of the loyalty user
  "promoCode": "123456", // promo code identifier
  "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
  },
}

Expected Response Payload:

Code Block
{
  "sanityId": "5f887b7e-348f-4861-822a-7dad712989e8" // sanityid of the offer redeemed
}

Expected Error Response Payload:

Promo code does not exist:

Code Block
{
  "code": "INVALID_PROMO_CODE",
  "details": {
    "promoCode": "123456", // promo code identifier
  },
  "httpCode": 404,
  "message": $errorMessage
}

Promo code is unredeemable:

Code Block
{
  "code": UNREDEEMABLE_PROMO_CODE",
  "details": {
    "promoCode": "123456", // promo code identifier
  },
  "httpCode": 422,
  "message": $errorMessage
}

Promo code vendor config is not correct:

Code Block
{ "code": "PROMO_CODE_VENDOR_CONFIG_ERROR, "httpCode": 422, "details": { "vendor": $vendorName } "message": $errorMessage }

These pages are meant to be read in coordination with Loyalty API - In-Store Customer Journey which explains the user experience flow intended to implement by using this API.

Child pages (Children Display)
allChildrentrue