Transaction Service ¶

The transaction service provides endpoints to activate, adjust, and inquire after cards. There is only one authentication method allowed for all endpoints:

B2B authentication

The Paytronix system implements many different requests, each with a corresponding reply set of use cases:

Use Case
Request	Reply
Activate loyalty card
`POST transaction/activate.json`	`TransactionReply`
Sell gift card
`POST transaction/activateAdd.json` (or its `corresponding void`)	`AddRedeemReply`
Add stored value to gift card
`POST transaction/addRedeem.json` (or its `corresponding void`)	`AddRedeemReply`
Sell gift cards in bulk
`POST transaction/bulkActivateAdd.json` (or its `reverse`)	`BulkAddReply`
Pay with Card
`POST transaction/addRedeem.json` (or its `corresponding void`)	`AddRedeemReply`
Redeem rewards
`POST transaction/addRedeem.json` (or its `corresponding void`)	`AddRedeemReply`
Check balance(s) of a gift or loyalty card
`POST transaction/balanceInquiry.json`	`TransactionReply`
Retrieve transaction history for a gift or loyalty card
`POST transaction/transactionHistory.json`	`TransactionHistoryReply`
Look up accounts by phone number, guest name, etc.
`POST transaction/accountQuery.json`	`AccountQueryReply`
Look up customers checked in via mobile app
`POST transaction/checkinsQuery.json`	`CheckinsQueryReply`
Identify customer and support rewards based on current visit
`POST transaction/identifyCustomer.json`	`TransactionReply`
Exchange damaged, missing, or virtual card for a new card
`POST transaction/exchange.json`	`TransactionReply`
Fetch loyalty configuration including reward configuration
`POST transaction/loadMap.json`	`LoadMapReply`
Reverse transaction (due to error or user action)
`POST transaction/reverse.json`	`TransactionReply`
Status Ping
`POST transaction/status.json`	`StatusReply`

Topics

Request and Reply Formatting ¶

All requests must contain the header structure (detailed below), and many use a common structure for card identification (also detailed below).

Request Objects ¶

HeaderInfo¶

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.
applicationId (String) – (optional) Application sending the request.
applicationVersion (String) – (optional) Version of application sending the request.
operatorId (String) – (required) Identifier of the operator (cashier) who initiated the request. Use "0" if not known.
senderId (String) – (required) Indicates the type of sender. Always use POS unless instructed otherwise by Paytronix.
programId (String) – (required) Indicates the type of program being implemented, one of "LP", "SV", "CH", or "PX". The value to send in this field is determined by the use case, see the documentation for each request for what value to use.
terminalId (String) – (required) Identifier of the POS terminal that initiated the request. If no terminal can be identified or not initiated from a terminal use "0". Maximum of 100 characters.
posTransactionId (String) – (optional) Check identifier (check number). This field is required for POST transaction/bulkActivateAdd.json requests. Maximum of 255 characters.
posTransactionDatetime (String) – (optional) Date and time the check was opened. No particular date format is required; Paytronix does not try to parse this value. Maximum of 20 characters.
sequenceNumber (String) – (optional) Used in conjunction with posTransactionId and posTransactionDatetime to provide a unique identifier for a given transaction. Maximum of 20 characters.
externalTransactionId (String) – (optional) Provides a unique identifier for a given transaction. Maximum of 128 characters.
datetime (String) – (optional) Date and time the request was initiated. Formatted as ISO8601 date and time: yyyy-mm-ddThh:mm:ss[.sss]
agentName (String) – (optional) Paytronix specific Security Agent name. Do NOT pass this field unless instructed by Paytronix.

Example:

"headerInfo": {
    "merchantId": 10101010,
    "storeCode": "corp",
    "operatorId": "1234",
    "terminalId": "1023",
    "posTransactionId": "999999",
    "datetime": "2004-06-01T13:10:01.001",
    "posTransactionDatetime": "2004-06-01 13:10:01Z",
    "senderId": "PARTNER",
    "programId": "PX"
}

CardInfo¶

A card info structure contains information common to many transactions.

This information is specific to the gift, loyalty, or comp card being used in the transaction. 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; 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.
phoneNumber (String) – (optional) Phone number uniquely identifying the guest. If the provided phone number is not unique, an error will be returned, and it is recommended that callers implement POST transaction/accountQuery.json instead.
barcode (String) – (optional) Barcode data for the card.
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.
identificationMethod (String) – (optional) An optional field that indicates how the guest identified themselves when it cannot be infered from the request. This is only needed if the integrator has a printed card number that they obtained from some method other than the guest manually entering it (i.e. an account query). In this case the integrator would send a printedCardNumber but would send an identificationMethod of ACCOUNT_QUERY. Possible values are: ACCOUNT_QUERY and LINKED_CC.

Manually entered card example:

"cardInfo": {
    "printedCardNumber": "1234567432131792",
    "cardRegCode": 1234

}

Swiped card example:

"cardInfo": {
    "trackInfo": "1234567432131792=4711101792000",
}

OrderMethod¶

Valid order methods include:

in store
online web
online app
online app - android
online app - ios
call in
call center
drive through
kiosk
3rd party ordering
smart home device ordering
other

DeliveryMethod¶

Valid delivery methods include:

dine in
pick up
in house delivery
curbside
drive through
3rd party delivery
other

Endpoints ¶

Activate a Card ¶

POST transaction/activate.json¶

The activate request activates a loyalty card. The card is given the appropriate fixed amount of loyalty wallets upon activation, so there is no wallet-content quantity sent in the message.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
cardInfo (Object) – (required) Card information for the request, as covered above.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    }
}

Void a Card Activation ¶

POST transaction/voidActivate.json¶

The void activate request returns a card to an inactive state if there have been no transactions between the activate and the void activate and is only appropriate for loyalty cards or certain special types of card. Use POST transaction/voidActivateAdd.json to deactivate a gift card.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
cardInfo (Object) – (required) Card information for the request, as covered above.
pxTransactionId (Long) – (optional) pxTransactionId for the corresponding non-void activate being voided.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    }
}

Check Balance of a Card ¶

POST transaction/balanceInquiry.json¶

A BalanceInquiry is used to request current balance information for a specified card in the Paytronix system. This is designed to provide information about both the stored value balance and some selected loyalty program information, if available, so the reply deals with all possible balance information. For pure stored value cards, only the stored value balance will be used.

The balance inquiry request contains just the common elements. Aside from the request element tags themselves, the request is identical to an activate request.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send `PX` as the `programId` for this request. cardInfo (Object) – (required) Card information for the request, as `covered above`.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    }
}

Identify a Customer Visit ¶

POST transaction/identifyCustomer.json¶

Identify Customer is almost identical to a Balance Inquiry except that it causes the PXS to run the rules engine. This is sometimes useful in that it makes it possible to modify a card’s wallet balances prior to any add/redeem transaction being performed, such as incrementing a cardholder’s visits wallet at the beginning of a transaction or granting rewards for the current visit.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
cardInfo (Object) – (required) Card information for the request, as covered above.
autoActivateCard (Boolean) – (optional) true if the card should automatically be activated if it is not already active
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    }
}

Add or Redeem Value From a Card Account ¶

POST transaction/addRedeem.json¶

The add redeem request is used to add value to a card or to redeem value from it, depending on the contents of the request.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. The programId should be set to SV for adding or redeeming value from a gift card, and LP for point accrual or reward redemption.
cardInfo (Object) – (required) Card information for the request, as covered above.
addWalletContents (List[Object]) – (required) Amounts to add to wallets, such as appetizers bought or gift card stored value dollars.
redeemWalletContents (List[Object]) – (required) Amounts to redeem from wallets, such as free appetizers bought or gift card stored value dollars.
autoActivateCard (Boolean) – (optional) true if the card should automatically be activated if it is not already active.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

This example adds $25.00 to the gift card 1234567432131792.

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "25.00"
        }
    ],
    "redeemWalletContents": []
}

This example redeems $14.25 in reward dollars (wallet code 1 in this case) from card 1234567432131792. Note that the quantity is a positive amount. Also note that the programId is LP to denote a loyalty redemption. It is deducted from the card because it is a redeem quantity, while an add quantity would add to the card’s value.

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "LP"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "addWalletContents": [],
    "redeemWalletContents": [
        {
            "walletCode": 1,
            "quantity": "14.25"
        }
    ]
}

Void an Addition or Redemption of Value From a Card Account ¶

POST transaction/voidAddRedeem.json¶

The void add/redeem request applies a “void add value” or “void redeem value” action to a gift card or a “void accrue points” or “void redeem rewards” action to a loyalty card. The void add/redeem request should be used to credit an account or to reverse a previous add or redeem. The void add/redee, request should also be used to remove balance from a gift card to facilitate a cash-out. See also the POST transaction/reverse.json endpoint which allows reversal of transactions in their entirety.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. The programId should be set to SV for voiding from a gift card, and LP for voiding point accruals or reward redemptions on a loyalty card.
cardInfo (Object) – (required) Card information for the request, as covered above.
addWalletContents (List[Object]) – (required) Amounts to void add (subtract) to wallets, such as appetizers bought or gift card stored value dollars. See AddWalletContent.
redeemWalletContents (List[Object]) – (required) Amounts to void redeem (add) from wallets, such as free appetizers bought or gift card stored value dollars. See RedeemWalletContent.
pxTransactionId (String) – (optional) pxTransactionId for the corresponding non-void add/redeem being voided.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

This example applies a “void add” of $25.00 to the gift card 1234567432131792. As a result the balance of the card will decrease by $25.00 if sufficient funds are available.

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "25.00"
        }
    ]
}

This example applies a “void redeem” of $14.25 reward dollars from card 1234567432131792. As a result the balance of the card will increase by $14.25 if the balance limit of walletCode 1 on the card is not reached.

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "LP"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "redeemWalletContents": [
        {
            "walletCode": 1,
            "quantity": "14.25"
        }
    ]
}

Activate a Stored Value (Gift) Card ¶

POST transaction/activateAdd.json¶

The activate add request activates a card and adds value to it as one action. This request is used to process a Sell Gift Card action at the point of sale terminal.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send SV as the programId.
cardInfo (Object) – (required) Card information for the request, as covered above.
addWalletContents (Sequence) – (required) Stored value amount to add. See AddWalletContent.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "55.00"
        }
    ]
}

Void a Stored Value (Gift) Card Activation ¶

POST transaction/voidActivateAdd.json¶

The void activate add request removes value and returns a card to an inactive state if there have been no transactions between the activate add and the void activate add. The stored value balance of the card must be $0.00 after removing value; the request will be denied otherwise.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send SV as the programId.
cardInfo (Object) – (required) Card information for the request, as covered above.
addWalletContents (List[Object]) – (required) Amount to void add (subtract) from stored value. The amount should match the face value of the card. See AddWalletContent.
pxTransactionId (Long) – (optional) pxTransactionId for the corresponding non-void activate add being voided.
isCatering (Boolean) – (optional) true Indicates whether current request is associated with a catering order.
orderMethod (String) – (optional) Order method associated with the current request. See above for possible values.
deliveryMethod (String) – (optional) Delivery method associated with the current request. See above for possible values.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "55.00"
        }
    ]
}

Activate a Batch of Stored Value Cards ¶

POST transaction/bulkActivateAdd.json¶

The bulk activate add request operates like a batch of POST transaction/activateAdd.json requests, activating and adding stored value to a series of cards.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send SV as the programId.
firstCardInfo (Object) – (required) First card in range to activate. See CardInfo.
lastCardInfo (Object) – (required) Last card in range to activate. See CardInfo.
numberOfCards (Integer) – (required) Number of cards expected to be in the range
discountPercent (String) – (real number) (optional) Discount percentage to apply, if allowed by the server
addWalletContents (List[Object]) – (required) Stored value amount to add to each card. See AddWalletContent.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "firstCardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "lastCardInfo": {
        "printedCardNumber": "1234567432140031"
    },
    "numberOfCards": 10,
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "55.00"
        }
    ]
}

Void a Bulk Stored Value (Gift) Activation ¶

POST transaction/reverseBulkActivateAdd.json¶

The bulk activate add request operates like a batch of POST transaction/voidActivateAdd.json requests, deactivating a series of cards.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send SV as the programId.
firstCardInfo (Object) – (required) First card in range to activate. See CardInfo.
lastCardInfo (Object) – (required) Last card in range to activate. See CardInfo.
numberOfCards (Integer) – (required) Number of cards expected to be in the range
discountPercent (String) – (real number) (optional) Discount percentage to apply, if allowed by the server
addWalletContents (List[Object]) – (required) Stored value amount to add to each card. See AddWalletContent.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "firstCardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "lastCardInfo": {
        "printedCardNumber": "1234567432140031"
    },
    "numberOfCards": 10,
    "addWalletContents": [
        {
            "walletCode": 0,
            "quantity": "55.00"
        }
    ]
}

Look Up Customer Accounts Using Phone Number or Other Fields ¶

POST transaction/accountQuery.json¶

Account Query (also called Account Lookup) can be used if a guest shows up at a store without a card and the user is registered. It provides card numbers, customer names and other information pertaining to customers that match the query criteria.

One can query the Paytronix server for a customer by customer First Name, Last Name, Phone Number, Postal Code, Email or a combination of those. See AccountQuery for more explanation on the possible query fields.

An implementation of Account Query is expected to display a screen where a server can enter the query criteria. Only the fields allowed by the merchant should be displayed (e.g. if the merchant decides not to allow query by Email, that field must not be displayed).

After one or more cards are found, the customer may be given the ability to use the card for certain kinds of activity as agreed with the merchant. The implementation should not need the server to write down the card number to use it later. In fact it must not display the card number at all (instead it should display the masked card number). Instead, when another activity, say Balance Inquiry, is about to be performed, the server must be given the ability to use the queried card number instead of swiping or typing a card.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send `PX` as the `programId`. pageSize (Integer) – (required) Maximum number of accounts to return accountQueries (List[Object]) – (required) Search parameters for query. See `AccountQuery`

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "pageSize": 5,
    "accountQueries": [
        {
            "name": "firstname",
            "value": "RO"
        },
        {
            "name": "phonenum",
            "value": "7892221111"
        },
        {
            "name": "lastname",
            "value": "LES"
        },
        {
            "name": "postalcode",
            "value": "02115"
        },
        {
            "name": "email",
            "value": "[email protected]"
        }
    ]
}

AccountQuery¶

JSON Parameters:
	name (String) – (required) The field to search. See below for valid fields. value (String) – (required) The value to search for in the field.

The valid query fields are listed below. Keep in mind that multiple fields can be sent in the query. When multiple fields are sent, they are ANDed together (resulting records must match ALL included query fields). It is also possible to query with partial information for all fields except cardnum and phonenum. For all partial information queries, at least two characters are required.

cardnum
username
firstname
lastname
postalcode
phonenum
email

Look Up Customer Account Checked in With a Mobile Application ¶

POST transaction/checkinsQuery.json¶

Checkins Query can be used in text or mobile app enabled programs to find guests that have checked in to the store recently via text message or mobile app. It provides Card numbers, customer names and other information pertaining to customers that have done so.

After one or more cards are found, the customer may be given the ability to use the card for certain kinds of activity as agreed with the merchant. The implementation should not need the server to write down the card number to use it later. In fact it must not display the card number at all (instead it should display the masked card number). Instead, when another activity, say Balance Inquiry, is about to be performed, the server must be given the ability to use the queried card number instead of swiping or typing a card.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send `PX` as the `programId`. pageSize (Integer) – (required) Maximum number of accounts to return shortCardNumber (String) – (optional) If supplied, look for a particular short card number supplied by the guest

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "pageSize": 50
}

Query Transaction History of a Card ¶

POST transaction/transactionHistory.json¶

A transaction history request can be sent to request recent transaction details for an account, similar to what a guest would see on the Paytronix guest web site. The request itself has only one field specific to the transaction history request which is the date to start getting transaction history from. The range of dates covered will be from this start date until the current day.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
cardInfo (Object) – (required) Card information for the request, as covered above.
dateStart (String) – (optional) Start date to start retrieving transactions. Format: yyyy-mm-dd
maxNumberOfResults (Integer) – (optional) Limits the results returned to the most recent X transactions.
limitToBalanceAffectingTransactions (Boolean) – (optional) If true only transaction that resulting in a change in wallet balances will be returned.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "trackInfo": "1234567432131792=4711101792000"
    }
}

Exchange a Physical or Virtual Card with Another ¶

POST transaction/exchange.json¶

The exchange request is used to exchange one card number for another, typically when the original plastic card is damaged or lost. It can also be used for reverse enrollment, customer acquisition, and mobile app programs where a virtual card number is generated by the system and the guest would like to switch to a physical card in the store.

The old (exchanged) card becomes unusable, and the new card must be inactive for the exchange to be successful.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send PX as the `programId` for this request. cardInfo (Object) – (required) Card information for the request, as `covered above`. newCardInfo (Object) – (required) Card to exchange to. See `CardInfo`.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "printedCardNumber": "1234567432131792"
    },
    "newCardInfo": {
        "trackInfo": "1234567432132985=4711101985000"
    }
}

Retrieve Program Configuration Objects ¶

POST transaction/loadMap.json¶

The load map request is used to query the PXS for information on what wallets, activation items and tender items which are relevant to this location. This information can be used to determine what POS items are being tracked, what rewards might be available (in the event that a redemption is being attempted without first running a balance inquiry) and what sorts of items will need to be inserted into the check as a result of various actions (i.e. gift card activation or paying with a card). Unlike most Paytronix API calls, loadMap.json should be made at regular intervals or when reloading the terminal, and cached.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send PX as the `programId` for this request.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    }
}

Reverse a Previously Submitted Transaction ¶

POST transaction/reverse.json¶

A reverse request is used to reverse a previous transaction. Only transactions that happened in the last seven days can be reversed.

The transaction to reverse can be specified in the message by one of the following combinations of request fields:

The pxTransactionId from the original transaction reply
The pxAuthCode from the original transaction reply and the card info used for the original transaction
The posTransactionId sequenceNumber and posTransactionDatetime for the original transaction

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
pxTransactionId (Long) – (optional) pxTransactionId from reply to transaction to reverse
pxAuthCode (String) – (optional) pxAuthCode from reply to transaction to reverse
previousPosTransactionId (String) – (optional) posTransactionId from transaction to reverse
previousSequenceNumber (String) – (optional) sequenceNumber from transaction to reverse
previousPosTransactionDatetime (String) – (optional) posTransactionDatetime from transaction to reverse
previousExternalTransactionId (String) – (optional) externalTransactionId from transaction to reverse

Reverse by pxTransactionId example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "pxTransactionId": 123456789
}

Reverse by previousPosTransactionId, previousSequenceNumber, and previousPosTransactionDatetime example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "previousPosTransactionId": "000673000001",
    "previousSequenceNumber": "12345",
    "previousPosTransactionDatetime": "2004-06-01 13:04"
}

Reverse by previousExternalTransactionId example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "previousExternalTransactionId": "1db0f1ce-2eff-4daa-a5c0-f67567cb7934"
}

Adjust a Wallet Directly for Administrative Purposes ¶

POST transaction/adminAdjust.json¶

Performs an admin adjust to a wallet with an optional expiration date.

JSON Parameters:

headerInfo (Object) – (required) Header information for the request, as covered above. Only the Merchant ID is required within the headerInfo Object.
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 should occur.
posTransactionId (String) – (required) Usually the “Check Number” sent from the POS
operatorId (Integer) – (required) Identifier of the operator (cashier) who initiated the request. Use 0 if not known.
printedCardNumber (String) – (required) Printed card number associated with the account to get information about
walletCode (Integer) – (required) Wallet to add or redeem from.
quantity (String) – (real number) (required) Amount to add or redeem
expiration (Object) – (optional) The expiration date for this adjustment. Only used when the wallet balance is being adjusted upwards. See Expiration
activityType (String) – (required) The transaction type. One of ADD, VOID_ADD, REDEEM, VOID_REDEEM.
comment (tring) – (optional) An optional comment to be associated with the transaction.
isCommentGuestVisible (Boolean) – (optional) Whether the comment should be visible by the guest on the transaction history page. Defaults to true if not provided.

Example:

{
    "headerInfo": {
      "merchantId":10101010
    },
    "merchantId": 10101010,
    "storeCode": "1",
    "posTransactionId": "123",
    "operatorId": "0",
    "printedCardNumber": "1010101090000467",
    "walletCode": 5,
    "quantity": "1",
    "expiration": {
        "date": "2020-01-02",
        "type": "absolute"
    },
    "activityType": "ADD",
    "comment": "This is an admin adjust"
}

Expiration¶

JSON Parameters:
	type (String) – (required) One of `relative` or `absolute`. date (String) – (optional) The date on which the wallet amount should expire formatted as `yyyy-mm-dd`. Send only if `type` is `absolute`. numberOfDays (Integer) – (optional) The number of days until the wallet amount will expire. Must be positive. Send only if type `` is ``relative.

Example of a relative expiration date:

{
    "expiration": {
        "numberOfDays": 5,
        "type": "relative"
    }
}

Example of an absolute expiration date:

{
    "expiration": {
        "date": "2020-01-02",
        "type": "absolute"
    }
}

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

For example:

{
    "result": "success",
}

"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.

Status Ping ¶

POST transaction/status.json¶

The status ping request is used to notify Paytronix the connectivity status of the Point Of Sale terminals. POS should wait until a number of minutes equal to the value of the nextStatusInterval response field has passed before sending the next status request to the PXS.

JSON Parameters:
	headerInfo (Object) – (required) Header information for the request, as `covered above`. Send PX as the `programId` for this request. Please include `agentName` field provided by Paytronix and send POS as `senderId`. versionInfo (String) – (optional) POS Software Version.

Example:

{
    "headerInfo": {
        "merchantId": 10101010,
        "storeCode": "corp",
        "operatorId": "1234",
        "terminalId": "1023",
        "posTransactionId": "999999",
        "datetime": "2004-06-01T13:10:01.001",
        "posTransactionDatetime": "2004-06-01 13:10:01Z",
        "senderId": "POS",
        "programId": "PX",
        "agentName": "POS 1"
    },
    "versionInfo": "1.3.1"
}

