Coupon Service

The coupon service provides endpoints for ensuring coupon code validity and recording/voiding coupon usage.

Request Objects

CouponRedemptionInfo

This object represents the packet of information to be recorded about the coupon usage. If the check number is not provided, then the coupon usage cannot be voided

JSON Parameters:
 
  • merchantId (Int) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • couponId (Int) – (required) Coupon ID as returned by validateCouponUsage
  • storeCode (String) – (required) Store Code of store at which coupon is being redeemed
  • redemptionDatetime (String) – (required) The time at which the coupon was redeemed. Valid format is “yyyy-MM-ddTHH:mm:ss”.
  • checkOpenDatetime (String) – (required) The time at which the coupon was opened. Valid format is “yyyy-MM-ddTHH:mm:ss”.
  • operatorId (Int) – (optional) Optionally specify the operator of the register
  • terminalId (String) – (optional) Optionally specify the register
  • checkNumber (String) – (optional) Optionally specify the check number (NOTE: for voidCouponUsage, a checkNumber is required)
  • integrationId (Int) – (optional) Optionally specify the integration
  • printedCardNumber (String) – (optional) Optionally specify a card number, if a check was associated with a loyalty customer

Endpoints

Validate Coupon Usage

GET coupon/validateCouponUsage.json

Attempts to find a currently-valid coupon based on the coupon code and merchant Id. The coupon must be configured in the PXS, and will have an associated Redeem Wallet which will determine the “reward” the coupon is valid for. If it finds a coupon, it will return this redeem wallet. Should be called by the entity processing the check before the check has been paid for.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • couponCode (String) – (required) The Coupon Code associated with the coupon, as configured in the PXS.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • couponId (Int) – (required) A unique integer that identifies the coupon found. Use this for reportCouponUsage
  • walletCode (Int) – (required) The wallet code of the redeem wallet associated with the coupon
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code validate_coupon.no_coupon indicates that no coupon was found. Other error codes will be given as a result of a configuration error or unexpected behavior
  • errorMessage (String) – (required) Further explanation of the error code

Report Coupon Usage

PUT coupon/reportCouponUsage.json

Records information about a coupon after it was applied to a given check, for reporting purposes. Should be called after a coupon has been applied to a check, on the condition that its reward was in fact used.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • couponRedemptionInfo (Object) – (required) Information to record. See CouponRedemptionInfo for details.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success No further action necessary
"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.

Void Coupon Usage

POST coupon/voidCouponUsage.json

Voids a particular coupon usage, removing it from reporting. Identifies a specific usage by check number, store code, and redemption date, so the check number must be specified in the corresponding call to reportCouponUsage.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • checkNumber (String) – (required) Check number associated with the coupon usage in reportCouponUsage call
  • storeCode (String) – (required) Store Code at which the coupon was used
  • redemptionDate (String) – (required) Date at which the coupon was used
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success No further action necessary
"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.