Base Kiosk Integration

1 Identify (POST)
2 Transaction Validation (POST)
3 Transaction Update (PUT) - Claim / Commit
4 Unclaimed Transaction (POST)
5 Void Transaction

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:

{
    "identifier": "$6digitCode or $loyaltyId",
     "posVendor": {
        "matchingId": "$smgCode",
        "operator": "$operatorId",
        "posType": "$posVendorName",
        "storeId": "$rbiStoreId",
        "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
        "terminal": "$terminalNumber",
        "transactionId": "$posTransactionId"
    }
}

Expected Response Payload:

{
    "balances": [
        {
            "amount": 14464,
            "currency": "points"
        }
    ],
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "$loyaltyUserId",
        "name": "$loyaltyUserName"
    },
    "order": [
        {
            "incentiveId": "$rewardSanityId",
            "price": 0,
            "productId": "$rewardPlu",
            "productType": "reward",
            "quantity": 1,
            "referenceId": "01" // unique line id
        },
        {
            "incentiveId": "$offerSanityId",
            "productId": "$offerPlu",
            "productType": "offer",
            "quantity": 1,
            "referenceId": "02" // unique line id
        }
    ],
    "transactionId": "$loyaltyTransactionId"
}

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. Please refer to Loyalty API v1 - Error Responses for a list of potential error message returned from this endpoint.

Endpoint URL: https://{reg}-{env}-{brand}-loyalty-middleware.rbictg.com/loyalty/transaction/pos/validate/{loyaltyTransactionId}

Expected Request Payload:

{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "PENDING or 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 (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "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": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "matchingId": "$smgCode",
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    },
    "transactionId": "$loyaltyTransactionId"
}

Expected Response Payload:

Expected Error Response:

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:

Expected Response Payload:

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:

Expected Response Payload:

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:

Expected Response Payload: