Check Service

The check service provides endpoints for posting check information and accruing points on checks.

Request Objects

PotentialUnitItem

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

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

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

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

Endpoints

Post Price Match Discounts

POST check/priceMatchDiscounts.json

The post price match discounts request allows for a list of Price Per Unit (PPU) Discounts per store to be passed to the PXS for price match purposes.

The following authentication methods are allowed for this endpoint:

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

Get Price Match Discounts By Store Code

GET check/priceMatchDiscounts.json

The get price match discounts request allows for a list of Price Per Unit (PPU) Discounts by store to be returned from the PXS for price match purposes.

The following authentication methods are allowed for this endpoint:

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

Get All Price Match Discounts

GET check/allPriceMatchDiscounts.json

The get price match discounts request allows for a list of all Price Per Unit (PPU) Discounts grouped by store code to be returned from the PXS for price match purposes.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.

::jsonparam String integrationIdentifier: (required) A unique identifier for the caller

"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • PriceMatchDiscountRecordsForStoreCode (List[Object]) – (required) List of Price Match Discounts for the given store. See PriceMatchDiscountRecordsForStoreCode for details.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure

Check Upload Batches

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: Postman Collection.

The following authentication methods are allowed for this endpoint:

Multipart/form-data request:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • avroSchemaIdentifier (String) – (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:

JSON Parameters:
 
  • <unamed json array> (List[Object]) – (required) List of POS check to post. See Check for details.

Example of <unamed json array>:

[
  {
    "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
    }
  }
]
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • count (Int) – (required) Number of sucessfully uploaded checks
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.
"result": "success"
JSON Parameters:
 
  • holdOffTime (java.time.Duration) – (required) 0 if store settings does not accept checks, 1 otherwise.
  • result (String) – (required) temporarilyRejected

Check Post

POST check/post.json

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

The following authentication methods are allowed for this endpoint:

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

Check Post and Accrue Points

POST check/postAndAccruePoints.json

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

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • integrationIdentifier (String) – (required) A unique identifier for the caller
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active. Defaults to false
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (Integer) – (required) Number of the POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • reply (Object) – (required) The add/redeem reply from the point accrual transaction. See AddRedeemReply for format.
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines
"result": "noWorkSuccess"
JSON Parameters:
 
  • result (String) – (required) noWorkSuccess
"result": "failed"
JSON Parameters:
 
  • result (String) – (required) failed
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Post and Accrue Points with Auto-Redeem

POST check/postAndAccruePointsWithAutoRedeem.json

The check post and accrue points with auto-redeem request implements the same behavior as the POST check/postAndAccruePoints.json request, with the additional functionality of automatically identifying and applying any applicable rewards. For example, this might identify that the loyalty member is eligible for a 10% discount and automatically apply it, which might consequently impact the loyalty points accrued.

This endpoint takes the same input as the check post and accrue points endpoint.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • integrationIdentifier (String) – (required) A unique identifier for the caller
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • autoActivateCard (Boolean) – (required) true if the card should automatically be activated if it is not already active. Defaults to false
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (Integer) – (required) Number of the POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • reply (Object) – (required) The add/redeem reply from the point accrual transaction. See AddRedeemReply for format.
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that were applied to the check. See ItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of applied discounts which concern the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Multi Post and Accrue Points

POST check/multiPostAndAccruePoints.json

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

The following authentication methods are allowed for this endpoint:

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

Check Simulate Accrual And Redemption

POST check/simulateAccrualAndRedemption.json

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

The following authentication methods are allowed for this endpoint:

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

Check Simulate Coupon

POST check/simulateCoupon.json

The check simulate coupon request is similar to the simulate accrual and redemption endpoint. It finds any rewards connected to the supplied coupon code, and attempts to apply them to the check. 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:

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

Check Post And Accrue Points With Redeem

POST check/postAndAccruePointsWithRedeem.json

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

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • integrationIdentifier (String) – (required) A unique identifier for the caller
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (optional) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters
  • operator (Integer) – (required) Number of the POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • receiptSettings (List[Object]) – (required) List of receipt settings. See ReceiptSetting for details
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • receiptText (Map[List[String]]) – (required) This is a mapping from String labels to sets (or lists) of receipt lines
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Compute Point Accrual

POST check/computePointAccrual.json

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

The following authentication methods are allowed for this endpoint:

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

Check Compute Applicable Rewards

POST check/computeApplicableRewards.json

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

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (Integer) – (required) Number of the POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic or manual reward selection. See RewardSelectionMode for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts that could be applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts that could be applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of whole-check discounts that could be applied to the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check Redeem Only

POST check/redeemOnly.json

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

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
  • agentName (String) – (optional) The agent name. Used if a store has more than one POS system.
  • check (Object) – (required) POS check to post. See Check for details.
  • cardInfo (Object) – (required) Card to accrue points for. See CardInfo for details.
  • terminal (String) – (required) Number of the POS terminal where the check was submitted for accrual, usually by closing the check. Use "0" if the terminal is unknown or unavailable. Maximum of 100 characters.
  • operator (Integer) – (required) Number of the POS operator (cashier) who submitted the check for accrual, usually by closing the check. Use "0" if the operator is unknown or unavailable.
  • rewardSelectionMode (Object) – (required) Identifies whether to use automatic or manual reward selection. See RewardSelectionMode for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • checkNumber (String) – (required) The check number.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • pxTransactionId (Long) – (required) Unique Long value to identify this transaction
  • itemDiscounts (List[Object]) – (required) The list of per-item discounts applied to the check. See ItemDiscount for the format of the individual objects
  • multiItemDiscounts (List[Object]) – (required) The list of multi-item discounts applied to the check. See MultiItemDiscount for the format of the individual objects
  • subtotalDiscounts (List[Object]) – (required) The list of whole-check discounts applied to the check subtotal, or the whole check. See SubTotalDiscount for the format of the individual objects
  • chosenRewardsNotApplied (List[ChosenReward]) – (required) List of chosen rewards that were unable to be applied to the check. See ChosenReward for the format of the individual objects
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Reply Objects

AvailableUnitDiscount

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

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

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

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

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

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

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

JSON Parameters:
 
  • itemId (String) – (required) The ID of the item to which this discount could be applied.
  • unitDiscount (Decimal) – (required) Represents the per-unit discount that should be applied to an applicable item, e.g. if the value is 1.00 and there are two units of the item, the item’s total price should total discount should be reduced by 2.00. This will be a positive number.
Category
JSON Parameters:
 
  • categoryType (String) – (required) Either “major”, “minor”, or “promo”. Type of category if there are multiple types. Use “major” if there are no distinct category types.
  • id (String) – (required) Identifier for the category. This identifies the category in the POS database.
  • name (String) – (optional) Human-readable name for the category.
Check
JSON Parameters:
 
  • header (Object) – (required) The header to the check. Contains details about the check as as whole, such as check number, number of seats, time opened, etc. See Header for format
  • items (List[Object]) –

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

    • Single menu items (MenuItem) such as entrees, appetizers, and beverages.
    • Combo items (ComboItem) which represent combo meals, such as burger and fries.
    • Discount items (DiscountItem) which alter the check total (typically by reducing it) but are not directly tied to a single item.
    • Service charge items (ServiceChargeItem) which represent additional nontaxed service charges such as gift card purchases.
    • Tender items (TenderItem) which represent payments or other similar items, such as credit card payments, gift card payments, loyalty card swipes, or comp card payments.

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

  • totals (Object) – (required) The totals at the end of the check. See Totals for format
ChosenReward
JSON Parameters:
 
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant
  • amount (Decimal) – (required) Represents either the discount amount if applied to an item, or the wallet balance if the reward is applied to the transaction.
ComboItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a menu item. Must always be "comboItem".
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the combo item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the combo item. Typically a positive amount, unless voided. Should be calculated as unit price * quantity.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • modifiers (List[Object]) – (optional) Can be empty. A list of any modifiers (such as condiments) attached to the combo item. Defaults to empty. See Modifier for format
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the combo item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • items (List[Object]) – (required) List of menu items (see MenuItem for format) to be included in the combo
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.
CreditCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a credit card detail. Must always be "creditCard".
  • cardholder (String) – (optional) Name of the cardholder as captured from the credit card.
  • cardType (String) – (optional) Type of credit card. Must be one of “Visa”, “MasterCard”, “American Express”, “Diners Club”, “Discover”, “JCB”, or “other”.
  • iin (String) – (optional) IIN (first 6 digits) from credit card number.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from credit card number.
  • expiration (String) – (optional) Expiration date of the credit card. Format yyyy-MM-dd. Credit cards typically have no day of month component in the expiration date; please enter “01” in that case. For example, if the credit card expires 05/15, this field should be set to 2015-05-01.
DiscountItem

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

JSON Parameters:
 
  • type (String) – (required) Identifies this item as a discount item. Must always be “discountItem”.
  • itemId (String) – (required) Identifier for the discount item. This identifies the discount item in the Paytronix database, not the particular line item in the check.
  • multiItemDiscountId (Integer) – (optional) Identifier for a combo reward. This identifies the item as part of a combo reward.
  • name (String) – (optional) Human-readable description of the discount item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the discount item, if any.
  • quantity (Decimal) – (optional) Quantity of the discount item purchased. Typically "1". Defaults to 1.
  • isVoided (Boolean) – (optional) true if the discount item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the discount item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the discount item. Typically a negative amount (which reduces the check total), unless voided.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • discountSource (String) – (optional) One of "POS", "Loyalty", "Coupon"
  • walletCode (Integer) – (optional) A numeric identifier for a specific type of discount, unique for a given merchant. Populated based on the walletCode field in the ItemDiscount, SubtotalDiscount, or AvailableUnitDiscount which was applied. Must be present for Loyalty and Coupon Discounts
  • walletQuantity (Decimal) – (optional) Quantity of the wallet which was used. Populated based on the quantityRedeemed field in the ItemDiscount or SubtotalDiscount objects, or the unitDiscount field in a PossibleUse, depending on how the discount was applied to the check. Must be present for Loyalty Discounts
  • couponId (Integer) – (optional) Unique identifier of the coupon from which this reward came. Must be present for Coupon Discounts
GiftCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a gift card detail. Must always be "giftCard".
  • pxTransactionId (Long) – (optional) Paytronix transaction ID, if available and for a Paytronix gift card.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from gift card number.
Header
JSON Parameters:
 
  • number (String) – (required) Check number that appears on POS receipt. If this number is not guaranteed to be unique within the business day at the particular store, provide ‘uniqueIdentifier’ field as well. Maximum of 255 characters.
  • uniqueIdentifier (String) – (optional) Unique check identification number. Paytronix requires that this is unique within the business day at the particular store. This field should be entered if and only if ‘number’ field isn’t guaranteed to be unique within the business day at the particular store.
  • isReturn (Boolean) – (required) true if the check is a return check, i.e., a check containing one or more returned items. A check being marked this way does not affect the interpretation of the line items, it’s merely used as an additional data point for various analysis such as fraud analysis.
  • openTime (String) – (required) Date and time the check was opened, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • closeTime (String) – (optional) Date and time the check was closed, in UTC by default unless timezone offset specified. The format is yyyy-MM-dd HH:mm:ss [+-ZZZZ]
  • seatCount (Integer) – (optional) Number of seats.
  • tableNumber (String) – (optional) Table number or identifier.
  • revenueCenterNumber (Integer) – (optional) Identifier for revenue center (cost center) that the check was located in.
  • revenueCenterName (String) – (optional) Human readable description for revenue center (cost center) that the check was located in.
  • cashier (String) – (optional) Cashier (operator) ID.
  • properties (Map[String]) – (required) Can be empty. Additional POS-specific properties as strings. Defaults to empty.
  • isVoid (Boolean) – (optional) Flag to indicate whether the check is voided.
ItemDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique
  • multiItemDiscountId (Integer) – (optional) Identifier for a combo reward. This identifies the item as part of a combo reward.
  • name (String) – (required) Human-readable name of discount
  • referenceLine (String) – (optional) Directly corresponds to the referenceLine field of a menu or combo item in the request, and indicates that the discount should be applied to that specific item.
  • menuItemId (String) – (required) Directly corresponds to the itemId field of a menu or combo item in the request.
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • quantityDiscounted (Decimal) – (required) Quantity of the line item which is to be discounted.
  • unitDiscount (Decimal) – (required) This is the discount value divided by the quantityDiscounted. Usually ignored
  • discountType (String) – (required) One of “Percent”, “Dollar”, “ReducePrice”, “PerUnit”. Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • couponId (Integer) – (optional) ID of coupon, only returned in calls to simulateCoupon.
ItemizedTotal
JSON Parameters:
 
  • itemizerType (String) – (required) Either "sales" or "tax", depending on what is itemized
  • id (String) – (required) Identifier for the itemizer
  • total (Decimal) – (required) Itemized amount
LoyaltyCardTenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this detail as a loyalty card detail. Must always be "loyaltyCard".
  • pxTransactionId (Long) – (optional) Paytronix transaction ID, if available and for a Paytronix comp/loyalty.
  • masked (String) – (optional) Masked account number (typically last 4 digits) from comp/loyalty card number.
MenuItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a menu item. Must always be "menuItem".
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the menu item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the menu item. Typically a positive amount, unless voided. Should be calculated as unit price * quantity. This should not include the prices of the modifiers.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • modifiers (List[Object]) – (optional) Can be empty. A list of any modifiers (such as condiments) attached to the menu item. Defaults to empty. See Modifier for format
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the single menu item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.
Modifier
JSON Parameters:
 
  • itemId (String) – (required) Identifier for the menu item. This identifies the menu item in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the menu item.
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the menu item, if any.
  • quantity (Decimal) – (optional) Quantity of the menu item purchased. Typically "1". Defaults to 1.
  • categories (List[Object]) – (optional) Can be empty. Any categories the menu item is associated with. Defaults to empty. See Category for format
  • isVoided (Boolean) – (optional) true if the menu item is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the menu item is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the modifier. Typically a positive amount, unless voided. Should be calculated as unit price * quantity.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
  • discounts (List[Object]) – (optional) Can be empty. A list of any discounts that apply to the single menu item only, applicable for instance if a coupon has been applied. Defaults to empty. See DiscountItem for format
  • consumedQuantity (Decimal) – (optional) Consumed quantity of the menu item. Defaults to 0.
MultiItemDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique
  • name (String) – (required) Human-readable name of discount
  • discountObjectNumber (String) – (required) POS discount number to apply when redeeming this wallet as a reward.
  • posItemId (String) – (required) Unique identifier for item in the point of sale system
  • items (List[Object]) – (required) A list of sub item discounts. See SubItemDiscount for format
  • discountType (String) – (required) One of “Percent”, “Dollar”, “ReducePrice”, “PerUnit”. Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant. Must be present for Loyalty Discounts
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized. Must be present for Loyalty Discounts
  • totalDiscounted (Decimal) – (required) Total value discounted
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
ReceiptSetting
JSON Parameters:
 
  • name (String) – (required) Name of receipt printer
  • maxWidth (Integer) – (required) Width in characters of receipt
RewardSelectionMode
JSON Parameters:
 
  • mode (String) – (required) Either "automatic" or "manual"
  • chosenRewards (List[Object]) – (required if ``manual``) List of manually chosen rewards. See ChosenReward for the format of the objects
RewardToRemove
JSON Parameters:
 
  • itemId (String) – (required) A numeric identifier for the specific reward to be removed
  • reason (String) – (required) States the reason why the reward was unable to be applied
  • referenceLine (String) – (optional) Directly corresponds to the referenceLine field of a menu or combo item in the request, and indicates that the discount should be applied to that specific item.
ServiceChargeItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a service charge item. Must always be "serviceChargeItem".
  • itemId (String) – (required) Identifier for the service charge. This identifies the service charge in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the service charge
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the service charge, if any.
  • quantity (Decimal) – (optional) Quantity of the service charge purchased. Typically "1". Defaults to 1.
  • isVoided (Boolean) – (optional) true if the service charge is voided or removed from the check and does not affect the check total, nor was purchased or returned. Defaults to false.
  • isTaxable (Boolean) – (optional) true if the service charge is a taxable item which contributed to the tax total. Defaults to true.
  • price (Decimal) – (required) Price of the service charge. Typically a positive amount, unless voided.
  • fullPrice (Decimal) – (optional) If the price varies from the “base price” due to discounting, couponing, or similar, then this field should contain the base price before discounting.