Error Codes ¶

The following are the possible codes and messages that can be returned by this resource.

There are other system-level errors which may be returned which may not be documented here.

The caller of the endpoint can use the returned error message value to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code	Message
`transaction.server_error`	Internal server error
`transaction.store_not_found`	Store not found
`transaction.store_closed`	Store closed
`transaction.invalid_merchant_id`	Invalid merchant ID
`transaction.invalid_wallet_code`	Invalid wallet code
`transaction.wallet_not_attached`	Invalid wallet code for this card template
`transaction.past_expiration_date`	Expiration date is in the past
`transaction.negative_days`	Negative number of days
`transaction.expiration_invalid_wallet_type`	Expiration not allowed for this wallet type
`transaction.expiration_invalid_activity_type`	Expiration not allowed for this activity type
`transaction.non_positive_quantity`	Quantity must be positive
`transaction.invalid_card`	Invalid printed card number
`transaction.invalid_account`	Invalid account
`transaction.invalid_integration`	Invalid integration
`transaction.transaction_denied`	Variable depending on the denial reason

Reply Objects ¶

TransactionReply¶

JSON Parameters:
	result (String) – (required) Contains one of `authorizedSuccess`, `authorizedVariantSuccess`, `denied`, `userDataError`, or `failure` indicating the disposition of the transaction. Consult the following sections for each type.

When result is authorizedSuccess:

JSON Parameters:

result (String) – (required) authorizedSuccess
responseCode (Integer) – (required) 200, 202, 210, 220 or 250
responseMessage (String) – (required) Authorized
posTransactionId (String) – (optional) echo of posTransctionId field from request
enrollDate (String) – (required) Enrollment date, e.g. "2013-08-01"
printedCardNumber (String) – (required) printed card number, e.g. "1010101090000317"
maskedCardNumber (String) – (required) masked card number, e.g. "000317"
isRegistered (Boolean) – (optional) Indicate whether the guest is registered
tierName (String) – (optional) Name of tier, e.g. "Unregistered"
tierCode (String) – (optional) Code to identify the tier, e.g. 0
cardTemplateCode (Integer) – (required) Code to uniquely identify the card template
cardTemplateName (String) – (required) Name of the card template, e.g. "Loyalty Card"
cardTypeName (String) – (required) Type of the card template. See CardTemplateType
customerName (String) – (optional) Name of customer. This could be an empty string if the information is not available
pxAuthCode (String) – (optional) 6-digit random value, e.g. "683290"
pxTransactionId (Long) – (required) Unique 64-bit signed integer value to identify this transaction, this can be used to reverse a previous transaction. E.g. 148240240
svCurrentBalance (Decimal) – (optional) Balance of Stored Value wallet, e.g. "25.00"
svTransactionAmount (Decimal) – (optional) Transaction amount of Stored Value wallet, e.g. "25.00"
svPreviousBalance (Decimal) – (optional) Previous balance of Stored Value wallet, e.g. "0.00"
svriFlag (Boolean) – (optional) Indicates whether Stored Value balance information is present in reply
expirationDate (String) – (optional) If the card is a gift card, this field displays the card’s expiration date in the form YYYY-MM-DD.
activationItem (Object) – (optional) What POS item to insert into the check for this activation. Only present for activations. See ActivationItem
balancePoints (List[Object]) – (optional) Point balances that cannot be directly redeemed. See BalancePoint.
rewardPoints (Sequence) – (optional) Point balances that can be redeemed. See BalancePoint.
anonymousAccountToken (String) – (optional) Unique String value to identify the guest.

When result is authorizedVariantSuccess:

This reply is received when the request could only be partially authorized, such as attempting to redeem greater balance than what was available on the card, or attempting to add or redeem decimal amounts to a wallet that only supports integer amounts. This reply will have similar fields as in authorizedSuccess except for:

JSON Parameters:
	result (String) – (required) `authorizedVariantSuccess` responseCode (Integer) – (required) 201 or 251 responseMessage (String) – (required) `Authorized Variant`

When result is denied:

This reply will have similar fields as in authorizedSuccess except for:

JSON Parameters:
	result (String) – (required) `denied` responseCode (Integer) – (required) a value between 300 and 399(inclusive) responseMessage (String) – (required) various error message based on `responseCode` errorCode (String) – (required) See Error Codes errorMessage (String) – (required) See Error Codes

When result is userDataError:

This reply will have similar fields as in authorizedSuccess except for:

JSON Parameters:
	result (String) – (required) `userDataError` responseCode (Integer) – (required) a value between 400 and 499(inclusive) responseMessage (String) – (required) various error message based on `responseCode` errorCode (String) – (required) See Error Codes errorMessage (String) – (required) See Error Codes

When result is failure:

This reply indicates a system error or failure

JSON Parameters:
	result (String) – (required) `failure` responseCode (Integer) – (required) a value between 600 and 699(inclusive) responseMessage (String) – (required) various error message based on `responseCode` errorCode (String) – (required) See Error Codes errorMessage (String) – (required) See Error Codes

AddRedeemReply¶

AddRedeemReply augments TransactionReply with additional reply fields in the following circumstances.

Take care to consult the quantity field as the value may have be different than requested if result is authorizedVariantSuccess.

When result is authorizedSuccess or authorizedVariantSuccess:

JSON Parameters:
	addWalletContents (List[Object]) – (optional) See `AddWalletContent` for format of this object. redeemWalletContents (List[Object]) – (optional) See `RedeemWalletContent` for format of this object. changedWalletContents (List[Object]) – (optional) See `ChangedWalletContent` for format of this object.

BulkAddReply¶

BulkAddReply augments TransactionReply and AddRedeemReply with additional reply fields:

JSON Parameters:

bulkMaskedCardNumbers (List[Object]) – (required) contains the masked card numbers of the activated cards
discountAmount (Decimal) – (optional) the discount amount per card e.g. "25.00"
discountPercent (Integer) – (optional) the discount percentage used to calculate the discountAmount based on purchase price
numberOfCards (Integer) – (required) the number of cards activated

CheckinsQueryReply¶

A check-ins query reply contains information on the guests that are checked into a particular store.

JSON Parameters:
	pageRecordCount (Integer) – The number of check-ins that were found and returned. totalRecordCount (Integer) – The total number of check-ins that were found, this may differ from the number of rows returned. rows (List[CheckinData]) – (required) The check-ins data. See `CheckinData` for format of this object.

StatusReply¶

JSON Parameters:
	nextStatusInterval (Integer) – (required) number of minutes to wait before sending the next status request to the PXS.

LoadMapReply¶

A load map reply contains information on what wallets, activation items and tender items which are relevant to this location. This information can be used to determine what POS items are being tracked, what rewards might be available (in the event that a redemption is being attempted without first running a balance inquiry) and what sorts of items will need to be inserted into the check as a result of various actions (i.e. gift card activation or paying with a card).

JSON Parameters:

requestEvent (String) – (required) LP-code of original request. Usually ignored.
posTransactionId (String) – (optional) posTransactionId from request. Usually ignored.
pxTransactionId (Long) – (required) Paytronix-assigned unique 64-bit signed integer identifying the transaction.
datetime (String) – (required) Date/time stamp when Paytronix processed the transaction. Do not parse this field, as the format may change.
pxAuthCode (String) – (optional) For authorized transactions, a Paytronix-assigned code for the authorization.
responseCode (Integer) – (required) Code indicating whether the transaction was authorized, denied, or had some other error. See Error Codes.
responseMessage (String) – (required) Text description of the status of the transaction, e.g. Authorized for responseCode of 200
senderId (String) – (required) Sender of the reply. Usually PXS but will be PXC for stored and forwarded transactions. Usually ignored.
activationItems (List[Object]) – (required) Items which might be returned in the activationItem field of TransactionReply for activation requests. See NamedItem.
tenderItems (List[Object]) – (required) Ignore this field. See NamedItem.
wallets (List[Object]) – (required) Wallets in the merchant’s program. See LoadMapWallet
properties (List[Object]) – (required) Additional properties associated with distinguished wallets. See LoadMapWalletProperty

TransactionHistoryReply¶

TransactionHistoryReply augments TransactionReply with additional reply fields:

JSON Parameters:

transactions (List[Object]) – (required) Contains the Paytronix transactions of the given card. See TransactionHistoryTransaction for additional info.
userFields (List[Object]) – (required) User information associated with the transactions of the given card. Usually just firstName and lastName but additional fields may be configured in Paytronix.
walletInfos (List[Object]) – (required) See TransactionHistoryWalletInfo for details

CardTemplateType¶

One of a list of card template types that a Paytronix card can belong to. Roughly reflects functionality.

Template Type	Meaning
`Gift`	Gift Card
`Loyalty`	Loyalty Card
`Gift & Loyalty`	Combined Gift & Loyalty Card
`Comp`	Comp Card
`Guest Comp`	Comp Card
`Manager Comp`	Comp Card
`Employee Comp`	Comp Card
`Test`	Test
`E-Club`	eClub-Only
`Charge`	No longer used

LoadMapWallet¶

The load map wallet structure represents a single wallet in the load map. It contains all of the information necessary to define how the POS should behave in regard to said wallet, such as the name of the wallet, its type (i.e. add, redeem, internal data tracking, stored value), product category information, item number of the discount which should be inserted, the type of reward it represents (i.e. fixed amount, open amount), etc.

JSON Parameters:

walletName (String) – (required) Name of the wallet.
walletCode (Integer) – (required) Identifying code for the wallet.
walletType (Integer) – (required) Type of wallet, see below.
walletContents (Integer) – (required) Contents of wallet, see below.
productType (Integer) – (required) Type of POS product associated with wallet, see below.
productId (String) – (required) Identifier for product(s). See productType for how to interpret this field.
productDefinition (String) – (optional) POS-specific definition for POSes or applications where productType and productId are not flexible enough.
discountObjectNumber (Integer) – (optional) POS discount number to apply when redeeming this wallet as a reward.
rewardType (Integer) – (optional) Type of reward. See RedeemWalletContent
valueType (Integer) – (optional) Value type of reward. See RedeemWalletContent
valueAmount (String) – (optional) Percentage off, dollar off, or particular POS discount as defined by valueFlag. See RedeemWalletContent
scale (Integer) – (required) Number of digits after the decimal place for balances of this wallet.
walletTags (List[Object]) – (required) Tags for this wallet. See WalletTag
autoRedeem (Boolean) – (required) Derives from the applyAutomatically flag in discount reply objects. Used by Check service integrations that respect this flag.
minimumSpendAmount (Decimal) – (optional) - The minimum amount to be spent for the reward to be applied.
checkServiceDiscountObjectNumber (Integer) – (optional) - The check service specific discount number to apply when redeeming this wallet as a reward.
checkServiceItemType (Integer) – (optional) - The check service specific product type associated with the wallet.
checkServiceProductInfo (String) – (optional) - The check service specific product item id associated with the wallet.
checkServiceRewardType (Integer) – (optional) - The check service specific reward type.
checkServiceValue (String) – (optional) - The check service specific value amount.
checkServiceValueType (Integer) – (optional) - The check service specific value type.
walletComboConditions (List[Object]) – (optional) - The check service specific combo conditions to determine whether the reward can be applied. See LoadMapWalletRewardCondition
walletBogoConfiguration (Object) – (optional) - The check service specific BOGO (Buy One Get One) configuration to determine whether the reward can be applied. See LoadMapWalletBogoConfiguration
posItemId (Integer) – (required) - Identifier for product(s). See productType for how to interpret this field.

