Gift Service ======================== The gift service provides endpoints to to support a gift card integration. .. contents:: Topics Endpoints --------- Sell ~~~~~~~~~~~~~~~~~ .. http:post:: gift/sell.json Activates a gift card and adds value to it. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the request, as :http:jsonentity:`covered above `. :jsonparam Decimal amount: *(required)* The dollar amount to add to the card. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. :jsonparam String externalTransactionId: *(optional)* Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Reload ~~~~~~~~~~~~~~~~~ .. http:post:: gift/reload.json Adds value to a gift card that has already been activated. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the request, as :http:jsonentity:`covered above `. :jsonparam Decimal amount: *(required)* The dollar amount to add to the card. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. :jsonparam String externalTransactionId: *(optional)* Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Balance ~~~~~~~~~~~~~~~~~ .. http:post:: gift/balance.json Redeems value off a gift card. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the request, as :http:jsonentity:`covered above `. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Redeem ~~~~~~~~~~~~~~~~~ .. http:post:: gift/redeem.json Retrieves the balance of a gift card. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the request, as :http:jsonentity:`covered above `. :jsonparam Decimal amount: *(required)* This amount combined with the tip below is the total amount that will be redeemed from the card. :jsonparam Decimal tip: *(optional)* This optional tip amount combined with the amount above is the total amount that will be redeemed from the card. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. :jsonparam String externalTransactionId: *(optional)* Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Reverse ~~~~~~~~~~~~~~~~~ .. http:post:: gift/reverse.json Reverses a gift card transaction. There are two ways to identify the transaction to reverse. If the caller received a response from Paytronix they can use the pxTransactionId from the reply to reverse the transaction. If the request timed out the caller can use the externalTransactionId they passed in the request to reverse the transaction. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Long pxTransactionId: *(optional)* A unique transaction identifier returned by Paytronix. :jsonparam String externalTransactionId: *(optional)* A unique transaction identifier specified by the caller. One of pxTransactionId or externalTransactionId must be provided. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Cash Out ~~~~~~~~~~~~~~~~~ .. http:post:: gift/cashOut.json Removes the remaining balance on a gift card so the guest can receive its value in cash. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the request, as :http:jsonentity:`covered above `. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. :jsonparam String externalTransactionId: *(optional)* Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Exchange ~~~~~~~~~~~~~~~~~ .. http:post:: gift/exchange.json Exchanges one gift card for another. Typically used to convert an eGift to a physical card or to replace a card when the original plastic card is damaged or lost. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant identifier (ID) in which to perform the operation. :jsonparam String storeCode: *(required)* A short code to uniquely identify the store where this transaction occurred. :jsonparam Object cardInfo: *(required)* Card information for the active card which will be exchanged, as :http:jsonentity:`covered above `. :jsonparam Object newCardInfo: *(required)* Card information for the inactive card which assume the balance of the card above, as :http:jsonentity:`covered above `. :jsonparam String checkNumber: *(optional)* Check identifier (check number). Maximum of 255 characters. :jsonparam String cashier: *(optional)* Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters. :jsonparam String terminalId: *(optional)* Identifier of the POS terminal that initiated the request. Maximum of 100 characters. .. http:response:: success :http:jsonentity:`Success` .. http:response:: failure :http:jsonentity:`Failure` Request Objects --------------- .. http:jsonentity:: CardInfo A structure containing card identifying information common to many transactions. This element provides a variety of ways to identify the guest's account. One of printedCardNumber, trackInfo, phoneNumber, barcode, appleNfcVasPayload, googleNfcVasPayload, or accountToken should be provided. ``cardRegCode`` is an optional parameter which functions as a PIN; if it is passed in the call then it will check the registration code against that card number and deny the transaction if the registration code does not match. :jsonparam String printedCardNumber: *(optional)* The number printed on the card. :jsonparam String trackInfo: *(optional)* The complete track two of the magnetic swipe data without the beginning and ending sentinel characters. :jsonparam String barcode: *(optional)* Barcode data for the card. :jsonparam String phoneNumber: *(optional)* Phone number uniquely identifying the guest. :jsonparam String appleNfcVasPayload: *(optional)* Base64 encoded Apple NFC VAS payload obtained from Apple NFC-enabled passes. :jsonparam String googleNfcVasPayload: *(optional)* Base64 encoded Google NFC VAS payload obtained from Google Passes using SmartTap protocol. :jsonparam String accountToken: *(optional)* Paytronix generated token that uniques identifies a loyalty account. Contact Paytronix for more details. :jsonparam String cardRegCode: *(optional)* Send only if you wish to verify the registration code for the card. If null, then this param will be ignored. Reply Objects ------------- .. http:jsonentity:: Success :jsonparam String result: *(required)* Contains ``success`` :jsonparam Long pxTransactionId: *(required)* Unique 64-bit signed integer value to identify this transaction. This can be used to reverse a previous transaction. :jsonparam String pxAuthCode: *(required)* 6-digit random value :jsonparam Decimal currentBalance: *(required)* Balance of the gift card, e.g. ``"25.00"`` :jsonparam Decimal previousBalance: *(optional)* Previous balance of the gift card if the transaction altered the balance. :jsonparam Decimal transactionAmount: *(optional)* The the gift card balance changed if the transaction altered the balance. :jsonparam String printedCardNumber: *(required)* A unique identifier for the gift card. :jsonparam String maskedCardNumber: *(required)* A masked card number suitable for display. :jsonparam String customerName: *(optional)* The guest's name if known. :jsonparam Int cardTemplateCode: *(required)* Unique identifier for the card template :jsonparam String cardTemplateName: *(required)* Name of the gift card template :jsonparam Int tierCode: *(required)* Unique identifier for the guest's tier. :jsonparam String tierName: *(required)* Name of the guest's tier. :jsonparam List[String] posMessages: *(required)* Any messages to display. .. http:jsonentity:: Failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* A unique error code for the failure. :jsonparam String errorMessage: *(required)* The human readable error message of the failure.