Check Service

The check service provides endpoints for posting check information, redeeming rewards, and accruing points on checks. The basic principle of the check service is that all discounting eligibility and calculation logic lives within the Paytronix system, and an integration need only send an accurate picture of the state of the check for evaluation, redemption, and posting.

Request Objects

PotentialUnitItem

This object represents an item which has not yet been inserted into the check, but which is available to the guest, and which the caller would like to have considered for per-unit discounting. This is generally only used for items which are purchased by weight or volume (e.g. pounds of coffee or gallons of gasoline).

JSON Parameters:
 
  • itemId (String) – (required) Identifier for this item. This identifies the item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the item.
  • categories (List[Object]) – (required) Can be empty. Any categories the menu item is associated with. See Category for format
  • pricePerUnit (Decimal) – (required) Per-unit price of the item. Expected to be positive.
cardAmount

This object represents loyalty card information and the amount of the check paid by that guest.

JSON Parameters:
 
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details
  • amountPaid (Decimal) – (required) The amount that was paid by this guest.

Endpoints

Check Compute Point Accrual

POST check/computePointAccrual.json

The check compute point accrual request can be used to have the PXS compute a point accrual Add/Redeem Request based on the contents of a POS check. The resulting add/redeem can then be submitted for processing by the PXS.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "autoActivateCard": false,
   "terminal": "1",
   "operator": "0"
}

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active. Defaults to false
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • voidAddRedeem (Object) – (optional) The void add/redeem request to send to process the voided items/amounts in the check. If given in the reply, should be sent via POST transaction/voidAddRedeem.json prior to the Add/Redeem.
  • addRedeem (Object) – (optional) The add/redeem request to send to process the nonvoided items/amounts in the check. If given in the reply, should be sent via POST transaction/addRedeem.json.

Example response body

{
   "result": "success",
   "voidAddRedeem": {}, //see POST transaction/voidAddRedeem.json
   "addRedeem": {} //see POST transaction/addRedeem.json
}
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Compute Applicable Rewards

POST check/computeApplicableRewards.json

The check compute applicable rewards request can be used to have the PXS compute which rewards on the guest’s card would apply to the given check.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "terminal": "1",
   "operator": "0",
   "rewardSelectionMode": {
      "mode": "manual",
      "chosenRewards": [
         {
            "walletCode": 50,
            "amount": 1.0
         }
      ]
   }
}

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic, manual, or applicable_rewards reward selection. See RewardSelectionMode for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that could be applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts that could be applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of whole-check discounts that could be applied to the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • serviceChargeDiscounts (List[Object]) – (required) The list of serviceCharge discounts that could be applied to the check. See ServiceChargeDiscount for the format of the individual objects
  • anonymousAccountToken (String) – (optional) Unique String value to identify the guest.
  • customerName (String) – (required) The customer’s name
  • tierName (String) – (required) The tier label for this customer
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • maskedCardNumber (String) – (required) The masked card number associated with the account.
  • pointBalances (List[Object]) – (required) The guest’s loyalty point balances. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for details
  • changedWalletContents (List[Object]) – (required) The list of visible points changes. See ChangedPointInfo for details
  • posMessages (List[String]) – (required) A list of messages to be displayed to the cashier
  • guestWebSite (String) – (required) A URL where guests can login to see their balances and transaction history
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines

Example response body:

{
   "result": "success",
   "checkNumber": "5657",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100",
   "openTime": "2024-05-01 12:00:00 -05:00",
   "itemDiscounts": [],
   "multiItemDiscounts": [],
   "subtotalDiscounts": [],
   "serviceChargeDiscounts": [],
   "customerName": "John Doe",
   "tierName": "Standard",
   "printedCardNumber": "011235813213455",
   "maskedCardNumber": "***3455",
   "pointsBalances": [],
   "rewardBalances": [],
   "changedWalletContents": [],
   "posMessages": ["Guest has earned Reward Dollars for next visit!"],
   "guestWebSite":"www.fake.test",
   "receiptText": {}
}
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Simulate Accrual And Redemption

POST check/simulateAccrualAndRedemption.json

The check simulate accrual and redemption request is similar to the post and accrue points with auto-redeem request, with the difference that no points or rewards are actually applied. Instead, this endpoint takes in a check (with the same parameters as in the previous endpoint) and additionally a list of already applied rewards, the manner in which rewards are to be selected (either automatic or manual and specified with the request), and the details of the receipt printer associated with the request. If successful, it will return the applicable discounts (see DiscountItem), a list of attempted rewards that cannot be applied (including any previously applied rewards that are no longer applicable) and a new receipt text.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "autoActivateCard": false,
   "terminal": "1",
   "operator": "0",
   "rewardSelectionMode": {
      "mode": "automatic",
      "chosenRewards": []
   },
   "potentialUnitItems":[],
   "receiptSettings": [
      {
         "maxWidth": 40,
         "name": "myReceipt"
      }
   ],
   "potentialUnitItemDiscounts": []
}

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic, manual, or applicable_rewards reward selection. See RewardSelectionMode for details.
  • potentialUnitItems (List[Object]) – (required) A sequence of items which are dispensed by weight or volume and which are available to the guest. This is separate from items which have already been inserted into the check. See PotentialUnitItem for details.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
  • potentialUnitItemDiscounts (List[Object]) – (required) List of discounts that have been applied to potential unit items. See WalletInformation for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • pxTransactionId (Long) – (required) Paytronix transaction ID
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that could be applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts that could be applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of applicable discounts which concern the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • serviceChargeDiscounts (List[Object]) – (required) The list of serviceCharge discounts that could be applied to the check. See ServiceChargeDiscount for the format of the individual objects
  • rewardsToRemove (List[Object]) – (required) The list of rewards specified with the request that are inapplicable for the given check. See RewardToRemove for the format of the individual objects
  • availableUnitDiscounts (List[Object]) – (required) The list of unit discounts which have not been applied, but could be. See AvailableUnitDiscount for the format of the individual objects
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines
  • customerName (String) – (required) The customer’s name
  • tierName (String) – (required) The tier label for this customer
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • accountCode (Int) – (optional) Unique identifier for the account associated with the accrual
  • discountsNotApplied (List[Object]) – (required) The list of rewards specified in the request that could not be applied to the given check. See RewardNotApplied for details
  • pointBalances (List[Object]) – (required) The list of the remaining quantity of all points on the given card. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for the format of the individual objects
  • changedWalletContents (List[Object]) – (required) The list of visible points changes. See ChangedPointInfo for the format of the individual objects
  • posMessages (List[String]) – (required) A list of messages to be displayed to the cashier
  • guestWebSite (String) – (required) A URL where guests can login to see their balances and transaction history

Example response body

{
   "result": "success",
   "checkNumber": "5657",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100",
   "openTime": "2024-05-05 13:22:10 -05:00",
   "pxTransactionId": 11269326,
   "itemDiscounts": [],
   "multiItemDiscounts": [],
   "subtotalDiscounts": [],
   "serviceChargeDiscounts": [],
   "rewardsToRemove": [],
   "availableUnitDiscounts": [],
   "receiptText": {
      "myReceipt": [
         "Card #: ***12421",
         "Standard",
         "----------------------------------------",
         "Stored Value Information",
         "Current Balance   :               5.00",
         "----------------------------------------",
         "Visits Earned                          2",
         "Points Wallet                        41",
         "----------------------------------------",
         "Whole check wallet                 0.000",
         "----------------------------------------"
      ]
   },
   "customerName": "John Doe",
   "tierName": "Standard",
   "printedCardNumber": "011235813213455",
   "accountCode": 986,
   "discountsNotApplied": [],
   "rewardBalances": [],
   "pointBalances": [
       {
           "balance": "2",
           "pointName": "Coffee Points",
           "walletCode": 2
       }
   ],
   "changedWalletContents": [],
   "posMessages": ["Guest has earned Reward Dollars for next visit!"],
   "guestWebSite":"www.fake.test"
}
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Simulate Coupon

POST check/simulateCoupon.json

The check simulate coupon request is similar to the simulate accrual and redemption endpoint. It finds any rewards connected to the supplied coupon code, and attempts to apply them to the check. Its return values differ in that only one itemDiscount, subtotalDiscount, or availableUnitDiscount will be returned, and no list of rewards to remove will be returned, as no card is associated with the call. It should be possible to call this endpoint followed by a call to simulateAccrualAndRedemption, or vice versa, in order to apply rewards from both a coupon and a loyalty account. A call to this endpoint should be followed with a call to postAndAccruePointsWithRedeem to finalize the check, with the selected discounts present in the check items.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic, manual, or applicable_rewards reward selection. See RewardSelectionMode for details.
  • potentialUnitItems (List[Object]) – (required) A sequence of items which are dispensed by weight or volume and which are available to the guest. This is separate from items which have already been inserted into the check. See PotentialUnitItem for details.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
  • couponCode (String) – (required) A coupon code to attempt to apply to a check
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that could be applied to the check. See ItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of applicable discounts which concern the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • couponsToRemove (List[Int]) – (required) The list of coupon IDs to remove from the check before applying item and subtotal discounts.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Post And Accrue Points With Redeem

POST check/postAndAccruePointsWithRedeem.json

The check post and accrue points with redeem request is meant to follow a call to POST check/simulateAccrualAndRedemption.json, enabling you to choose the discounts that are applied. These will be passed in through the Check object. Its arguments are almost identical to the POST check/postAndAccruePointsWithAutoRedeem.json endpoint, merely requiring the addition of a receiptSettings object, and not needing the autoActivateCard argument. If successfull, it will return a receipt.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "terminal": "1",
   "operator": "0",
   "receiptSettings": [
      {
         "maxWidth": 40,
         "name": "myReceipt"
      }
   ]
}

The check post request allows for a full POS check to be submitted to the PXS for diagnostic or data analysis purposes.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (optional) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • customerName (String) – (required) The customer’s name
  • tierName (String) – (required) The tier label for this customer
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • accountCode (Int) – (required) Unique identifier for the account associated with the accrual
  • pxTransactionId (Long) – (required) Paytronix transaction ID
  • pointBalances (List[Object]) – (required) The list of the remaining quantity of all points on the given card. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for the format of the individual objects
  • changedWalletContents (List[Object]) – (required) The list of visible points changes. See ChangedPointInfo for the format of the individual objects
  • posMessages (List[String]) – (required) A list of messages to be displayed to the cashier
  • guestWebSite (String) – (required) A URL where guests can login to see their balances and transaction history
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines

Example response body

 {
   "result": "success",
   "checkNumber": "5657",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100",
   "openTime": "2024-05-05 13:22:10 -05:00",
   "customerName": "John Doe",
   "tierName": "Standard",
   "printedCardNumber": "011235813213455",
   "accountCode": 986,
   "pxTransactionId": 11269326,
   "rewardBalances": [],
   "pointBalances": [
       {
           "balance": "2",
           "pointName": "Coffee Points",
           "walletCode": 2
       }
   ],
   "changedWalletContents": [],
   "posMessages": ["Guest has earned Reward Dollars for next visit!"],
   "guestWebSite":"www.fake.test",
   "receiptText": {
      "myReceipt": [
         "Card #: ***12421",
         "Standard",
         "----------------------------------------",
         "Stored Value Information",
         "Current Balance   :               5.00",
         "----------------------------------------",
         "Visits Earned                          2",
         "Points Wallet                        41",
         "----------------------------------------",
         "Whole check wallet                 0.000",
         "----------------------------------------"
      ]
   }
}
"result": "couponSuccess"
JSON Parameters:
 
  • result (String) – (required) couponSuccess
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]

Example response body

{
   "result": "couponSuccess",
   "checkNumber": "5657",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100",
   "openTime": "2024-05-05 13:22:10 -05:00"
}
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Get Check

GET check/check.json

The get check request allows an integrator to retrieve a check that had been previously posted. Checks that are posted may require up to 24 hours to be processed before they are availible via this endpoint.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • number (String) – (required) Check number of the desired check.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • check (Object) – (required) The requested check. See Check for details.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failed
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Post and Accrue Points

POST check/postAndAccruePoints.json

The check post and accrue points request allows for a simplified one-step flow for posting a check for analysis and accruing points with one action, equivalent to using POST check/computePointAccrual.json to compute a point accrual Add/Redeem Request then submitting it via POST transaction/addRedeem.json and then submitting the check again via POST check/post.json. The only reason to use the multi-step flow is if the point accrual add/redeem needs to be tailored for special applications prior to submission.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "terminal": "1",
   "operator": "0",
   "receiptSettings": [
      {
         "maxWidth": 40,
         "name": "myReceipt"
      }
   ]
}

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active. Defaults to false
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • reply (Object) – (required) The add/redeem reply from the point accrual transaction. See AddRedeemReply for format.
  • customerName (String) – (required) The customer’s name
  • tierName (String) – (required) The tier label for this customer
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • pointBalances (List[Object]) – (required) The guest’s loyalty point balances. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for the format of the individual objects
  • changedWalletContents (List[Object]) – (required) The list of visible points changes. See ChangedPointInfo for the format of the individual objects
  • posMessages (List[String]) – (required) A list of messages to be displayed to the cashier
  • guestWebSite (String) – (required) A URL where guests can login to see their balances and transaction history
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines

Example response body

{
   "result": "success",
   "reply": {}, //see https://developers.paytronix.com/pxs_api_reference/transaction.html#jsonentity-AddRedeemReply
   "guestWebSite":"www.fake.test",
   "receiptText": {}
   "printedCardNumber": "011235813213455",
   "pointBalances": [
       {
           "balance": "2",
           "pointName": "Coffee Points",
           "walletCode": 2
       }
   ]
}
"result": "noWorkSuccess"
JSON Parameters:
 
  • result (String) – (required) noWorkSuccess
"result": "failed"
JSON Parameters:
 
  • result (String) – (required) failed
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Multi Post and Accrue Points

POST check/multiPostAndAccruePoints.json

The multi check post and accrue points request allows for a simplified one-step flow for posting a check for analysis and accruing points for each card when a check is split between two or more cards. This is equivalent to using POST check/postAndAccruePoints.json to compute a point accrual Add/Redeem Request and splitting it up into new Add/Redeem Requests, adjusting the point balances based the percentage of the check paid for by each card, submitting it via POST transaction/addRedeem.json, and then submitting the check. again via POST check/post.json.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cards (Object) – (required) A list of CardAmount objects. See CardAmount for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active. Defaults to false
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • reply (List[Object]) – (required) A list of single point accrual result objects. Successes will contain the AddRedeemReply and the receipt text, failures will contain the error code and error message. See POST check/postAndAccruePoints.json for result formats.
"result": "noWorkSuccess"
JSON Parameters:
 
  • result (String) – (required) noWorkSuccess
"result": "failed"
JSON Parameters:
 
  • result (String) – (required) failed
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Redeem Only

POST check/redeemOnly.json

The redeem only request can run an add-redeem to redeem rewards against a given check, returning a list of discounts to insert.

Example request body

{
   "merchantId": 1738,
   "storeCode": "0",
   "check": {}, //see Example Check for details
   "cardInfo": {
         "printedCardNumber": "011235813213455"
   },
   "terminal": "1",
   "operator": "0",
   "rewardSelectionMode": {
      "mode": "manual",
      "chosenRewards": [
         {
            "walletCode": 50,
            "amount": 1.0
         }
      ]
   }
}

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (String) – (required) The POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic, manual, or applicable_rewards reward selection. See RewardSelectionMode for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • pxTransactionId (Long) – (required) Unique Long value to identify this transaction
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of whole-check discounts applied to the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • serviceChargeDiscounts (List[Object]) – (required) The list of serviceCharge discounts that could be applied to the check. See ServiceChargeDiscount for the format of the individual objects
  • chosenRewardsNotApplied (List[ChosenReward]) – (required) List of chosen rewards that were unable to be applied to the check. See ChosenReward for the format of the individual objects
  • pointBalances (List[Object]) – (required) The list of the remaining quantity of all points on the given card. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for the format of the individual objects
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines
  • changedWalletContents (List[Object]) – (required) The list of visible points changes. See ChangedPointInfo for details
  • posMessages (List[String]) – (required) A list of messages to be displayed to the cashier
  • guestWebSite (String) – (required) A URL where guests can login to see their balances and transaction history
  • customerName (String) – (required) The customer’s name
  • tierName (String) – (required) The tier label for this customer
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • anonymousAccountToken (String) – (optional) Unique String value to identify the guest.

Example response body

{
   "result": "success",
   "checkNumber": "5657",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100",
   "openTime": "2024-05-05 13:22:10 -05:00",
   "pxTransactionId": 11269326,
   "itemDiscounts": [],
   "multiItemDiscounts": [],
   "subtotalDiscounts": [],
   "serviceChargeDiscounts": [],
   "chosenRewardsNotApplied": [],
   "rewardBalances": [],
   "receiptText": {},
   "guestWebSite":"www.fake.test",
   "customerName": "John Doe",
   "tierName": "Standard",
   "printedCardNumber": "011235813213455",
   "pointBalances": [
       {
           "balance": "2",
           "pointName": "Coffee Points",
           "walletCode": 2
       }
   ],
   "changedWalletContents": [],
   "posMessages": []
}
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.
"result": "noRewardsApplied"
JSON Parameters:
 
  • result (String) – (required) noRewardsApplied
  • printedCardNumber (String) – (required) The printed card number associated with the account.
  • pointBalances (List[Object]) – (required) The list of the remaining quantity of all points on the given card. See PointInfo for the format of the individual objects
  • rewardBalances (List[Object]) – (required) The list of the remaining quantity of all rewards on the given card. See RewardPointInfo for the format of the individual objects
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines

Check Post

POST check/post.json

The check post request allows for a full POS check to be submitted to the PXS diagnostic or data analysis purposes, as well as the recording of billing events for our online ordering integrations. Functions similarly to POST check/uploadBatches.json, only this endpoint uploads only a single check.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • check (Object) – (required) POS check to post. See Check for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • visitCode (String) – (required) A generated VisitCode based off the submitted check
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • visitCode (String) – (required) A generated VisitCode based off the submitted check

Post Price Match Discounts

POST check/priceMatchDiscounts.json

The post price match discounts request takes a list of Price Per Unit (PPU) Discounts grouped by store and passes it to the PXS for price match purposes.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A store code to uniquely identify the store where this transaction occurred.
  • priceMatchDiscounts (List[Object]) – (required) List of Price Match Discounts to post per store. See PriceMatchDiscountRecord for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure

Get Price Match Discounts By Store Code

GET check/priceMatchDiscounts.json

The get price match discounts request returns a list of Price Per Unit (PPU) Discounts for the specified store.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A store code to uniquely identify the store where this transaction occurred.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • priceMatchDiscounts (List[Object]) – (required) List of Price Match Discounts for the given store. See PriceMatchDiscountRecord for details.
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that could be applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts that could be applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of whole-check discounts that could be applied to the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • anonymousAccountToken (String) – (optional) Unique String value to identify the guest.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure

Get All Price Match Discounts

GET check/allPriceMatchDiscounts.json

The get price match discounts request returns a list of all Price Per Unit (PPU) Discounts grouped by store code for the given merchant.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • PriceMatchDiscountRecordsForStoreCode (List[Object]) – (required) List of Price Match Discounts for the given merchant. See PriceMatchDiscountRecordsForStoreCode for details.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure

Get Reward Details

GET check/rewardDetails.json

The reward details endpoint obtains detailed information about a reward wallet’s configuration, including applicable item IDs and reward conditions.

Example request for a single wallet code:

https://m123.api.pxslab.com/rest/24.12/check/rewardDetails.json?merchantId=5555&walletCodes[]=58&storeCode=Store123

Example request for multiple wallet codes:

https://m123.api.pxslab.com/rest/24.12/check/rewardDetails.json?merchantId=5555&walletCodes[]=58&walletCodes[]=45&storeCode=Store123

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where the redemption will take place.
  • walletCodes (Seq[Int]) – (required) Code number for the wallet(s). This will never change for a particular wallet unless Paytronix makes a specific change to do so. For example, wallet code 0 might be associated with “Points”.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • wallets (List[Object]) – (required) Wallets specified in the request. See Wallets for details.

Reply Objects

AvailableUnitDiscount

This object represents a per-unit discount which is available to the guest, and can be used to reduce the unit price of one or more which are not yet in the check as they are dispensed (generally in such a way as is visible to the guest), up to a maximum quantity equal to maxEligibleUnits. Only one line item should be discounted per AvailableUnitDiscount per check. That is, if there were two 1oz Strawberry Almond Yogurt items in the check, only one of them should be discounted by a single AvailableUnitDiscount even if the maxEligibleUnits is greater than or equal to 2.

Eligible item IDs are contained within possibleUses, and each may have a different discount value (primarily because we don’t want to reduce an item’s unit price below zero).

When a discount of this type is applied the check, the relevant MenuItem or ComboItem should have a DiscountItem appended where the price value is equal to the applied unitDiscount times the item’s quantity, the walletCode should be set to the walletcode of this object, and the walletQuantity should be equal to the unitDiscount applied to that item.

Note: This field is only populated if the potentialUnitItems field is populated in the request.

JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique
  • name (String) – (required) Human-readable name of discount
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant
  • possibleUses (List[Object]) – (required) See PossibleDiscount
  • maxEligibleUnits (Decimal) – (optional) Maximum units to which this discount can be applied.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • priority (Integer) – (required) The priority in which the reward should be applied
PossibleDiscount

This object represents a per-unit discount which could be applied to a specific type of item (e.g. ounces of almond milk yogurt).

Note: Only ever appears as a sub-element of AvailableUnitDiscount

JSON Parameters:
 
  • itemId (String) – (required) The ID of the item to which this discount could be applied.
  • unitDiscount (Decimal) – (required) Represents the per-unit discount that should be applied to an applicable item, e.g. if the value is 1.00 and there are two units of the item, the item’s total price should total discount should be reduced by 2.00. This will be a positive number.
Category
JSON Parameters:
 
  • categoryType (String) – (required) Either “major”, “minor”, or “promo”. Type of category if there are multiple types. Use “major” if there are no distinct category types.
  • id (String) – (required) Identifier for the category. This identifies the category in the POS database.
  • name (String) – (optional) Human-readable name for the category.
CategoryItemCode

The contents of Paytronix-generated categories associated with items in the check body.

JSON Parameters:
 
  • categoryCode (String) – (required) Unique code associated with this item or category
  • itemType (String) – (required) A human-readable item type. One of Item, Minor, Major or Promo
ChangedPointInfo
JSON Parameters:
 
  • pointName (String) – (required) Name of the wallet earned
  • walletCode (Integer) – (required) A numeric identifier for a specific wallet, unique for a given merchant
  • quantity (BigDecimal) – (required) Quantity earned
Check
JSON Parameters:
 
  • header (Object) – (required) The header to the check. Contains details about the check as as whole, such as check number, number of seats, time opened, etc. See Header for format
  • items (List[Object]) –

    (required) List of individual check items. These are further broken down into separate types, identified by the type field of each:

    • Single menu items (MenuItem) such as entrees, appetizers, and beverages.
    • Combo items (ComboItem) which represent combo meals, such as burger and fries for a bundled price.
    • Discount items (DiscountItem) which alter the check total (typically by reducing it) and may discount a particular menu item, modifier, or the whole check.
    • Service charge items (ServiceChargeItem) which represent additional nontaxed service charges such as gift card purchases or delivery fees.
    • Tender items (TenderItem) which represent payments or other similar items, such as credit card payments, gift card payments, loyalty card swipes, or comp card payments.

    Ideally the check items should be in the same order they visually appear on the check

  • totals (Object) – (required) The totals at the end of the check. See Totals for format

Example check:

{
"header": {
  "cashier": "0",
  "closeTime": "2024-05-05 13:22:10 -05:00",
  "isReturn": false,
  "number": "-1",
  "openTime": "2024-05-05 13:22:10 -05:00",
  "revenueCenterName": "",
  "revenueCenterNumber": 1,
  "seatCount": 0,
  "tableNumber": "",
  "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100"
},
"items": [
  {
        "type": "menuItem",
        "itemId": "FUELID",
        "name": "Regular Fuel",
        "seat": 1,
        "referenceLine": "",
        "quantity": 12.0,
        "categories": [
          {
                "categoryType": "major",
                "id": "-1"
          }
        ],
        "isVoided": false,
        "isTaxable": true,
        "price": 12.0,
        "fullPrice": 12.0,
        "modifiers": [],
        "discounts": []
  },
  {
        "type": "menuItem",
        "itemId": "1126342",
        "name": "Pizza Slice",
        "seat": 1,
        "referenceLine": "",
        "quantity": 1.0,
        "categories": [
          {
                "categoryType": "major",
                "name": "Food",
                "id": "10"
          },
          {
                "categoryType": "minor",
                "name": "Hot Foods",
                "id": "125"
          }
        ],
        "isVoided": false,
        "isTaxable": true,
        "price": 12.0,
        "fullPrice": 12.0,
        "modifiers": [
          {
                "itemId": "456",
                "name": "Pepperoni",
                "quantity": "1",
                "price": "0.50",
                "categories": [
                  {
                        "categoryType": "minor",
                        "id": "45666"
                  }
                ]
          }
        ],
        "discounts": []
  },
  {
        "type": "discountItem",
        "itemId": "201",
        "name": "Reward Dollars",
        "quantity": "1",
        "price": "-2.00",
        "discountSource": "loyalty",
        "walletCode": 14,
        "walletQuantity": "2.00"
  },
  {
        "type": "serviceChargeItem",
        "itemId": "301",
        "name": "Gift Card Sale",
        "referenceLine": "GC-XXXXXX**XXXXXX",
        "quantity": "1",
        "isTaxable": false,
        "price": "5.00"
  }
],
"totals": {
  "subTotal": 10.50,
  "taxTotal": 0.11,
  "discountTotal": -2.0,
  "serviceChargeTotal": 5.0,
  "checkTotal": 15.61,
  "tipTotal": 0.0,
  "tenderTotal": 0.0
}
}
ChosenReward
JSON Parameters:
 
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant
  • amount (Decimal) – (required) Represents the wallet balance to redeem off of the account/card, usually equal to the quantityRedeemed field from the simulateAccrualAndRedemption response. May differ from the actual monetary value of the discount if a fixed-type discount, or equal if an open-type discount.
ComboItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a menu item. Must always be "comboItem".
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the combo item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the combo item. Typically a positive amount, unless voided. Should be calculated as unit price * quantity.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • modifiers (List[Object]) – (optional) Can be empty. A list of any modifiers (such as condiments) attached to the combo item. Defaults to empty. See Modifier for format
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the combo item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • items (List[Object]) – (required) List of menu items (see MenuItem for format) to be included in the combo
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.
CreditCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a credit card detail. Must always be "creditCard".
  • cardholder (String) – (optional) Name of the cardholder as captured from the credit card.
  • cardType (String) – (optional) Type of credit card. Must be one of “Visa”, “MasterCard”, “American Express”, “Diners Club”, “Discover”, “JCB”, or “other”.
  • iin (String) – (optional) IIN (first 6 digits) from credit card number.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from credit card number.
  • expiration (String) – (optional) Expiration date of the credit card. Format yyyy-MM-dd. Credit cards typically have no day of month component in the expiration date; please enter “01” in that case. For example, if the credit card expires 05/15, this field should be set to 2015-05-01.
DiscountItem

Note: If this is a Paytronix discount then it should have the walletCode and walletQuantity fields populated if it is to be sent to the POST postAndAccruePointsWithRedeem endpoint, otherwise the reward will never be redeemed from the guest’s account.

JSON Parameters:
 
  • type (String) – (required) Identifies this item as a discount item. Must always be “discountItem”.
  • itemId (String) – (required) Identifier for the discount item. This identifies the discount item in the Paytronix database, not the particular line item in the check.
  • multiItemDiscountId (Integer) – (optional) Identifier for a combo reward. This identifies the item as part of a combo reward. Use value of discountObjectNumber from the simulateAccrualAndRedemption response, MultiItemDiscount object.
  • name (String) – (optional) Human-readable description of the discount item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the discount item, if any.
  • quantity (Decimal) – (optional) Quantity of the discount item purchased. Typically "1". Defaults to 1.
  • isVoided (Boolean) – (optional) true if the discount item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the discount item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the discount item. Typically a negative amount (which reduces the check total), unless voided.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • discountSource (String) – (optional) One of "other", "loyalty", "coupon"
  • walletCode (Integer) – (optional) A numeric identifier for a specific type of discount, unique for a given merchant. Populated based on the walletCode field in the ItemDiscount, SubTotalDiscount, or AvailableUnitDiscount which was applied. Must be present for Loyalty and Coupon Discounts
  • walletQuantity (Decimal) – (optional) Quantity of the wallet which was used. Populated based on the quantityRedeemed field in the ItemDiscount, SubTotalDiscount, ServiceChargeDiscount, or MultiItemDiscount objects, or the unitDiscount field in a PossibleUse, depending on how the discount was applied to the check. Must be present for Loyalty Discounts
  • couponId (Integer) – (optional) Unique identifier of the coupon from which this reward came. Must be present for Coupon Discounts

Example:

{
   "type": "discountItem",
   "itemId": "201",
   "name": "Reward Dollars",
   "quantity": "1",
   "price": "-2.00",
   "discountSource": "loyalty",
   "walletCode": 14,
   "walletQuantity": "2.00"
}

Example:

{
   "type": "discountItem",
   "itemId": "251",
   "name": "Free Pizza",
   "quantity": "1",
   "price": "-9.99",
   "discountSource": "loyalty",
   "walletCode": 7,
   "walletQuantity": "1"
}
GiftCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a gift card detail. Must always be "giftCard".
  • pxTransactionId (Long) – (optional) Paytronix transaction ID, if available and for a Paytronix gift card.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from gift card number.
Header
JSON Parameters:
 
  • number (String) – (required) Check number that appears on POS receipt. If this number is not guaranteed to be unique within the business day at the particular store, provide ‘uniqueIdentifier’ field as well. Maximum of 255 characters.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • isReturn (Boolean) – (required) true if the check is a return check, i.e., a check containing one or more returned items. A check being marked this way does not affect the interpretation of the line items, it’s merely used as an additional data point for various analysis such as fraud analysis.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • closeTime (String) – (optional) Date and time the check was closed, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • seatCount (Integer) – (optional) Number of seats.
  • tableNumber (String) – (optional) Table number or identifier.
  • revenueCenterNumber (Integer) – (optional) Identifier for revenue center (cost center) that the check was located in.
  • revenueCenterName (String) – (optional) Human readable description for revenue center (cost center) that the check was located in.
  • cashier (String) – (optional) Cashier (operator) ID.
  • properties (Map[String]) – (required) Can be empty. Additional POS-specific properties as strings. Defaults to empty.
  • isVoid (Boolean) – (optional) Flag to indicate whether the check is voided.
  • isCatering (Boolean) – (optional) Flag to indicate whether the check is for a catering order.
  • orderMethod (String) – (optional) Order method of the check. Possible values are: in store, online web, online app, online app - android, online app - ios, call in, call center, drive through, kiosk, third party ordering, smart home device ordering, other
  • deliveryMethod (String) – (optional) Delivery method of the check. Possible values are: dine in, pick up, in house delivery, curbside, drive through, third party delivery, other

Example

{
   "cashier": "0",
   "closeTime": "2024-05-05 13:22:10 -05:00",
   "isReturn": false,
   "number": "1",
   "openTime": "2024-05-05 13:22:10 -05:00",
   "revenueCenterName": "",
   "revenueCenterNumber": 1,
   "seatCount": 0,
   "tableNumber": "",
   "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100"
}
ItemDiscount

Discounts that can be applied to specific a menu item within the check, or to a specific modifier of a menu item within the check, will be returned here.

JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique. If not a MultiItemDiscount, use value of discountObjectNumber from the simulateAccrualAndRedemption response.
  • multiItemDiscountId (Integer) – (optional) Identifier for a combo reward. This identifies the item as part of a combo reward.
  • name (String) – (required) Human-readable name of discount
  • referenceLine (String) – (optional) Directly corresponds to the referenceLine field of a menu or combo item in the request, and indicates that the discount should be applied to that specific item.
  • menuItemId (String) – (required) Directly corresponds to the itemId field of a menu or combo item in the request. Points to which item the discount should be nested under.
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • quantityDiscounted (Decimal) – (required) Quantity of the line item which is to be discounted.
  • unitDiscount (Decimal) – (required) This is the discount value divided by the quantityDiscounted. Usually ignored
  • discountType (String) – (required) One of “Percent”, “Dollar”, “ReducePrice”, “PerUnit”. Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • couponId (Integer) – (optional) ID of coupon, only returned in calls to simulateCoupon.
  • soonestExpirationDate (Date) – (optional) The earliest or soonest expiration date out of a list of reward point expiration dates. The format is yyyy-mm-dd.
  • priority (Integer) – (required) The priority in which the reward should be applied

Example:

{
   "id": "32",
   "name": "Two Dollars Off Item 3",
   "menuItemId": "Item 3",
   "discount": "2.00",
   "unitDiscount": "2.00",
   "discountType": "Dollar",
   "walletCode": 50,
   "quantityRedeemed": "1",
   "applyAutomatically": true,
   "priority": 1
}
ItemizedTotal
JSON Parameters:
 
  • itemizerType (String) – (required) Either "sales" or "tax", depending on what is itemized
  • id (String) – (required) Identifier for the itemizer
  • total (Decimal) – (required) Itemized amount
LoyaltyCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a loyalty card detail. Must always be "loyaltyCard".
  • pxTransactionId (Long) – (optional) Paytronix transaction ID, if available and for a Paytronix comp/loyalty.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from comp/loyalty card number.
MenuItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a menu item. Must always be "menuItem".
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the menu item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the menu item. Typically a positive amount, unless voided. Should be calculated as unit price * quantity. This should not include the prices of the modifiers.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • modifiers (List[Object]) – (optional) Can be empty. A list of any modifiers (such as condiments) attached to the menu item. Defaults to empty. See Modifier for format
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the single menu item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.

Example

{
   "type": "menuItem",
   "itemId": "FUELID",
   "name": "Regular Fuel",
   "seat": 1,
   "referenceLine": "",
   "quantity": 12.00,
   "categories": [{"categoryType": "major", "id": "-1"}],
   "isVoided": false,
   "isTaxable": true,
   "price": 12.00,
   "fullPrice": 12.00,
   "modifiers": [],
   "discounts": [],
   "consumedQuantity": "0"
}
Modifier
JSON Parameters:
 
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the menu item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the modifier. Typically a positive amount, unless voided. Should be calculated as unit price * quantity.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the single menu item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.
MultiItemDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique. Use value of multiItemDiscountId from the simulateAccrualAndRedemption response.
  • name (String) – (required) Human-readable name of discount
  • discountObjectNumber (String) – (required) POS discount number to apply when redeeming this wallet as a reward.
  • posItemId (String) – (required) Unique identifier for item in the point of sale system
  • items (List[Object]) – (required) A list of sub item discounts. See SubItemDiscount for format
  • discountType (String) – (required) One of “Percent”, “Dollar”, “ReducePrice”, “PerUnit”. Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant. Must be present for Loyalty Discounts
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. Must be present for Loyalty Discounts
  • totalDiscounted (Decimal) – (required) Total value discounted
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • priority (Integer) – (required) The priority in which the reward should be applied

Example

{
   "id": "33",
   "name": "Twenty Five Percent Off Combo",
   "discountObjectNumber": "1111",
   "posItemId": "Item 1 and 2 Combo",
   "items": [
      {
         "menuItemId": "Item 1",
         "discount": "2.00",
         "quantityDiscounted"" "1.00",
         "unitDiscount": "2.00"
      },
      {
         "menuItemId": "Item 2",
         "discount": "0.25",
         "quantityDiscounted"" "1.00",
         "unitDiscount": "0.25"
      }
   ],
   "discountType": "Percent",
   "walletCode": 51,
   "quantityRedeemed": "1",
   "totalDiscounted": "2.25"
   "applyAutomatically": true,
   "priority": 1
}
PointExpirationInfo
JSON Parameters:
 
  • quantity (Decimal) – (required) The quantity of reward that will expire
  • date (String) – (required) Expiration date
PointInfo
JSON Parameters:
 
  • pointName (String) – (required) The name of the point
  • walletCode (Integer) – (required) A numeric identifier for the point balance, unique for a given merchant
  • balance (Decimal) – (required) The quantity of the balance remaining on the card after the transaction
ReceiptSetting
JSON Parameters:
 
  • name (String) – (required) Name of receipt printer
  • maxWidth (Integer) – (required) Width in characters of receipt
RewardNotApplied

There are 10 defined instances for when a reward cannot be redeemed. Each instance has a reason code and a corresponding message to return to the user. All messages are configurable and default to "Invalid"

The following reason codes are used for this object:

  • reducedPriceGreaterThanTotal: Message for when the reward’s ‘Reduce To’ price is higher than the corresponding item’s total cost
  • invalidWalletCode: Message for when the reward’s wallet code is invalid
  • itemNotInCheck: Message for when there is no item in the check corresponding to the reward
  • chosenRewardAmountZeroOrNegative: Message for when the requested reward quantity is zero or negative
  • chosenRewardAmountTooHigh: Message for when the requested reward quantity is higher than the available reward quantity
  • minimumSpendNotMet: Message for when minimum spend amount is not met for the given check
  • minimumSpendAlreadyApplied: Message for when a minimum spend reward has already been applied to the given check
  • percentDiscountAlreadyApplied: Message for when a percent discount has already been applied to the given check
  • negativeSubtotal: Message for when applying the reward would result in a negative check total
  • Invalid: General message for when a reward is invalid
JSON Parameters:
 
  • message (String) – (required) The message to return to the guest with the reason the specified reward was not applied, this is custom language set by the merchant. Defaults to "Invalid"
  • reason (String) – (required) Reason code used to determine which message to send.
  • walletCode (String) – (required) A numeric identifier for the specified discount that could not be applied, unique for a given merchant.
  • walletName (String) – (required) The name of the reward that could not be applied.

Example of RewardNotApplied:

{
  "message": "Minimum spend amount not met",
  "reason": "minimumSpendNotMet",
  "walletCode": 3,
  "walletName": "Free Coffee"
}
RewardPointInfo
JSON Parameters:
 
  • pointName (String) – (required) The name of the discount
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant
  • discountObjectNumber (String) – (required) POS discount number to apply when redeeming this wallet as a reward
  • balance (Decimal) – (required) The quantity of the reward remaining on the card after the transaction
  • expirationDates (List[Object]) – (required) A list of the dates that specified quantities of the reward will expire. See PointExpirationInfo for the format of the objects
  • additionalExpiringBalance (Decimal) – (required) The quantity of the reward that will expire later than the returned expirationDates
  • rewardType (String) – (optional) Either "FIXED_AMOUNT" or "OPEN_AMOUNT"
  • rewardValueType (String) – (optional) One of "PERCENT_DISCOUNT", "DOLLAR_DISCOUNT", "POS_DISCOUNT", "REDUCE_PRICE_TO", "PRECENT_OFF_CATEGORY", "PER_UNIT_DISCOUNT"

Example

{
   "additionalExpiringBalance": "0.000",
   "balance": "0.000",
   "discountObjectNumber": "56675",
   "expirationDates": [],
   "pointName": "Fuel Wallet",
   "rewardType": "FIXED_AMOUNT",
   "rewardValueType": "PER_UNIT_DISCOUNT",
   "walletCode": 71
}
RewardSelectionMode

Reward redemption can be run under three “modes”: "automatic", "manual", or "applicable_rewards".

In "automatic" mode, the PXS chooses which rewards to apply to a check from the set of rewards that are available to the guest and are applicable to the check. The PXS will only return a list of rewards that can be applied concurently.

In "manual" mode, the caller instead specifies which rewards they would like to redeem by wallet code and the PXS attempts to redeem only those rewards specified, returning to the caller whether or not those rewards were applied.

In "applicable_rewards" mode, the PXS will return all rewards that could be applied to the check, even if they cannot be applied concurrently. The integrator should only allow the guest to apply one reward per simulate request. Attempting to apply multiple rewards may fail.

JSON Parameters:
 
  • mode (String) – (required) One of "automatic" "manual" or "applicable_rewards"
  • chosenRewards (List[Object]) – (required only if manual) List of manually chosen rewards. See ChosenReward for the format of the objects

Example (manual)

{
   "mode": "manual",
   "chosenRewards": [
      {
         "walletCode": 41,
         "amount": 1
      }
   ]
}

Example (automatic)

{
   "mode": "automatic",
   "chosenRewards": []
}

Example (applicable_rewards)

{
   "mode": "applicable_rewards",
   "chosenRewards": []
}
RewardToRemove
JSON Parameters:
 
  • itemId (String) – (required) A numeric identifier for the specific reward to be removed
  • reason (String) – (required) States the reason why the reward was unable to be applied
  • referenceLine (String) – (optional) Directly corresponds to the referenceLine field of a menu or combo item in the request, and indicates that the discount should be applied to that specific item.

Example

{
   "itemId": "863",
   "reason": "item fully discounted",
   "referenceLine": "31324"
}
ServiceChargeItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a service charge item. Must always be "serviceChargeItem".
  • itemId (String) – (required) Identifier for the service charge. This identifies the service charge in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the service charge
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the service charge, if any.
  • quantity (Decimal) – (optional) Quantity of the service charge purchased. Typically "1". Defaults to 1.
  • isVoided (Boolean) – (optional) true if the service charge is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the service charge is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the service charge. Typically a positive amount, unless voided.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the single serviceCharge item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.

Example:

{
   "type": "serviceChargeItem",
   "itemId": "301",
   "name": "Gift Card Sale",
   "referenceLine": "GC-XXXXXX**XXXXXX",
   "quantity": "1",
   "isTaxable": false,
   "price": "5.00"
}
ServiceChargeDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique.
  • name (String) – (required) Human-readable name of discount.
  • referenceLine (String) – (optional) Reference line for the service charge discount, if any.
  • posItemId (String) – (required) Unique identifier for item in the point of sale system.
  • menuItemId (String) – (required) Directly corresponds to the itemId field of a ServiceChargeItem in the request.
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • quantityDiscounted (Decimal) – (required) Quantity of the line item which is to be discounted.
  • discountType (String) – (required) One of "Percent", "Dollar", "ReducePrice". Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts.
  • priority (Integer) – (required) The priority in which the reward should be applied

Example:

{
      "id": "718",
      "name": "Service Charge Dollar off",
      "referenceLine": "5",
      "posItemId": "2718",
      "menuItemId": "2718",
      "discount": "7.00",
      "quantityDiscounted": "1",
      "discountType": "Dollar",
      "walletCode": 9,
      "quantityRedeemed": "1",
      "applyAutomatically": true,
      "priority": 1
  }
SubItemDiscount
JSON Parameters:
 
  • referenceLine (String) – (optional) Reference line for the discount item, if any.
  • menuItemId (String) – (required) Directly corresponds to the itemId field of a menu or combo item in the request.
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • quantityDiscounted (Decimal) – (required) Quantity of the line item which is to be discounted.
  • unitDiscount (Decimal) – (required) This is the discount value divided by the quantityDiscounted.
SubTotalDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique
  • name (String) – (required) Human-readable name of discount
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • discountType (String) – (required) One of "Percent", "Dollar", "ReducePrice", "PerUnit". Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • couponId (Integer) – (optional) Id of coupon, only returned in calls to simulateCoupon.
  • priority (Integer) – (required) The priority in which the reward should be applied

Example:

{
   "id": "34",
   "name": "Five Dollars Off Check",
   "discount": "5.00",
   "discountType": "Dollar",
   "walletCode": 52,
   "quantityRedeemed": "1",
   "applyAutomatically": true,
   "priority": 1
}
TenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a tender item. Must always be "tenderItem".
  • itemId (String) – (required) Identifier for the tender. This identifies the tender in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the tender
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the tender, if any.
  • amount (Decimal) – (required) Amount of the tender. Typically a negative amount (reducing the check total). Can be 0, such as in the case of loyalty cards that are not being used as comp cards.
  • detail (Object) –

    (optional) Not present if a cash tender or not one of the available types (credit card, gift card, or loyalty card). Gives additional detail about the tender. Available types are

Example:

{
   "type": "tenderItem",
   "itemId": "102",
   "name": "GC Redeem",
   "seat": 1,
   "referenceLine": "PX-ref_line",
   "amount": "-5.00",
   "detail": {
      "masked": "1234",
      "pxTransactionId": 123456,
      "type": "giftCard"
   }
}
Totals
JSON Parameters:
 
  • subTotal (Decimal) – (required) Sub total of menu, combo, and discount items. Calculated by summing the price field of each menu, combo, and discount item.
  • taxTotal (Decimal) – (required) Tax total. Typically calculated by taking the subTotal and multiplying by some appropriate tax rate.
  • discountTotal (Decimal) – (required) Total amount of discounts. Sign is relative to check total – that is, a negative amount indicates the check total was reduced by that amount. Calculated by summing the price of all discounts, no matter where they appear.
  • serviceChargeTotal (Decimal) – (required) Total of service charges
  • checkTotal (Decimal) – (optional) Check total before tenders and tips. checkTotal can be calculated from the individual totals via the following formula: subTotal + taxTotal + serviceChargeTotal
  • tipTotal (Decimal) – (optional) Total of tips, if known.
  • tenderTotal (Decimal) – (required) Total of tenders applied to the check. Typically a negative amount (reducing the check total).
  • itemizedTotals (List[Object]) – (required) Can be empty. Additional POS-specific itemized totals, such as totals by reporting group or similar. Defaults to empty. See ItemizedTotal for format
Wallets
JSON Parameters:
 
  • autoRedeem (Boolean) – (required) Derives from the applyAutomatically flag in discount reply objects. Used by Check service integrations that respect this flag.
  • categoryItemCodes (List[Object]) – (required) A list of the contents of Paytronix-generated categories appended to items in the check body. This list contains item codes associated with applicable items and/or categories. See CategoryItemCode for details.
  • discountObjectNumber (Integer) – (required) POS discount number to apply when redeeming this wallet as a reward.
  • posItemId (Integer) – (required) Identifier for product(s). See productType for how to interpret this field.
  • productDefinition (String) – (required) POS-specific definition for POSes or applications where productType and productId are not flexible enough.
  • productId (String) – (required) Identifier for product(s). See productType for how to interpret this field.
  • productType (Integer) – (required) Type of POS product associated with wallet. See ProductType
  • rewardType (Integer) – (required) Type of reward. See RedeemWalletContent for details.
  • scale (Integer) – (required) Number of digits after the decimal place for balances of this wallet.
  • valueAmount (String) – (required) Percentage off, dollar off, or particular POS discount as defined by valueFlag. See RedeemWalletContent for details.
  • valueType (Integer) – (required) Value type of reward. See RedeemWalletContent for details.
  • walletBogoConfiguration (Object) – (optional) The check service specific BOGO (Buy One Get One) configuration to determine whether the reward can be applied. See LoadMapWalletBogoConfiguration for details.
  • walletCode (Integer) – (required) Identifying code for the wallet.
  • walletComboConditions (List[Object]) – (required) The check service specific combo conditions to determine whether the reward can be applied. See LoadMapWalletRewardCondition for details.
  • walletContents (Integer) – (required) Contents of wallet, see See WalletContents for details.
  • walletName (String) – (required) Name of the wallet.
  • walletTags (List[Object]) – (required) Tags for this wallet.See WalletTag for details.
  • walletType (Integer) – (required) Type of wallet, see See WalletType for details.
WalletInformation
JSON Parameters:
 
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant
  • amount (Decimal) – (required) The amount to be redeemed from the wallet

Example

{
   "subTotal":10.00,
   "taxTotal": 0.10,
   "discountTotal": -2.00,
   "serviceChargeTotal": 5.00,
   "checkTotal": 15.10,
   "tipTotal": 0.0
   "tenderTotal": -5.00
}
PriceMatchDiscountRecord
JSON Parameters:
 
  • itemId (String) – (required) Identifier for the PPU item. This identifies the PPU item in the Paytronix database, not the particular line item in the check.
  • originalPrice (Decimal) – (required) Original Price for PPU item. (Positive Number!)
  • discountAmount (Decimal) – (required) Price Match Discount Amount for PPU item. (Positive Number!)
PriceMatchDiscountRecordsForStoreCode
JSON Parameters:
 
  • storeCode (String) – (required) A store code to uniquely identify the store.
  • priceMatchDiscounts (List[Object]) – (required) List of Price Match Discounts for this store. See PriceMatchDiscountRecord for details.

Error Codes

The following are the possible codes and messages that can be returned by the Check Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
check_storage.upload_check.no_batches No batches given as multipart attachments
check_storage.upload_check.invalid_request_part [Varies, pertains to an invalid part of the check request]
check_storage.upload_check.invalid_check Check data could not be parsed: [Varies, pertains to nature of the parsing error]
check_storage.upload_check.xml_not_supported XML format not currently supported
check_storage.upload_check.avro_not_supported Avro format not currently supported
check_storage.get_check.not_found Check not found

Using Coupons

It is possible to use multi-use coupons with the Check Service. Every Coupon will be associated with a reward along with conditions for applying that reward to a given check. The main difference between rewards and coupons is that although both are associated with a redeemable wallet, a coupon code can be used multiple times by different users, including non-loyalty users, unlike loyalty rewards whose balances decrement on use. Coupons should integrate smoothly with the rest of the Check Service flows, while changing no behavior if they are not used. To apply a coupon to a check, use the POST check/simulateCoupon.json endpoint, which has a similar return type to POST check/simulateAccrualAndRedemption.json. If loyalty rewards also need to apply to the check, that will necessitate an additional call to POST check/simulateAccrualAndRedemption.json. After the check is finalized, simply call POST check/postAndAccruePointsWithRedeem.json with the check information, which will do its usual work on top of recording the coupon usage. Changes to POST check/postAndAccruePointsWithRedeem.json are as follows:

  • CardInfo is now an optional field, so that rewards that are not directly associated with a card (in this case, from a coupon) can be processed
  • Discounts that come from coupon rewards should have the couponId set on their DiscountItem in the check. This will ensure both that the reward is not checked against what the optionally provided card has in its wallet, and that usage of the coupon is properly recorded

Additionally, representations of discounts are slightly different with coupons. For the objects DiscountItem, ItemDiscount, SubTotalDiscount, and AvailableUnitDiscount, we now need to include information on the source of the discount, be it a loyalty transaction, a coupon, or something entered in at the POS. The following fields are now present (except quantityRedeemed on AvailableUnitDiscount) on all of these fields.

  • String discountSource: (required) One of "other", "loyalty", "coupon"
  • Integer walletCode: (optional) A numeric identifier for a specific type of discount, unique for a given merchant. Must be present for Loyalty Discounts
  • Decimal quantityRedeemed: (optional) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. Must be present for Loyalty Discounts
  • Integer couponId: (optional) Unique identifier of the coupon from which this reward came. Must be present for Loyalty Discounts

If the discount is a loyalty discount (as previously all discounts created by the PXS were), the walletCode and quantity redeemed will be defined, and the discountsource will be "loyalty"

If the discount is a coupon discount, the couponId will be defined and the discountSource will be "coupon".

If the discount comes from the POS or is just neither loyalty nor coupon related, the discount source will be "other" and none of those fields will be defined