WalletType¶

Value	Type of wallet
`1`	Internal
`2`	Add
`3`	Redeem
`4`	Stored Value
`5`	Charge
`6`	Member Reward

WalletContents¶

Value	Type of wallet content
`1`	Products
`2`	Internal points
`3`	Rewards
`4`	Products and rewards

ProductType¶

Value	Name	Meaning of `productId`
`1`	All	ignored
`2`	Major category	refers to a major category in the POS
`3`	Minor category	refers to a minor category in the POS
`4`	Menu item	refers to a particular menu item in the POS
`5`	Stored value	ignored
`6`	Charge	ignored
`7`	Revenue center	refers to a revenue center in the POS
`8`	Points	ignored
`9`	Check details	`1` means check subtotal `2` means seat count
`10`	Sales itemizer	refers to a sales itemizer in the POS
`11`	Wallet code	refers to a wallet
`12`	Tender
`13`	Major modifier
`14`	Minor modifier
`15`	Item modifier
`16`	Promotional Group

WalletTag¶

A tag representing additional information regarding a given wallet, to be interpreted by the client as desired

JSON Parameters:
	label (String) – (required) Human-readable label for this wallet tag code (Integer) – (required) Numeric code for this wallet tag data (String) – (required) String data for this wallet tag

LoadMapWalletProperty¶

This structure represents a special property of a wallet, which the POS may want to handle specially in regard to adding or redeeming from the wallet. It consists of a propertyEnumId and the associated wallet code.

JSON Parameters:
	propertyEnumId (Integer) – (required) Which property is associated with the wallet. See table below. walletCode (Integer) – (required) Wallet code being assigned a property.

propertyEnumId values:

Value	Meaning
13100	Visit Tracking
13101	Dollars Spent
13102	Visible Point Changes
13103	Stored Value
13104	Charge
13105	Manager Dollars
13106	Stored Value Discount
13107	Stored Value Redemption Fee

NamedItem¶

Named items represent special POS items. A good example of this is activationItem (sent with TransactionReply and LoadMapReply), which is used to indicate what item should be inserted into the check when a given card is activated.

JSON Parameters:
	itemType (Integer) – (required) Type of item in the POS. See `productType` field of `LoadMapWallet`. itemId (String) – (required) Identifier of item in the POS. See `productId` field of `LoadMapWallet`. quantity (real number) (String) – (required) Quantity of item. Usually `1`. name (String) – (required) Name of item

ActivationItem¶

JSON Parameters:
	itemId (String) – (required) POS Item ID.See `LoadMapWallet` above for how to interpret this value. itemType (Integer) – (required) POS Item Type. See `LoadMapWallet` above for a table of values. itemName (String) – (required) Name of item quantity (Decimal) – (required) Quantity

AddWalletContent¶

JSON Parameters:
	walletCode (Integer) – (required) Wallet code quantity (Decimal) – (required) Quantity

ChangedWalletContent¶

JSON Parameters:
	name (String) – (required) wallet label followed by `` Earned`` or `` Used`` operationType (Integer) – (required) operation type, see below walletCode (Integer) – (required) Wallet code quantity (Decimal) – (required) Quantity

operationType values:

Value	Type of operation
`1`	Add
`2`	Subtract
`3`	Void add
`4`	Void subtract

RedeemWalletContent¶

JSON Parameters:
	rewardType (Integer) – (required) Reward type discountItemId (String) – (required) POS discount item ID walletCode (Integer) – (required) Wallet code quantity (Decimal) – (required) Quantity

BalancePoint¶

JSON Parameters:
	pointName (String) – (required) Name of point wallet pointType (Integer) – (required) See `walletType` values in the section on `LoadMapWallet` points (Decimal) – (required) point balance walletCode (Integer) – (required) Wallet code expirationDates (List[Object]) – (required) See `ExpirationDate`

ExpirationDate¶

JSON Parameters:
	quantity (Decimal) – (required) point amount to be expired date (String) – (required) Expiration date

UserField¶

JSON Parameters:
	fieldEnumId (Integer) – (required) PX defined ID value for user field type value (String) – (required) value of user field

CheckinData¶

JSON Parameters:

nameOrPhone (String) – (optional) The name or phone number
integration (String) – (optional) The integration ID
relativeTime (String) – (optional) The length of time elapsed since the check-in time
shortCardNumber (String) – (optional) Short card number
checkNumber (String) – (optional) Check number
printedCardNumber (String) – (optional) Printed card number

LoadMapWalletBogoConfiguration¶

JSON Parameters:
	walletBogoOrder (Integer) – (required) The wallet BOGO order, either 1 (MAX) or 2 (MIN), to discount the high priced or lowest priced item respectively walletBogoConditions (List[Object]) – (required) The wallet bogo conditions. See `LoadMapWalletRewardCondition`

LoadMapWalletRewardCondition¶

JSON Parameters:
	posItemId (String) – (required) The POS item id productType (Integer) – (required) The product type quantity (String) – (required) The item quantity

Error Codes ¶

The following are the possible codes and messages that can be returned by the Transaction Service.

There are other system-level errors which may be returned which may not be documented here.

