Gift Service ¶

The gift service provides endpoints to to support a gift card integration.

Topics

Gift Service
- Endpoints
  - Sell
  - Reload
  - Balance
  - Redeem
  - Reverse
  - Cash Out
  - Exchange
- Request Objects
- Reply Objects

Endpoints ¶

Sell ¶

POST gift/sell.json¶

Activates a gift card and adds value to it.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the request, as covered above.
amount (Decimal) – (required) The dollar amount to add to the card.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.
externalTransactionId (String) – (optional) Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters.

"result": "success": Success

"result": "failure": Failure

Reload ¶

POST gift/reload.json¶

Adds value to a gift card that has already been activated.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the request, as covered above.
amount (Decimal) – (required) The dollar amount to add to the card.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.
externalTransactionId (String) – (optional) Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters.

"result": "success": Success

"result": "failure": Failure

Balance ¶

POST gift/balance.json¶

Redeems value off a gift card.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the request, as covered above.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.

"result": "success": Success

"result": "failure": Failure

Redeem ¶

POST gift/redeem.json¶

Retrieves the balance of a gift card.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the request, as covered above.
amount (Decimal) – (required) This amount combined with the tip below is the total amount that will be redeemed from the card.
tip (Decimal) – (optional) This optional tip amount combined with the amount above is the total amount that will be redeemed from the card.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.
externalTransactionId (String) – (optional) Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters.

"result": "success": Success

"result": "failure": Failure

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:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
pxTransactionId (Long) – (optional) A unique transaction identifier returned by Paytronix.
externalTransactionId (String) – (optional) A unique transaction identifier specified by the caller. One of pxTransactionId or externalTransactionId must be provided.

"result": "success": Success

"result": "failure": Failure

Cash Out ¶

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:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the request, as covered above.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.
externalTransactionId (String) – (optional) Unique transaction identifier. Can be used to reverse a transaction if the request times out. Maximum of 128 characters.

"result": "success": Success

"result": "failure": Failure

Exchange ¶

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:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
storeCode (String) – (required) A short code to uniquely identify the store where this transaction occurred.
cardInfo (Object) – (required) Card information for the active card which will be exchanged, as covered above.
newCardInfo (Object) – (required) Card information for the inactive card which assume the balance of the card above, as covered above.
checkNumber (String) – (optional) Check identifier (check number). Maximum of 255 characters.
cashier (String) – (optional) Identifier of the operator (cashier) who initiated the request. Maximum of 100 characters.
terminalId (String) – (optional) Identifier of the POS terminal that initiated the request. Maximum of 100 characters.

"result": "success": Success

"result": "failure": Failure

Request Objects ¶

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.

JSON Parameters:

printedCardNumber (String) – (optional) The number printed on the card.
trackInfo (String) – (optional) The complete track two of the magnetic swipe data without the beginning and ending sentinel characters.
barcode (String) – (optional) Barcode data for the card.
phoneNumber (String) – (optional) Phone number uniquely identifying the guest.
appleNfcVasPayload (String) – (optional) Base64 encoded Apple NFC VAS payload obtained from Apple NFC-enabled passes.
googleNfcVasPayload (String) – (optional) Base64 encoded Google NFC VAS payload obtained from Google Passes using SmartTap protocol.
accountToken (String) – (optional) Paytronix generated token that uniques identifies a loyalty account. Contact Paytronix for more details.
cardRegCode (String) – (optional) Send only if you wish to verify the registration code for the card. If null, then this param will be ignored.

Reply Objects ¶

Success¶

JSON Parameters:

result (String) – (required) Contains success
pxTransactionId (Long) – (required) Unique 64-bit signed integer value to identify this transaction. This can be used to reverse a previous transaction.
pxAuthCode (String) – (required) 6-digit random value
currentBalance (Decimal) – (required) Balance of the gift card, e.g. "25.00"
previousBalance (Decimal) – (optional) Previous balance of the gift card if the transaction altered the balance.
transactionAmount (Decimal) – (optional) The the gift card balance changed if the transaction altered the balance.
printedCardNumber (String) – (required) A unique identifier for the gift card.
maskedCardNumber (String) – (required) A masked card number suitable for display.
customerName (String) – (optional) The guest’s name if known.
cardTemplateCode (Int) – (required) Unique identifier for the card template
cardTemplateName (String) – (required) Name of the gift card template
tierCode (Int) – (required) Unique identifier for the guest’s tier.
tierName (String) – (required) Name of the guest’s tier.
posMessages (List[String]) – (required) Any messages to display.

Failure¶

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) A unique error code for the failure. errorMessage (String) – (required) The human readable error message of the failure.