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.

Topics

General Flow - POS ¶

General Flow - Online Ordering ¶

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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:

B2B authentication

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
- Credit card (see CreditCardTenderItem)
- Gift card (see GiftCardTenderItem)
- Loyalty card (see LoyaltyCardTenderItem) Typically the amount of a loyalty card tender would be 0, as comp redemption affects the pre-tax total and would be entered as a discount in addition to the tracking tender.

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