SubItemDiscount
JSON Parameters:
 
  • referenceLine (String) – (optional) Reference line for the discount item, if any.
  • menuItemId (String) – (required) Directly corresponds to the itemId field of a menu or combo item in the request.
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • quantityDiscounted (Decimal) – (required) Quantity of the line item which is to be discounted.
  • unitDiscount (Decimal) – (required) This is the discount value divided by the quantityDiscounted.
SubTotalDiscount
JSON Parameters:
 
  • id (String) – (required) An identifier for this discount, as in a coupon number. Not guaranteed to be unique
  • name (String) – (required) Human-readable name of discount
  • discount (Decimal) – (required) Full amount by which the target item should be discounted.
  • discountType (String) – (required) One of "Percent", "Dollar", "ReducePrice", "PerUnit". Can be ignored.
  • walletCode (Integer) – (required) A numeric identifier for a specific type of discount, unique for a given merchant.
  • quantityRedeemed (Decimal) – (required) Actual number of points in the Paytronix wallet which will be redeemed when the transaction is finalized.
  • applyAutomatically (Boolean) – (required) Automatically apply discounts
  • couponId (Integer) – (optional) Id of coupon, only returned in calls to simulateCoupon.
TenderItem
JSON Parameters:
 
  • type (String) – (required) Identifies this item as a tender item. Must always be "tenderItem".
  • itemId (String) – (required) Identifier for the tender. This identifies the tender in the Paytronix database, not the particular line item in the check.
  • name (String) – (optional) Human-readable description of the tender
  • seat (Integer) – (optional) Seat number, if available.
  • referenceLine (String) – (optional) Reference line for the tender, if any.
  • amount (Decimal) – (required) Amount of the tender. Typically a negative amount (reducing the check total). Can be 0, such as in the case of loyalty cards that are not being used as comp cards.
  • detail (Object) –

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

Totals
JSON Parameters:
 
  • subTotal (Decimal) – (required) Sub total of menu, combo, and discount items. Calculated by summing the price field of each menu, combo, and discount item.
  • taxTotal (Decimal) – (required) Tax total. Typically calculated by taking the subTotal and multiplying by some appropriate tax rate.
  • discountTotal (Decimal) – (required) Total amount of discounts. Sign is relative to check total – that is, a negative amount indicates the check total was reduced by that amount. Calculated by summing the price of all discounts, no matter where they appear.
  • serviceChargeTotal (Decimal) – (required) Total of service charges
  • checkTotal (Decimal) – (optional) Check total before tenders and tips. checkTotal can be calculated from the individual totals via the following formula: subTotal + taxTotal + serviceChargeTotal
  • tipTotal (Decimal) – (optional) Total of tips, if known.
  • tenderTotal (Decimal) – (required) Total of tenders applied to the check. Typically a negative amount (reducing the check total).
  • itemizedTotals (List[Object]) – (required) Can be empty. Additional POS-specific itemized totals, such as totals by reporting group or similar. Defaults to empty. See ItemizedTotal for format
PriceMatchDiscountRecord
JSON Parameters:
 
  • itemId (String) – (required) Identifier for the PPU item. This identifies the PPU item in the Paytronix database, not the particular line item in the check.
  • originalPrice (Decimal) – (required) Original Price for PPU item. (Positive Number!)
  • discountAmount (Decimal) – (required) Price Match Discount Amount for PPU item. (Positive Number!)
PriceMatchDiscountRecordsForStoreCode
JSON Parameters:
 
  • storeCode (String) – (required) A store code to uniquely identify the store.

:jsonparam List[Object] priceMatchDiscounts (required) List of Price Match Discounts for this store. See PriceMatchDiscountRecord for details.

Error Codes

The following are the possible codes and messages that can be returned by the 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 POST check/simulateCoupon.json endpoint, which has a similar return type to POST check/simulateAccrualAndRedemption.json. If loyalty rewards also need to apply to the check, that will necessitate an additional call to POST check/simulateAccrualAndRedemption.json. After the check is finalized, simply call POST check/postAndAccruePointsWithRedeem.json with the check information, which will do its usual work on top of recording the coupon usage. Changes to POST check/postAndAccruePointsWithRedeem.json are as follows:

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

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

  • String discountSource: (required) One of "POS", "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 "POS" and none of those fields will be defined