Loadmap

Overview

The Loadmap is a structured object that contains information on location-specific wallets, activation items, and tender items. This information can be used to determine what POS items should be tracked, what rewards might be available, and what sorts of items will need to be inserted into the check as a result of various actions.

The Loadmap request queries the PXC or PXS for information on the wallets, activation, and tender items that are relevant to the specified store. This information can be used to determine which check items are being tracked, rewards that might be available, and the sorts of items that need to be inserted into the check. While these values could be hard coded into your integration, it is important to note that many merchants choose to update their programs and rewards on a regular basis. Utilizing the Loadmap reply and Paytronix’s eligibility logic allows you to dynamically add new rewards and tracking groups without the need for additional programming and certification after launch.

Authentication

This flow supports only the B2B Authentication type. See this page for details: API Authentication Styles

Flow

../_images/loadmap.png
  1. Integration sends Loadmap call. This should not occur with every check, but instead should be made on a timed basis system-wide, between once a day and every fifteen minutes.

  2. The Paytronix System returns authorizedSuccess, denied, userDataError, or failure.

    1. If the result is authorizedSuccess, the integration should interpret the Loadmap reply to configure the integration.
    2. If the result is denied, userDataError, or failure, the integration should inform the user of the failure. It is suggested that the integration use the error code and error message returned by the system to inform the user of the problem, the merchant should decide on the exact message.

How to Interpret the Different Wallet Types

Stored Value Wallets

If the merchant uses Paytronix gift cards, only one stored value wallet will be present in the Loadmap. This wallet is indicated by a walletType of 4.

Add or Tracker Type wallets

Add type wallets are used to track and report on guest behavior or certain items purchased in an order. Some examples are dollars spent, number of entrees purchased, or smoothies bought. These wallets will always be marked by a walletType value of 2, and any wallet with this value in the Loadmap should be included in your point accrual request. Most Paytronix loyalty programs utilize at least one tracker wallet. Most commonly this wallet tracks guest spending: the check subtotal before tip and tax, and after any reward reductions. The check subtotal or dollars spent wallet is a type of tracker wallet that is a part of most merchants programs. The dollars spent wallet code number is indicated by a propertyEnumId value of 13103 in the properties array towards the end of the LoadMap reply:

"properties":[{"propertyEnumId":13103,
      "walletCode":2},

In this merchant’s example, wallet code 2 corresponds to the dollars spent wallet.

In addition to dollars spent, some loyalty programs may also track certain items in the check. Each wallet may track a single type of menu item, a single minor group of items, a single major group of items, or some other grouping type from the above list of possible productType values. Which items to track may be determined from the combination of the wallet’s productType and productId. For example, an add wallet with a productType of 3 (where “3” corresponds to minor group) and a productId of 100 means that any item in minor group 100 should be tracked. If four items that belong to minor group 100 are present in the check, the point accrual request to Paytronix should add a quantity of four to this tracker wallet.

Redeem or Reward Wallets

It is possible for a merchant to utilize multiple loyalty reward wallets at once. These wallets will always be marked by a walletType value of 3, as well as a positive rewardType value. The Paytronix system offers several different types of rewards:

  1. Open Dollar Comps

    This is a type of comp that behaves most like a gift card, in that any leftover amounts are saved on the card. One example of this is a card that has a balance of $50 comp dollars and the check is only $20, the guest will retain the leftover $30 on the card that can be used later. This is referred to as an “open” comp because any amount–up to the max on the card–may be applied to the check. If desired, the guest can choose to apply only $5 or $10 of the comp instead of the full check amount. Finally, this style of comp could be applied to multiple items in the check rather than just a single menu item. For example, if the check is made up of 20 one-dollar items, you may still apply $20 worth of the discount. In the Paytronix Loadmap reply, an “open amount” comp is represented by a rewardType value of 2, with the “dollar” definition represented by a valueType value of 2.

  2. Fixed Value Comps

    This comp is most commonly used as a “free item,” but this is not always the case. Fixed value comps may also reduce an item’s price by a specified percentage amount or dollar amount. In a balance inquiry call, each comp on the guest’s card is represented by a value of 1. For instance, a guest might have a free bagel wallet with a balance of 3, meaning he or she has 3 free bagels available. The guest could also have a $5 off wallet with a value of 2 – they thus have 2 $5 comps, for a combined maximum total of $10 at the POS. Fixed value comps do not give change; if any amount of the comp is redeemed at the POS, the Paytronix balance should be reduced by 1. If the guest uses a $5 comp on a $2 check, most POS providers will allow the check to be reduced by $2 and consider the comp successfully used. The three types of fixed value comps are explained in detail below.

    1. Free Items

      The free item comp reduces a single item in the check by a fixed percentage of 100%, meaning the item is free. This comp may only be applied to one item. The Paytronix Loadmap represents this comp as a rewardType of 1 (fixed), a valueType of 1 (percent), and a valueAmount of 100 (100%).

    2. Percent Discounts

      The percent discount comp reduces a single item in the checked by a variable fixed percentage, which is configurable by the merchant. Most commonly, merchants discount by 100%. If the merchant wishes to implement a comp that discounts a single item by 50%, the valueAmount variable in your Loadmap reply will be 50 rather than 100.

    3. Fixed Dollar Discounts

      The fixed dollar discount comp reduces a single item in the check by a fixed dollar amount. For instance, a $5 comp will reduce an item up to $5. In this case, a $2 item would be free, while an $8 item would have its price reduced to $3. The Paytronix Loadmap represents this comp as a rewardType of 1 (fixed), a valueType of 2 (dollar), and a valueAmount that represents the number of dollars to be removed (for instance, our $5 example would have an amount of 5.00).

Further examples:

Wallet Name Wallet Code walletType productType productId discountObjectNumber rewardType valueType
Free Things 5 3 (Redeem) 3 (Minor Group) 1 1000 Fixed Amount Percent
Free Drink 7 3 (Redeem) 4 (Menu Item) 2 999 Fixed Amount Dollar
Reward Dollars 8 3 (Redeem) 1 (Whole Check) 1 22 Open Amount Dollar

The Loadmap reply also indicates which items or grouping of items in the check is eligible for redemption. This is particularly applicable to fixed value comps, for which a “Free Sandwich” reward should only discount sandwiches. Similarly, for Add type wallets, your group of eligible items can be determined by the combination of the wallet’s productType and productId. A free sandwich wallet with a productType of 2 and a productId of 600 means that only items in major group 600 may be reduced by this reward – any other items in the check are ineligible. It is also possible for a reward to reduce the value of the entire check. This is indicated by a productType of 1 and any productId, and the reward is typically applied directly to the check subtotal.

Example

Example Call

Request Body

{
  "headerInfo": {
        "merchantId": 777777,
        "storeCode": "001",
        "operatorId": "0",
        "senderId": "PARTNER",
        "programId": "PX",
        "terminalId": "5",
        "datetime": "2015-04-12 12:25:25.001"
  }
}

Response

{
 "result": "authorizedSuccess",
 "activationItems": [
   {
         "itemId": "7005",
         "itemType": 4,
         "name": "Activate Loyalty",
         "quantity": "1"
   }
 ],
 "properties": [
   {
         "propertyEnumId": 13103,
         "walletCode": 0
   },
   {
         "propertyEnumId": 13101,
         "walletCode": 6
   }
 ],
 "pxAuthCode": "406924",
 "pxTransactionId": 35056505,
 "pxTransactionIdLong": 35056505,
 "requestEvent": "LP222",
 "responseCode": 200,
 "responseMessage": "Successfully retrieved rules and wallets",
 "senderId": "PXS",
 "tenderItems": [
   {
         "itemId": "10",
         "itemType": 12,
         "name": "Promo Tender",
         "quantity": "1"
   }
 ],
 "wallets": [
   {
         "discountObjectNumber": 0,
         "productId": 7006,
         "productType": 4,
         "rewardType": -1,
         "scale": 0,
         "valueAmount": "0.00",
         "valueType": -1,
         "walletCode": 18,
         "walletContents": 0,
         "walletName": "Extra Points Tracker",
         "walletTags": [],
         "walletType": 2
   },
   {
         "discountObjectNumber": 0,
         "productId": 33,
         "productType": 7,
         "rewardType": -1,
         "scale": 2,
         "valueAmount": "0.00",
         "valueType": -1,
         "walletCode": 6,
         "walletContents": 0,
         "walletName": "Dollars Spent",
         "walletTags": [],
         "walletType": 2
   },
   {
         "discountObjectNumber": 0,
         "productId": 8,
         "productType": 8,
         "rewardType": -1,
         "scale": 0,
         "valueAmount": "0.00",
         "valueType": -1,
         "walletCode": 8,
         "walletContents": 0,
         "walletName": "Reward Points",
         "walletTags": [],
         "walletType": 1
   },
   {
         "discountObjectNumber": 120,
         "productDefinition": "1",
         "productId": 99,
         "productType": 4,
         "rewardType": 1,
         "scale": 0,
         "valueAmount": "100",
         "valueType": 1,
         "walletCode": 7,
         "walletContents": 0,
         "walletName": "Free Birthday Bowl",
         "walletTags": [ ],
         "walletType": 3
   }
 ]
}

Wallet Array Example #1

Parameter Value
Wallet Name Free Birthday Bowl
Wallet Code 7
Wallet Type 3
Scale 0
Product Type 4
Product ID 99
Discount Object Number 120
Value Type 1
Reward Type 1
Value amount 100

Please note the following:

  • Wallet Code 7

    You will need to specify this code in any future addRedeem transactions if you wish to add or remove value.

  • Wallet Type 3

    A type of 3 indicates that this is a “redeem” wallet. Add wallets will be marked by a wallet type of 2.

  • Scale 0

    The scale, or number of decimal places, is 0. Here, a value of 2 will be displayed as 2 rather than 2.00. Paytronix will also reflect this in the balance inquiry reply.

  • Product Type and Product ID

    The product type and product ID values are used together to determine which items the wallet tracks or which items may be discounted by the reward. In this case, product type 4 is a menu item grouping. Any items in the check that correspond to menu item number 99 may be discounted by this reward.

  • Discount Object Number 120

    This reward corresponds to POS discount number 120. When inserting the reward into the POS check, this is the discount or coupon number that should be used.

  • Reward Type 1

    The number 1 indicates a reward type of “fixed.” This indicates that this reward will discount an item by a fixed, unchangeable amount (unless the item costs less than the value amount, in which case you may reduce it as much as possible). Fixed types of rewards include free items, rewards that reduce an item by a fixed amount of money, or rewards that reduce an item by a fixed percentage. A reward type of 2 corresponds to an open dollar reward, which can reduce the entire check or reduce a group of items by an amount up to the wallet balance present on the guest’s card.

  • Value Type 1

    The number 1 indicates a value type of “percent.” This, combined with the reward type, indicates that the reward will take a fixed percentage amount off either an item or the entire check. For instance, it might take 100% off (i.e., “free”), or 50% off an item. The same logic applies to a value type of 2 (dollar). In this case, a fixed dollar amount is taken off an item, such as $5 off an item.

  • Value Amount

    Value amount refers to the amount of dollars or the percentage amount that the eligible item should be reduced by. In this example, the value amount is 100, so this particular reward is a fixed percent reward that takes 100% off a single item. Please note that this value does not correspond to the number of this specific reward that the guest has on his or her card – that number is only returned in the balance or add redeem reply.

Wallet Array Example #2

Parameter Value
Wallet Name Entrees Bought
Wallet Code 5
Wallet Type 2
Scale 0
Product Type 4
Product ID 300
Discount Object Number 0
Value Type -1
Reward Type -1
Value amount 0.00

We can determine that this is an Add type wallet, because its walletType is labeled as 2. Since it is not propertyEnumId 13101, this wallet tracks something other than dollars spent. From the productType and productId values, we can tell that this wallet should track any item located in major group 300. All reward-related fields may be ignored.

API Reference

Please see the following API reference page for more details: Transaction Service - Loadmap