.. _check_service: Check Service ============= The check service provides endpoints for posting check information and accruing points on checks. .. contents:: Topics General Flow - POS ~~~~~~~~~~~~~~~~~~ .. image:: pos_flow.png :align: center General Flow - Online Ordering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. image:: online_ordering_flow.png :align: center Request Objects ~~~~~~~~~~~~~~~ .. http:jsonentity:: 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). :jsonparam String itemId: *(required)* Identifier for this item. This identifies the item in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the item. :jsonparam List[Object] categories: *(required)* Can be empty. Any categories the menu item is associated with. See :http:jsonentity:`Category` for format :jsonparam Decimal pricePerUnit: *(required)* Per-unit price of the item. Expected to be positive. .. http:jsonentity:: cardAmount This object represents loyalty card information and the amount of the check paid by that guest. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details :jsonparam Decimal amountPaid: *(required)* The amount that was paid by this guest. Endpoints --------- Check Compute Point Accrual ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "check": {}, //see Example Check for details "cardInfo": { "printedCardNumber": "011235813213455" }, "autoActivateCard": false, "terminal": "1", "operator": "0" } The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam Boolean autoActivateCard: *(required)* ``true`` if the card should automatically be activated if it is not already active. Defaults to ``false`` :jsonparam String terminal: *(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. :jsonparam String operator: *(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. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object voidAddRedeem: *(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 :http:post:`transaction/voidAddRedeem.json` prior to the Add/Redeem. See :http:jsonentity:`VoidAddRedeem`. :jsonparam Object addRedeem: *(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 :http:post:`transaction/addRedeem.json`. See :http:jsonentity:`AddRedeem`. Example response body .. code:: javascript { "result": "success", "voidAddRedeem": {}, //see POST transaction/voidAddRedeem.json "addRedeem": {} //see POST transaction/addRedeem.json } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Compute Applicable Rewards ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam String terminal: *(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. :jsonparam String operator: *(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. :jsonparam Object rewardSelectionMode: *(required)* Identifies whether to use automatic, manual, or applicable_rewards reward selection. See :http:jsonentity:`RewardSelectionMode` for details. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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]`` :jsonparam List[Object] itemDiscounts: *(required)* The list of per-item discounts that could be applied to the check. See :http:jsonentity:`ItemDiscount` for the format of the individual objects :jsonparam List[Object] multiItemDiscounts: *(required)* The list of multi-item discounts that could be applied to the check. See :http:jsonentity:`MultiItemDiscount` for the format of the individual objects :jsonparam List[Object] subtotalDiscounts: *(required)* The list of whole-check discounts that could be applied to the check subtotal, or the whole check. See :http:jsonentity:`SubTotalDiscount` for the format of the individual objects :jsonparam List[Object] serviceChargeDiscounts: *(required)* The list of serviceCharge discounts that could be applied to the check. See :http:jsonentity:`ServiceChargeDiscount` for the format of the individual objects :jsonparam String anonymousAccountToken: *(optional)* Unique String value to identify the guest. :jsonparam String customerName: *(required)* The customer's name :jsonparam String tierName: *(required)* The tier label for this customer :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam String maskedCardNumber: *(required)* The masked card number associated with the account. :jsonparam List[Object] pointBalances: *(required)* The guest's loyalty point balances. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam List[Object] changedWalletContents *(required)* The list of visible points changes. See :http:jsonentity:`ChangedPointInfo` for the format of the individual objects :jsonparam List[String] posMessages *(required)* A list of messages to be displayed to the cashier :jsonparam String guestWebSite *(required)* A URL where guests can login to see their balances and transaction history :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines Example response body .. code:: javascript { "result": "success", "checkNumber": "5657", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100", "openTime": "0001-01-01 00:00:00 -00: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": {} } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Simulate Accrual And Redemption ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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 :http:jsonentity:`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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam Boolean autoActivateCard: *(required)* ``true`` if the card should automatically be activated if it is not already active. :jsonparam String terminal: *(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 :jsonparam String operator: *(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. :jsonparam Object rewardSelectionMode: *(required)* Identifies whether to use automatic, manual, or applicable_rewards reward selection. See :http:jsonentity:`RewardSelectionMode` for details. :jsonparam List[Object] potentialUnitItems: *(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 :http:jsonentity:`PotentialUnitItem` for details. :jsonparam List[Object] receiptSettings: *(required)* List of receipt settings. See :http:jsonentity:`ReceiptSetting` for details :jsonparam List[Object] potentialUnitItemDiscounts: *(required)* List of discounts that have been applied to potential unit items. See :http:jsonentity:`WalletInformation` for details .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String openTime: *(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]`` :jsonparam String uniqueIdentifier: *(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. :jsonparam Long pxTransactionId: *(required)* Paytronix transaction ID :jsonparam List[Object] itemDiscounts: *(required)* The list of per-item discounts that could be applied to the check. See :http:jsonentity:`ItemDiscount` for the format of the individual objects :jsonparam List[Object] multiItemDiscounts: *(required)* The list of multi-item discounts that could be applied to the check. See :http:jsonentity:`MultiItemDiscount` for the format of the individual objects :jsonparam List[Object] subtotalDiscounts: *(required)* The list of applicable discounts which concern the check subtotal, or the whole check. See :http:jsonentity:`SubTotalDiscount` for the format of the individual objects :jsonparam List[Object] serviceChargeDiscounts: *(required)* The list of serviceCharge discounts that could be applied to the check. See :http:jsonentity:`ServiceChargeDiscount` for the format of the individual objects :jsonparam List[Object] rewardsToRemove: *(required)* The list of rewards specified with the request that are inapplicable for the given check. See :http:jsonentity:`RewardToRemove` for the format of the individual objects :jsonparam List[Object] availableUnitDiscounts: *(required)* The list of unit discounts which have not been applied, but could be. See :http:jsonentity:`AvailableUnitDiscount` for the format of the individual objects :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines :jsonparam String customerName: *(required)* The customer's name :jsonparam String tierName: *(required)* The tier label for this customer :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam Int accountCode: *(optional)* Unique identifier for the account associated with the accrual :jsonparam List[Object] discountsNotApplied: *(required)* The list of rewards specified in the request that could not be applied to the given check. See :http:jsonentity:`RewardNotApplied` for details :jsonparam List[Object] pointBalances: *(required)* The list of the remaining quantity of all points on the given card. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam List[Object] changedWalletContents *(required)* The list of visible points changes. See :http:jsonentity:`ChangedPointInfo` for the format of the individual objects :jsonparam List[String] posMessages *(required)* A list of messages to be displayed to the cashier :jsonparam String guestWebSite *(required)* A URL where guests can login to see their balances and transaction history Example resonse body .. code:: javascript { "result": "success", "checkNumber": "5657", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100", "openTime": "0001-01-01 00:00:00 -00: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" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Simulate Coupon ^^^^^^^^^^^^^^^^^^^^^ .. http: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. It's 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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Boolean autoActivateCard: *(required)* ``true`` if the card should automatically be activated if it is not already active. :jsonparam String terminal: *(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 :jsonparam String operator: *(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. :jsonparam Object rewardSelectionMode: *(required)* Identifies whether to use automatic, manual, or applicable_rewards reward selection. See :http:jsonentity:`RewardSelectionMode` for details. :jsonparam List[Object] potentialUnitItems: *(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 :http:jsonentity:`PotentialUnitItem` for details. :jsonparam List[Object] receiptSettings: *(required)* List of receipt settings. See :http:jsonentity:`ReceiptSetting` for details :jsonparam String couponCode: *(required)* A coupon code to attempt to apply to a check .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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]`` :jsonparam List[Object] itemDiscounts: *(required)* The list of per-item discounts that could be applied to the check. See :http:jsonentity:`ItemDiscount` for the format of the individual objects :jsonparam List[Object] subtotalDiscounts: *(required)* The list of applicable discounts which concern the check subtotal, or the whole check. See :http:jsonentity:`SubTotalDiscount` for the format of the individual objects :jsonparam List[Int] couponsToRemove: *(required)* The list of coupon IDs to remove from the check before applying item and subtotal discounts. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Post And Accrue Points With Redeem ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http:post:: check/postAndAccruePointsWithRedeem.json The check post and accrue points with redeem request is meant to follow a call to :http: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 :http: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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(optional)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam String terminal: *(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 :jsonparam String operator: *(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. :jsonparam List[Object] receiptSettings: *(required)* List of receipt settings. See :http:jsonentity:`ReceiptSetting` for details .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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]`` :jsonparam String customerName: *(required)* The customer's name :jsonparam String tierName: *(required)* The tier label for this customer :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam Int accountCode: *(required)* Unique identifier for the account associated with the accrual :jsonparam Long pxTransactionId: *(required)* Paytronix transaction ID :jsonparam List[Object] pointBalances: *(required)* The list of the remaining quantity of all points on the given card. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam List[Object] changedWalletContents *(required)* The list of visible points changes. See :http:jsonentity:`ChangedPointInfo` for the format of the individual objects :jsonparam List[String] posMessages *(required)* A list of messages to be displayed to the cashier :jsonparam String guestWebSite *(required)* A URL where guests can login to see their balances and transaction history :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines Example response body .. code:: javascript { "result": "success", "checkNumber": "5657", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100", "openTime": "0001-01-01 00:00:00 -00: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", "----------------------------------------" ] } } .. http:response:: couponSuccess :jsonparam String result: *(required)* ``couponSuccess`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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 .. code:: javascript { "result": "couponSuccess", "checkNumber": "5657", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100", "openTime": "0001-01-01 00:00:00 -00:00" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get Check ^^^^^^^^^^ .. http: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: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :query String number: *(required)* Check number of the desired check. :query String openTime: *(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]`` .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object check: *(required)* The requested check. See :http:jsonentity:`Check` for details. .. http:response:: failure :jsonparam String result: *(required)* ``failed`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Post and Accrue Points ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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 :http:post:`check/computePointAccrual.json` to compute a point accrual Add/Redeem Request then submitting it via :http:post:`transaction/addRedeem.json` and then submitting the check again via :http: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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam Boolean autoActivateCard: *(required)* ``true`` if the card should automatically be activated if it is not already active. Defaults to ``false`` :jsonparam String terminal: *(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. :jsonparam String operator: *(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. :jsonparam List[Object] receiptSettings: *(required)* List of receipt settings. See :http:jsonentity:`ReceiptSetting` for details .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object reply: *(required)* The add/redeem reply from the point accrual transaction. See :http:jsonentity:`AddRedeemReply` for format. :jsonparam String customerName: *(required)* The customer's name :jsonparam String tierName: *(required)* The tier label for this customer :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam List[Object] pointBalances: *(required)* The guest's loyalty point balances. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam List[Object] changedWalletContents *(required)* The list of visible points changes. See :http:jsonentity:`ChangedPointInfo` for the format of the individual objects :jsonparam List[String] posMessages *(required)* A list of messages to be displayed to the cashier :jsonparam String guestWebSite *(required)* A URL where guests can login to see their balances and transaction history :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines Example response body .. code:: javascript { "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 } ] } .. http:response:: noWorkSuccess :jsonparam String result: *(required)* ``noWorkSuccess`` .. http:response:: failed :jsonparam String result: *(required)* ``failed`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Multi Post and Accrue Points ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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 :http: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 :http:post:`transaction/addRedeem.json`, and then submitting the check. again via :http:post:`check/post.json`. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cards: *(required)* A list of CardAmount objects. See :http:jsonentity:`CardAmount` for details. :jsonparam Boolean autoActivateCard: *(required)* ``true`` if the card should automatically be activated if it is not already active. Defaults to ``false`` :jsonparam String terminal: *(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. :jsonparam String operator: *(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. :jsonparam List[Object] receiptSettings: *(required)* List of receipt settings. See :http:jsonentity:`ReceiptSetting` for details .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] reply: *(required)* A list of single point accrual result objects. Successes will contain the :http:jsonentity:`AddRedeemReply` and the receipt text, failures will contain the error code and error message. See :http:post:`check/postAndAccruePoints.json` for result formats. .. http:response:: noWorkSuccess :jsonparam String result: *(required)* ``noWorkSuccess`` .. http:response:: failed :jsonparam String result: *(required)* ``failed`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Check Redeem Only ^^^^^^^^^^^^^^^^^ .. http: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 .. code:: javascript { "merchantId": 1738, "storeCode": "0", "agentName": "PDQ POS", "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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String agentName: *(optional)* The agent name. Used if a store has more than one POS system. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. :jsonparam Object cardInfo: *(required)* Card to accrue points for. See :http:jsonentity:`CardInfo` for details. :jsonparam String terminal: *(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. :jsonparam String operator: *(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. :jsonparam Object rewardSelectionMode: *(required)* Identifies whether to use automatic, manual, or applicable_rewards reward selection. See :http:jsonentity:`RewardSelectionMode` for details. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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]`` :jsonparam Long pxTransactionId: *(required)* Unique Long value to identify this transaction :jsonparam List[Object] itemDiscounts: *(required)* The list of per-item discounts applied to the check. See :http:jsonentity:`ItemDiscount` for the format of the individual objects :jsonparam List[Object] multiItemDiscounts: *(required)* The list of multi-item discounts applied to the check. See :http:jsonentity:`MultiItemDiscount` for the format of the individual objects :jsonparam List[Object] subtotalDiscounts: *(required)* The list of whole-check discounts applied to the check subtotal, or the whole check. See :http:jsonentity:`SubTotalDiscount` for the format of the individual objects :jsonparam List[Object] serviceChargeDiscounts: *(required)* The list of serviceCharge discounts that could be applied to the check. See :http:jsonentity:`ServiceChargeDiscount` for the format of the individual objects :jsonparam List[ChosenReward] chosenRewardsNotApplied: *(required)* List of chosen rewards that were unable to be applied to the check. See :http:jsonentity:`ChosenReward` for the format of the individual objects :jsonparam List[Object] pointBalances: *(required)* The list of the remaining quantity of all points on the given card. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines :jsonparam List[Object] changedWalletContents *(required)* The list of visible points changes. See :http:jsonentity:`ChangedPointInfo` for the format of the individual objects :jsonparam List[String] posMessages *(required)* A list of messages to be displayed to the cashier :jsonparam String guestWebSite *(required)* A URL where guests can login to see their balances and transaction history :jsonparam String customerName: *(required)* The customer's name :jsonparam String tierName: *(required)* The tier label for this customer :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam String anonymousAccountToken: *(optional)* Unique String value to identify the guest. Example response body .. code:: javascript { "result": "success", "checkNumber": "5657", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100", "openTime": "0001-01-01 00:00:00 -00: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": [] } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. .. http:response:: noRewardsApplied :jsonparam String result: *(required)* ``noRewardsApplied`` :jsonparam String printedCardNumber: *(required)* The printed card number associated with the account. :jsonparam List[Object] pointBalances: *(required)* The list of the remaining quantity of all points on the given card. See :http:jsonentity:`PointInfo` for the format of the individual objects :jsonparam List[Object] rewardBalances: *(required)* The list of the remaining quantity of all rewards on the given card. See :http:jsonentity:`RewardPointInfo` for the format of the individual objects :jsonparam Map[List[String]] receiptText: *(required)* This is a mapping from String labels to sets (or lists) of receipt lines Check Upload Batches ^^^^^^^^^^^^^^^^^^^^ .. http:post:: check/uploadBatches.json The check uploadBatches request allows for a full POS check to be uploaded in batches This REST endpoints accepts multipart/form-data content-type. Download Postman App and import the following collection for request example: :download:`Postman Collection `. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` Multipart/form-data ``request``: :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam String avroSchemaIdentifier: *(optional)* Avro Schema Id using MD5 hash (only used if multipartPart contentType uses octet-stream format, do NOT send unless directed to do so by Paytronix.) Multipart/form-data ``batch``: :jsonparam List[Object] : *(required)* List of POS check to post. See :http:jsonentity:`Check` for details. Example of : .. code:: javascript [ { "header": { "cashier": "0", "closeTime": "0001-01-01 00:00:00 -05:00", "isReturn": false, "number": "-1", "openTime": "0001-01-01 00:00:00 -05:00", "revenueCenterName": "", "revenueCenterNumber": 1, "seatCount": 0, "tableNumber": "", "uniqueIdentifier": "8a54279c-78a7-4532-b05c-72c83aa5f60c" }, "items": [ { "categories": [ { "categoryType": "major", "id": "6", "name": "Soda Pop " } ], "fullPrice": 1.75, "isTaxable": true, "isVoided": false, "itemId": "105", "modifiers": [], "name": "Coke (med)", "price": 1.75, "quantity": 1, "seat": 1, "type": "menuItem" } ], "totals": { "checkTotal": 1.87, "discountTotal": 0, "serviceChargeTotal": 0, "subTotal": 1.75, "taxTotal": 0.12, "tenderTotal": 0, "tipTotal": 0 } } ] .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Int count: *(required)* Number of sucessfully uploaded checks .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. .. http:response:: success :jsonparam java.time.Duration holdOffTime: *(required)* 0 if store settings does not accept checks, 1 otherwise. :jsonparam String result: *(required)* ``temporarilyRejected`` Check Post ^^^^^^^^^^ .. http: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 order and delivery integrations. Functions similarly to :http:post:`check/uploadBatches.json`, only this endpoint uploads only a single check. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object check: *(required)* POS check to post. See :http:jsonentity:`Check` for details. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String visitCode: *(required)* A generated VisitCode based off the submitted check .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String visitCode: *(required)* A generated VisitCode based off the submitted check Post Price Match Discounts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String storeCode: *(required)* A store code to uniquely identify the store where this transaction occurred. :jsonparam List[Object] priceMatchDiscounts: *(required)* List of Price Match Discounts to post per store. See :http:jsonentity:`PriceMatchDiscountRecord` for details. .. http:response:: success :jsonparam String result: *(required)* ``success`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` Get Price Match Discounts By Store Code ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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: * :ref:`b2b_auth` * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String storeCode: *(required)* A store code to uniquely identify the store where this transaction occurred. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] priceMatchDiscounts: *(required)* List of Price Match Discounts for the given store. See :http:jsonentity:`PriceMatchDiscountRecord` for details. :jsonparam String checkNumber: *(required)* The check number. :jsonparam String uniqueIdentifier: *(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. :jsonparam String openTime: *(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]`` :jsonparam List[Object] itemDiscounts: *(required)* The list of per-item discounts that could be applied to the check. See :http:jsonentity:`ItemDiscount` for the format of the individual objects :jsonparam List[Object] multiItemDiscounts: *(required)* The list of multi-item discounts that could be applied to the check. See :http:jsonentity:`MultiItemDiscount` for the format of the individual objects :jsonparam List[Object] subtotalDiscounts: *(required)* The list of whole-check discounts that could be applied to the check subtotal, or the whole check. See :http:jsonentity:`SubTotalDiscount` for the format of the individual objects :jsonparam String anonymousAccountToken: *(optional)* Unique String value to identify the guest. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` Get All Price Match Discounts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. http: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: * :ref:`b2b_auth` * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] PriceMatchDiscountRecordsForStoreCode: *(required)* List of Price Match Discounts for the given merchant. See :http:jsonentity:`PriceMatchDiscountRecordsForStoreCode` for details. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` Reply Objects ------------- .. http:jsonentity:: 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 :http:jsonentity:`MenuItem` or :http:jsonentity:`ComboItem` should have a :http:jsonentity:`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. :jsonparam String id: *(required)* An identifier for this discount, as in a coupon number. Not guaranteed to be unique :jsonparam String name: *(required)* Human-readable name of discount :jsonparam Integer walletCode: *(required)* A numeric identifier forur a specific type of discount, unique for a given merchant :jsonparam List[Object] possibleUses: *(required)* See :http:jsonentity:`PossibleDiscount` :jsonparam Decimal maxEligibleUnits: *(optional)* Maximum units to which this discount can be applied. :jsonparam Boolean applyAutomatically: *(required)* Automatically apply discounts :jsonparam Integer priority: *(required)* The priority in which the reward should be applied .. http:jsonentity:: 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 :http:jsonentity:`AvailableUnitDiscount` :jsonparam String itemId: *(required)* The ID of the item to which this discount could be applied. :jsonparam Decimal unitDiscount: *(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. .. http:jsonentity:: Category :jsonparam String categoryType: *(required)* Either "major", "minor", or "promo". Type of category if there are multiple types. Use "major" if there are no distinct category types. :jsonparam String id: *(required)* Identifier for the category. This identifies the category in the POS database. :jsonparam String name: *(optional)* Human-readable name for the category. .. http:jsonentity:: Check :jsonparam Object header: *(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 :http:jsonentity:`Header` for format :jsonparam List[Object] items: *(required)* List of individual check items. These are further broken down into separate types, identified by the type field of each: * Single menu items (:http:jsonentity:`MenuItem`) such as entrees, appetizers, and beverages. * Combo items (:http:jsonentity:`ComboItem`) which represent combo meals, such as burger and fries. * Discount items (:http:jsonentity:`DiscountItem`) which alter the check total (typically by reducing it) but are not directly tied to a single item. * Service charge items (:http:jsonentity:`ServiceChargeItem`) which represent additional nontaxed service charges such as gift card purchases. * Tender items (:http:jsonentity:`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 :jsonparam Object totals: *(required)* The totals at the end of the check. See :http:jsonentity:`Totals` for format Example check .. code:: javascript { "header": { "cashier": "0", "closeTime": "0001-01-01 00:00:00 -00:00", "isReturn": false, "number": "-1", "openTime": "0001-01-01 00:00:00 -00: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.00, "categories": [{"categoryType": "major", "id": "-1"}], "isVoided": false, "isTaxable": true, "price": 12.00, "fullPrice": 12.00, "modifiers": [], "discounts": [], "consumedQuantity": "0" }, { "type": "discountItem", "itemId": "201", "name": "Reward Dollars", "quantity": "1", "price": "-2.00", "discountSource": "loyalty", "walletCode": 14, "walletQuantity": "1" } { "type": "tenderItem", "itemId": "102", "name": "GC Redeem", "seat": 1, "referenceLine": "PX-ref_line", "amount": "-5.00", "detail": { "masked": "1234", "pxTransactionId": 123456, "type": "giftCard" } }, { "type": "serviceChargeItem", "itemId": "301", "name": "Gift Card Sale", "referenceLine": "GC-XXXXXX**XXXXXX", "quantity": "1", "isTaxable": false, "price": "5.00" } ], "totals": { "subTotal":10.00, "taxTotal": 0.10, "discountTotal": -2.00, "serviceChargeTotal": 5.00, "checkTotal": 15.10, "tipTotal": 0.0 "tenderTotal": -5.00 } } .. http:jsonentity:: ChosenReward :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant :jsonparam Decimal amount: *(required)* Represents either the discount amount if applied to an item, or the wallet balance if the reward is applied to the transaction. .. http:jsonentity:: ComboItem :jsonparam String type: *(required)* Identifies this item as a menu item. Must always be ``"comboItem"``. :jsonparam String itemId: *(required)* Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the menu item. :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the menu item, if any. :jsonparam Decimal quantity: *(optional)* Quantity of the menu item purchased. Typically ``"1"``. Defaults to ``1``. :jsonparam List[Object] categories: *(optional)* Can be empty. Any categories the combo item is associated with. Defaults to empty. See :http:jsonentity:`Category` for format :jsonparam Boolean isVoided: *(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``. :jsonparam Boolean isTaxable: *(optional)* ``true`` if the menu item is a taxable item which contributed to the tax total. Defaults to ``true``. :jsonparam Decimal price: *(required)* Price of the combo item. Typically a positive amount, unless voided. Should be calculated as unit price * quantity. :jsonparam Decimal fullPrice: *(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. :jsonparam List[Object] modifiers: *(optional)* Can be empty. A list of any modifiers (such as condiments) attached to the combo item. Defaults to empty. See :http:jsonentity:`Modifier` for format :jsonparam List[Object] discounts: *(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 :http:jsonentity:`DiscountItem` for format :jsonparam List[Object] items: *(required)* List of menu items (see :http:jsonentity:`MenuItem` for format) to be included in the combo :jsonparam Decimal consumedQuantity: *(optional)* Consumed quantity of the menu item. Defaults to ``0``. .. http:jsonentity:: CreditCardTenderItem :jsonparam String type: *(required)* Identifies this detail as a credit card detail. Must always be ``"creditCard"``. :jsonparam String cardholder: *(optional)* Name of the cardholder as captured from the credit card. :jsonparam String cardType: *(optional)* Type of credit card. Must be one of "Visa", "MasterCard", "American Express", "Diners Club", "Discover", "JCB", or "other". :jsonparam String iin: *(optional)* IIN (first 6 digits) from credit card number. :jsonparam String masked: *(optional)* Masked account number (typically last 4 digits) from credit card number. :jsonparam String expiration: *(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. .. http:jsonentity:: 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 :http:post:`postAndAccruePointsWithRedeem` endpoint, otherwise the reward will never be redeemed from the guest's account. :jsonparam String type: *(required)* Identifies this item as a discount item. Must always be "discountItem". :jsonparam String itemId: *(required)* Identifier for the discount item. This identifies the discount item in the Paytronix database, not the particular line item in the check. :jsonparam Integer multiItemDiscountId: *(optional)* Identifier for a combo reward. This identifies the item as part of a combo reward. :jsonparam String name: *(optional)* Human-readable description of the discount item. :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the discount item, if any. :jsonparam Decimal quantity: *(optional)* Quantity of the discount item purchased. Typically ``"1"``. Defaults to ``1``. :jsonparam Boolean isVoided: *(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``. :jsonparam Boolean isTaxable: *(optional)* ``true`` if the discount item is a taxable item which contributed to the tax total. Defaults to ``true``. :jsonparam Decimal price: *(required)* Price of the discount item. Typically a negative amount (which reduces the check total), unless voided. :jsonparam Decimal fullPrice: *(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. :jsonparam String discountSource: *(optional)* One of ``"other"``, ``"loyalty"``, ``"coupon"`` :jsonparam Integer walletCode: *(optional)* A numeric identifier for a specific type of discount, unique for a given merchant. Populated based on the ``walletCode`` field in the :http:jsonentity:`ItemDiscount`, :http:jsonentity:`SubtotalDiscount`, or :http:jsonentity:`AvailableUnitDiscount` which was applied. Must be present for Loyalty and Coupon Discounts :jsonparam Decimal walletQuantity: *(optional)* Quantity of the wallet which was used. Populated based on the ``quantityRedeemed`` field in the :http:jsonentity:`ItemDiscount` or :http:jsonentity:`SubtotalDiscount` objects, or the ``unitDiscount`` field in a :http:jsonentity:`PossibleUse`, depending on how the discount was applied to the check. Must be present for Loyalty Discounts :jsonparam Integer couponId: *(optional)* Unique identifier of the coupon from which this reward came. Must be present for Coupon Discounts Example: .. code:: javascript { "type": "discountItem", "itemId": "201", "name": "Reward Dollars", "quantity": "1", "price": "-2.00", "discountSource": "loyalty", "walletCode": 14, "walletQuantity": "1" } .. http:jsonentity:: GiftCardTenderItem :jsonparam String type: *(required)* Identifies this detail as a gift card detail. Must always be ``"giftCard"``. :jsonparam Long pxTransactionId: *(optional)* Paytronix transaction ID, if available and for a Paytronix gift card. :jsonparam String masked: *(optional)* Masked account number (typically last 4 digits) from gift card number. .. http:jsonentity:: Header :jsonparam String number: *(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. :jsonparam String uniqueIdentifier: *(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. :jsonparam Boolean isReturn: *(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. :jsonparam String openTime: *(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]`` :jsonparam String closeTime: *(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]`` :jsonparam Integer seatCount: *(optional)* Number of seats. :jsonparam String tableNumber: *(optional)* Table number or identifier. :jsonparam Integer revenueCenterNumber: *(optional)* Identifier for revenue center (cost center) that the check was located in. :jsonparam String revenueCenterName: *(optional)* Human readable description for revenue center (cost center) that the check was located in. :jsonparam String cashier: *(optional)* Cashier (operator) ID. :jsonparam Map[String] properties: *(required)* Can be empty. Additional POS-specific properties as strings. Defaults to empty. :jsonparam Boolean isVoid: *(optional)* Flag to indicate whether the check is voided. :jsonparam Boolean isCatering: *(optional)* Flag to indicate whether the check is for a catering order. :jsonparam String orderMethod: *(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`` :jsonparam String deliveryMethod: *(optional)* Delivery method of the check. Possible values are: ``dine in``, ``pick up``, ``in house delivery``, ``curbside``, ``drive through``, ``third party delivery``, ``other`` Example .. code:: javascript { "cashier": "0", "closeTime": "0001-01-01 00:00:00 -00:00", "isReturn": false, "number": "-1", "openTime": "0001-01-01 00:00:00 -00:00", "revenueCenterName": "", "revenueCenterNumber": 1, "seatCount": 0, "tableNumber": "", "uniqueIdentifier": "#f62bed51-efea-c1fb-9336-a4e4cf934100" } .. http:jsonentity:: ItemDiscount :jsonparam String id: *(required)* An identifier for this discount, as in a coupon number. Not guaranteed to be unique :jsonparam Integer multiItemDiscountId: *(optional)* Identifier for a combo reward. This identifies the item as part of a combo reward. :jsonparam String name: *(required)* Human-readable name of discount :jsonparam String referenceLine: *(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. :jsonparam String menuItemId: *(required)* Directly corresponds to the itemId field of a menu or combo item in the request. :jsonparam Decimal discount: *(required)* Full amount by which the target item should be discounted. :jsonparam Decimal quantityDiscounted: *(required)* Quantity of the line item which is to be discounted. :jsonparam Decimal unitDiscount: *(required)* This is the ``discount`` value divided by the ``quantityDiscounted``. Usually ignored :jsonparam String discountType: *(required)* One of "Percent", "Dollar", "ReducePrice", "PerUnit". Can be ignored. :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant. :jsonparam Decimal quantityRedeemed: *(required)* Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. :jsonparam Boolean applyAutomatically: *(required)* Automatically apply discounts :jsonparam Integer couponId: *(optional)* ID of coupon, only returned in calls to simulateCoupon. :jsonparam Date soonestExpirationDate: *(optional)* The earliest or soonest expiration date out of a list of reward point expiration dates. The format is ``yyyy-mm-dd``. :jsonparam Integer priority: *(required)* The priority in which the reward should be applied Example: .. code:: javascript { "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 } .. http:jsonentity:: ItemizedTotal :jsonparam String itemizerType: *(required)* Either ``"sales"`` or ``"tax"``, depending on what is itemized :jsonparam String id: *(required)* Identifier for the itemizer :jsonparam Decimal total: *(required)* Itemized amount .. http:jsonentity:: LoyaltyCardTenderItem :jsonparam String type: *(required)* Identifies this detail as a loyalty card detail. Must always be ``"loyaltyCard"``. :jsonparam Long pxTransactionId: *(optional)* Paytronix transaction ID, if available and for a Paytronix comp/loyalty. :jsonparam String masked: *(optional)* Masked account number (typically last 4 digits) from comp/loyalty card number. .. http:jsonentity:: MenuItem :jsonparam String type: *(required)* Identifies this item as a menu item. Must always be ``"menuItem"``. :jsonparam String itemId: *(required)* Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the menu item. :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the menu item, if any. :jsonparam Decimal quantity: *(optional)* Quantity of the menu item purchased. Typically ``"1"``. Defaults to ``1``. :jsonparam List[Object] categories: *(optional)* Can be empty. Any categories the menu item is associated with. Defaults to empty. See :http:jsonentity:`Category` for format :jsonparam Boolean isVoided: *(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``. :jsonparam Boolean isTaxable: *(optional)* ``true`` if the menu item is a taxable item which contributed to the tax total. Defaults to ``true``. :jsonparam Decimal price: *(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. :jsonparam Decimal fullPrice: *(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. :jsonparam List[Object] modifiers: *(optional)* Can be empty. A list of any modifiers (such as condiments) attached to the menu item. Defaults to empty. See :http:jsonentity:`Modifier` for format :jsonparam List[Object] discounts: *(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 :http:jsonentity:`DiscountItem` for format :jsonparam Decimal consumedQuantity: *(optional)* Consumed quantity of the menu item. Defaults to ``0``. Example .. code:: javascript { "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" } .. http:jsonentity:: Modifier :jsonparam String itemId: *(required)* Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the menu item. :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the menu item, if any. :jsonparam Decimal quantity: *(optional)* Quantity of the menu item purchased. Typically ``"1"``. Defaults to ``1``. :jsonparam List[Object] categories: *(optional)* Can be empty. Any categories the menu item is associated with. Defaults to empty. See :http:jsonentity:`Category` for format :jsonparam Boolean isVoided: *(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``. :jsonparam Boolean isTaxable: *(optional)* ``true`` if the menu item is a taxable item which contributed to the tax total. Defaults to ``true``. :jsonparam Decimal price: *(required)* Price of the modifier. Typically a positive amount, unless voided. Should be calculated as unit price * quantity. :jsonparam Decimal fullPrice: *(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. :jsonparam List[Object] discounts: *(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 :http:jsonentity:`DiscountItem` for format :jsonparam Decimal consumedQuantity: *(optional)* Consumed quantity of the menu item. Defaults to ``0``. .. http:jsonentity:: MultiItemDiscount :jsonparam String id: *(required)* An identifier for this discount, as in a coupon number. Not guaranteed to be unique :jsonparam String name: *(required)* Human-readable name of discount :jsonparam String discountObjectNumber: *(required)* POS discount number to apply when redeeming this wallet as a reward. :jsonparam String posItemId: *(required)* Unique identifier for item in the point of sale system :jsonparam List[Object] items: *(required)* A list of sub item discounts. See :http:jsonentity:`SubItemDiscount` for format :jsonparam String discountType: *(required)* One of "Percent", "Dollar", "ReducePrice", "PerUnit". Can be ignored. :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant. Must be present for Loyalty Discounts :jsonparam Decimal quantityRedeemed: *(required)* Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. Must be present for Loyalty Discounts :jsonparam Decimal totalDiscounted: *(required)* Total value discounted :jsonparam Boolean applyAutomatically: *(required)* Automatically apply discounts :jsonparam Integer priority: *(required)* The priority in which the reward should be applied Example .. code:: javascript { "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 } .. http:jsonentity:: PointExpirationInfo :jsonparam Decimal quantity: *(required)* The quantity of reward that will expire :jsonparam String date: *(required)* Expiration date .. http:jsonentity:: PointInfo :jsonparam String pointName: *(required)* The name of the point :jsonparam Integer walletCode: *(required)* A numeric identifier for the point balance, unique for a given merchant :jsonparam Decimal balance: *(required)* The quantity of the balance remaining on the card after the transaction .. http:jsonentity:: ReceiptSetting :jsonparam String name: *(required)* Name of receipt printer :jsonparam Integer maxWidth: *(required)* Width in characters of receipt .. http:jsonentity:: 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 :jsonparam String message: *(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"`` :jsonparam String reason: *(required)* Reason code used to determine which message to send. :jsonparam String walletCode: *(required)* A numeric identifier for the specified discount that could not be applied, unique for a given merchant. :jsonparam String walletName: *(required)* The name of the reward that could not be applied. Example of :http:jsonentity:`RewardNotApplied`: .. code:: javascript { "message": "Minimum spend amount not met", "reason": "minimumSpendNotMet", "walletCode": 3, "walletName": "Free Coffee" } .. http:jsonentity:: RewardPointInfo :jsonparam String pointName: *(required)* The name of the discount :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant :jsonparam String discountObjectNumber: *(required)* POS discount number to apply when redeeming this wallet as a reward :jsonparam Decimal balance: *(required)* The quantity of the reward remaining on the card after the transaction :jsonparam List[Object] expirationDates: *(required)* A list of the dates that specified quantities of the reward will expire. See :http:jsonentity:`PointExpirationInfo` for the format of the objects :jsonparam Decimal additionalExpiringBalance: *(required)* The quantity of the reward that will expire later than the returned ``expirationDates`` :jsonparam String rewardType: *(optional)* Either ``"FIXED_AMOUNT"`` or ``"OPEN_AMOUNT"`` :jsonparam String rewardValueType: *(optional)* One of ``"PERCENT_DISCOUNT"``, ``"DOLLAR_DISCOUNT"``, ``"POS_DISCOUNT"``, ``"REDUCE_PRICE_TO"``, ``"PRECENT_OFF_CATEGORY"``, ``"PER_UNIT_DISCOUNT"`` Example .. code:: javascript { "additionalExpiringBalance": "0.000", "balance": "0.000", "discountObjectNumber": "56675", "expirationDates": [], "pointName": "Fuel Wallet", "rewardType": "FIXED_AMOUNT", "rewardValueType": "PER_UNIT_DISCOUNT", "walletCode": 71 } .. http:jsonentity:: 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. 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.<<<< :jsonparam String mode: *(required)* Either ``"automatic"`` or ``"manual"`` :jsonparam List[Object] chosenRewards: *(required if ``manual``)* List of manually chosen rewards. See :http:jsonentity:`ChosenReward` for the format of the objects Example (manual) .. code:: javascript { "mode": "manual", "chosenRewards": [ { "walletCode": 41, "amount": 1 } ] } Example (automatic) .. code:: javascript { "mode": "automatic", "chosenRewards": [] } Example (applicable_rewards) .. code:: javascript { "mode": "applicable_rewards", "chosenRewards": [] } .. http:jsonentity:: RewardToRemove :jsonparam String itemId: *(required)* A numeric identifier for the specific reward to be removed :jsonparam String reason: *(required)* States the reason why the reward was unable to be applied :jsonparam String referenceLine: *(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 .. code:: javascript { "itemId": "863", "reason": "item fully discounted", "referenceLine": "31324" } .. http:jsonentity:: ServiceChargeItem :jsonparam String type: *(required)* Identifies this item as a service charge item. Must always be ``"serviceChargeItem"``. :jsonparam String itemId: *(required)* Identifier for the service charge. This identifies the service charge in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the service charge :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the service charge, if any. :jsonparam Decimal quantity: *(optional)* Quantity of the service charge purchased. Typically ``"1"``. Defaults to ``1``. :jsonparam Boolean isVoided: *(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``. :jsonparam Boolean isTaxable: *(optional)* ``true`` if the service charge is a taxable item which contributed to the tax total. Defaults to ``true``. :jsonparam Decimal price: *(required)* Price of the service charge. Typically a positive amount, unless voided. :jsonparam Decimal fullPrice: *(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. :jsonparam List[Object] discounts: *(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 :http:jsonentity:`DiscountItem` for format :jsonparam Decimal consumedQuantity: *(optional)* Consumed quantity of the menu item. Defaults to ``0``. Example: .. code:: javascript { "type": "serviceChargeItem", "itemId": "301", "name": "Gift Card Sale", "referenceLine": "GC-XXXXXX**XXXXXX", "quantity": "1", "isTaxable": false, "price": "5.00" } .. http:jsonentity:: ServiceChargeDiscount :jsonparam String id: *(required)* An identifier for this discount, as in a coupon number. Not guaranteed to be unique. :jsonparam String name: *(required)* Human-readable name of discount. :jsonparam String referenceLine: *(optional)* Reference line for the service charge discount, if any. :jsonparam String posItemId: *(required)* Unique identifier for item in the point of sale system. :jsonparam String menuItemId: *(required)* Directly corresponds to the itemId field of a ServiceChargeItem in the request. :jsonparam Decimal discount: *(required)* Full amount by which the target item should be discounted. :jsonparam Decimal quantityDiscounted: *(required)* Quantity of the line item which is to be discounted. :jsonparam String discountType: *(required)* One of ``"Percent"``, ``"Dollar"``, ``"ReducePrice"``. Can be ignored. :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant. :jsonparam Decimal quantityRedeemed: *(required)* Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. :jsonparam Boolean applyAutomatically: *(required)* Automatically apply discounts. :jsonparam Integer priority: *(required)* The priority in which the reward should be applied Example: .. code:: javascript { "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 } .. http:jsonentity:: SubItemDiscount :jsonparam String referenceLine: *(optional)* Reference line for the discount item, if any. :jsonparam String menuItemId: *(required)* Directly corresponds to the itemId field of a menu or combo item in the request. :jsonparam Decimal discount: *(required)* Full amount by which the target item should be discounted. :jsonparam Decimal quantityDiscounted: *(required)* Quantity of the line item which is to be discounted. :jsonparam Decimal unitDiscount: *(required)* This is the ``discount`` value divided by the ``quantityDiscounted``. .. http:jsonentity:: SubTotalDiscount :jsonparam String id: *(required)* An identifier for this discount, as in a coupon number. Not guaranteed to be unique :jsonparam String name: *(required)* Human-readable name of discount :jsonparam Decimal discount: *(required)* Full amount by which the target item should be discounted. :jsonparam String discountType: *(required)* One of ``"Percent"``, ``"Dollar"``, ``"ReducePrice"``, ``"PerUnit"``. Can be ignored. :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant. :jsonparam Decimal quantityRedeemed: *(required)* Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. :jsonparam Boolean applyAutomatically: *(required)* Automatically apply discounts :jsonparam Integer couponId: *(optional)* Id of coupon, only returned in calls to simulateCoupon. :jsonparam Integer priority: *(required)* The priority in which the reward should be applied Example: .. code:: javascript { "id": "34", "name": "Five Dollars Off Check", "discount": "5.00", "discountType": "Dollar", "walletCode": 52, "quantityRedeemed": "1", "applyAutomatically": true, "priority": 1 } .. http:jsonentity:: TenderItem :jsonparam String type: *(required)* Identifies this item as a tender item. Must always be ``"tenderItem"``. :jsonparam String itemId: *(required)* Identifier for the tender. This identifies the tender in the Paytronix database, not the particular line item in the check. :jsonparam String name: *(optional)* Human-readable description of the tender :jsonparam Integer seat: *(optional)* Seat number, if available. :jsonparam String referenceLine: *(optional)* Reference line for the tender, if any. :jsonparam Decimal amount: *(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. :jsonparam Object detail: *(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 :http:jsonentity:`CreditCardTenderItem`) * Gift card (see :http:jsonentity:`GiftCardTenderItem`) * Loyalty card (see :http:jsonentity:`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: .. code:: javascript { "type": "tenderItem", "itemId": "102", "name": "GC Redeem", "seat": 1, "referenceLine": "PX-ref_line", "amount": "-5.00", "detail": { "masked": "1234", "pxTransactionId": 123456, "type": "giftCard" } } .. http:jsonentity:: Totals :jsonparam Decimal subTotal: *(required)* Sub total of menu, combo, and discount items. Calculated by summing the ``price`` field of each menu, combo, and discount item. :jsonparam Decimal taxTotal: *(required)* Tax total. Typically calculated by taking the ``subTotal`` and multiplying by some appropriate tax rate. :jsonparam Decimal discountTotal: *(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. :jsonparam Decimal serviceChargeTotal: *(required)* Total of service charges :jsonparam Decimal checkTotal: *(optional)* Check total before tenders and tips. checkTotal can be calculated from the individual totals via the following formula: ``subTotal`` + ``taxTotal`` + ``serviceChargeTotal`` :jsonparam Decimal tipTotal: *(optional)* Total of tips, if known. :jsonparam Decimal tenderTotal: *(required)* Total of tenders applied to the check. Typically a negative amount (reducing the check total). :jsonparam List[Object] itemizedTotals: *(required)* Can be empty. Additional POS-specific itemized totals, such as totals by reporting group or similar. Defaults to empty. See :http:jsonentity:`ItemizedTotal` for format .. http:jsonentity:: WalletInformation :jsonparam Integer walletCode: *(required)* A numeric identifier for a specific type of discount, unique for a given merchant :jsonparam Decimal amount: *(required)* The amount to be redeemed from the wallet Example .. code:: javascript { "subTotal":10.00, "taxTotal": 0.10, "discountTotal": -2.00, "serviceChargeTotal": 5.00, "checkTotal": 15.10, "tipTotal": 0.0 "tenderTotal": -5.00 } .. http:jsonentity:: PriceMatchDiscountRecord :jsonparam String itemId: *(required)* Identifier for the PPU item. This identifies the PPU item in the Paytronix database, not the particular line item in the check. :jsonparam Decimal originalPrice: *(required)* Original Price for PPU item. (Positive Number!) :jsonparam Decimal discountAmount: *(required)* Price Match Discount Amount for PPU item. (Positive Number!) .. http:jsonentity:: PriceMatchDiscountRecordsForStoreCode :jsonparam String storeCode: *(required)* A store code to uniquely identify the store. :jsonparam List[Object] priceMatchDiscounts: *(required)* List of Price Match Discounts for this store. See :http:jsonentity:`PriceMatchDiscountRecord` for details. Error Codes ----------- The following are the possible codes and messages that can be returned by the Sale 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 ~~~~~~~~~~~~~ Starting soon, it will be possible to 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. 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 :http:post:`check/simulateCoupon.json` endpoint, which has a similar return type to :http:post:`check/simulateAccrualAndRedemption.json`. If loyalty rewards also need to apply to the check, that will necessitate an additional call to :http:post:`check/simulateAccrualAndRedemption.json`. After the check is finalized, simply call :http:post:`check/postAndAccruePointsWithRedeem.json` with the check information, which will do its usual work on top of recording the coupon usage. Changes to :http: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 :http:jsonentity:`DiscountItem`, :http:jsonentity:`ItemDiscount`, :http:jsonentity:`SubtotalDiscount`, and :http:jsonentity:`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 :http:jsonentity:`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