The caller of the endpoint can use the returned error message value to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code	Message
`transaction.denied`	Denied
`transaction.denied_retry`	Denied: Retry
`transaction.unactivated`	Unactivated
`transaction.exceeded_max_limit`	Denied: Exceeded max limit
`transaction.exceeded_min_limit`	Denied: Exceeded min limit
`transaction.no_value_in_account`	Denied: No value in account
`transaction.insufficient_value_in_account`	Denied: Insufficient value in account. Requested amount=%s Available amount=%s
`transaction.insufficient_credit_in_account`	Denied: Insufficient credit in account
`transaction.charge_not_positive`	Charge redeem must be positive amount, found %s
`transaction.stored_val_redeem_not_positive`	Stored value redeem must be positive amount, found %s
`transaction.amount_not_positive`	Add amount must be positive, found %s
`transaction.use_wallet_request_not_present`	Denied: No wallet for request
`transaction.void_wallet_request_not_present`	Denied: No wallet for void request
`transaction.add_wallet_request_not_present`	Denied: No POS request, PXS tried to reply
`transaction.could_not_save_wallets`	Denied: Could not save wallets
`transaction.no_rule_to_apply`	Denied: No rule to apply
`transaction.no_authorized_amounts`	Denied: No authorized amounts
`transaction.no_transaction_to_reverse`	Denied: No transaction to reverse
`transaction.error_making_rule_active`	Error making rule active
`transaction.no_transaction_to_sync`	Denied: No transaction to sync
`transaction.user_data_error`	User/data error
`transaction.card_number_checksum`	Card number checksum error %s
`transaction.null_card_number`	Null card number
`transaction.invalid_auth_code_generation`	Invalid auth-code generation
`transaction.invalid_merchant_id`	Invalid merchant ID %i
`transaction.invalid_rule_`	Invalid rule %i
`transaction.invalid_card_number`	Invalid card number %s
`transaction.invalid_card_account`	Invalid account for card %s
`transaction.card_has_been_exchanged`	Card %s has been exchanged
`transaction.no_loyalty_tier`	Merchant ID %i has no loyalty tier
`transaction.account_not_active`	Account %i not active
`transaction.card_not_enabled_for_loyalty`	Card %s not enabled for loyalty rules
`transaction.card_not_activated_for_loyalty`	Card %s is not active
`transaction.rule_not_active`	Rule %i not active
`transaction.merchant_not_active`	Merchant with ID %i not active
`transaction.account_status_cannot_activate`	Account status %i cannot activate
`transaction.invalid_rule_request_type`	Invalid rule request type %s
`transaction.card_status_cannot_become`	Card status %s cannot become %s
`transaction.card_status_cannot_be`	Card %s cannot be %s
`transaction.card_is_already_deactivated`	Card %s is already deactivated
`transaction.no_club_membership_to_remove`	No club membership to remove
`transaction.card_exchanged_and_cannot_reset`	Card %s has been exchanged and cannot be reset
`transaction.store_code_does_not_exist_for_merchant`	Store code %s does not exist for merchant ID %i
`transaction.card_not_in_required_state`	Card in %s state, %s state required
`transaction.card_not_active_could_be_auto_activated`	Card Not Active
`transaction.card_already_active`	Card Already Active
`transaction.card_not_suspended`	Card %s is suspended
`transaction.card_not_terminated`	Card %s is terminated
`transaction.card_not_active_or_suspended`	Card %s is not active or suspended
`transaction.account_has_no_regular`	Card has no Regular
`transaction.card_not_active`	Card %s cannot be deactivated
`transaction.card_already_has_rule`	Card %s already has rule %s
`transaction.card_already_has_loyalty`	Card %s already activated for loyalty
`transaction.invalid_card_block_number`	Invalid card block number %s
`transaction.error_issuing_cards`	Error issuing cards
`transaction.missing_product_for_wallet`	No product_id for add wallet %i
`transaction.missing_reward_for_wallet`	No reward_id for redeem wallet %i
`transaction.invalid_wallet_spec`	Invalid wallet spec %i
`transaction.cards_not_from_same_template`	Cards not from same template
`transaction.missing_template_for_card`	No template_id for card
`transaction.invalid_card_validation_code`	Level 1 Check, Invalid Card
`transaction.invalid_card_swipe_required`	Level 2 Check, Please Swipe the Card
`transaction.invalid_card_level_2_check`	Level 2 Check, Invalid Card
`transaction.invalid_card_level_3_check`	Level 3 Check, Invalid Card
`transaction.cannot_deactivate_sv_amount`	Card %s contains SV Dollars, cannot be Deactivated
`transaction.invalid_activation`	No activation filter for this type of card
`transaction.invalid_card_mask_length`	Invalid value for card_mask_length, length: %i
`transaction.enum_label_not_found`	Enum Label not found for %s
`transaction.bulk_multi_template`	Card range spans more than one card template
`transaction.bulk_multi_batch`	Card range spans more than one card batch
`transaction.no_activation_product`	No activation product for this type of card
`transaction.no_cards_in_range`	No cards in specified range
`transaction.no_task_found`	No task found or task already completed
`transaction.tvr_already_accepted`	This transaction variance has already been accepted
`transaction.cannot_download_config_file`	Cannot download config files
`transaction.cannot_activate_open_amount_sv_without_amount`	Cannot activate open amount SV card with $0.00.
`transaction.cannot_activate_fixed_amount_sv`	Must activate this fixed amount SV card with proper amount.
`transaction.manual_authorization`	Manual authorization needed
`transaction.system_error`	System error
`transaction.pos_error`	POS Error
`transaction.pxc_error`	PXC Error
`transaction.pxs_error`	PXS Error
`transaction.db_error`	DB Error number %i