Transaction Service

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

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 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 AccountQueryReply
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

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. Normally the storeName is displayed instead since the guest won’t know these codes
  • 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".
  • posTransactionId (String) – (optional) Check identifier (check number). This field is required for POST transaction/bulkActivateAdd.json requests
  • posTransactionDatetime (String) – (optional) Date and time the check was opened. No particular date format is required; Paytronix does not try to parse this value.
  • sequenceNumber (String) – (optional) Used in conjunction with posTransactionId and posTransactionDatetime to provide a unique identifier for a given transaction.
  • datetime (String) – (optional) Date and time the request was initiated. Formatted as ISO8601 date and time: yyyy-mm-ddThh:mm:ss[.sss]

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": "PX"
}
CardInfo

A card info structure contains information common to many transactions.

This information is specific to the gift or loyalty card being used in the transaction. The value of the swipeFlag determines which of the remaining elements is supplied by the message. If the swipeFlag is true then the trackInfo element must be supplied, which is the Track II information from the card’s magnetic stripe. If the swipeFlag is false then the printedCardNumber element must be supplied, which is the number printed on the face of the card. In the latter case it is assumed that the card number was entered manually or via bar-code reader.

JSON Parameters:
 
  • swipeFlag (Boolean) – (required) true to indicate a physical card was swiped using a mag card reader, false to indicate card was identified by other means such as manual number entry or bar code.
  • printedCardNumber (String) – (optional) Send only if swipeFlag is false. The number printed on the card.
  • trackInfo (String) – (optional) Send only if swipeFlag is true. The complete track two of the magnetic swipe data without the beginning and ending sentinel characters.

Manually entered card example:

"cardInfo": {
    "swipeFlag": false,
    "printedCardNumber": "1234567432131792"
}

Swiped card example:

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

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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so 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",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • pxTransactionId (Integer) – (optional) pxTransactionId for the corresponding non-void activate being voided. Note that if the previous transaction ID is known, it’s better to use the POST transaction/reverse.json endpoint.

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": "PX"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so 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",
        "senderId": "PARTNER",
        "programId": "PX"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • autoActivateCard (Boolean) – (optional) true if the card should automatically be activated if it is not already active

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": "PX"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • 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.

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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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",
        "senderId": "PARTNER",
        "programId": "LP"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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. 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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • addWalletContents (List[Object]) – (required) Amounts to void add (subtract) to wallets, such as appetizers bought or gift card stored value dollars. See WalletContent.
  • redeemWalletContents (List[Object]) – (required) Amounts to void redeem (add) from wallets, such as free appetizers bought or gift card stored value dollars. See WalletContent.
  • pxTransactionId (String) – (optional) pxTransactionId for the corresponding non-void add/redeem being voided. Note that if the previous transaction ID is known, it’s better to use the POST transaction/reverse.json endpoint.

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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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 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",
        "senderId": "PARTNER",
        "programId": "LP"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • addWalletContents (Sequence) – (required) Stored value amount to add. See WalletContent.

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"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • addWalletContents (List[Object]) – (required) Amount to void add (subtract) from stored value. The amount should match the face value of the card. See WalletContent.
  • pxTransactionId (Integer) – (optional) pxTransactionId for the corresponding non-void activate add being voided. Note that if the previous transaction ID is known, it’s better to use the POST transaction/reverse.json endpoint.

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"
    },
    "cardInfo": {
        "swipeFlag": false,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • 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 WalletContent.

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"
    },
    "firstCardInfo": {
        "swipeFlag": false,
        "printedCardNumber": "1234567432131792"
    },
    "lastCardInfo": {
        "swipeFlag": false,
        "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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "pageSize": 50,
    "accountQueries": [
        {
            "name": "firstname",
            "value": "RO"
        },
        {
            "name": "phonenum",
            "value": "7892221111"
        },
        {
            "name": "lastname",
            "value": "LES"
        },
        {
            "name": "postalcode",
            "value": "02115"
        },
        {
            "name": "email",
            "value": "ROB@AOL.COM"
        }
    ]
}
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. 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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • 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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "swipeFlag": true,
        "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.
  • promotionCode (String) – (optional) Particular promotion to use. Do not send unless directed to do so by Paytronix.
  • 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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "cardInfo": {
        "swipeFlag": false,
        "printedCardNumber": "1234567432131792"
    },
    "newCardInfo": {
        "swipeFlag": true,
        "trackInfo": "1234567432132985=4711101985000"
    }
}

Retrieve Program Configuration Objects

POST transaction/loadMap.json

The load map request is used to query the PXC 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).

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",
        "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 and LP-code for the original transaction request type (see table below).

JSON Parameters:
 
  • headerInfo (Object) – (required) Header information for the request, as covered above. Send PX as the programId for this request.
  • pxTransactionId (Integer) – (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

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",
        "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",
        "senderId": "PARTNER",
        "programId": "SV"
    },
    "previousPosTransactionId": "000673000001",
    "previousSequenceNumber": "12345",
    "previousPosTransactionDatetime": "2004-06-01 13:04"
}

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 (nteger) – (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.

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"
  • cardTemplateCode (Integer) – (required) Code to uniquely identify the card template
  • cardTemplateName (String) – (required) Name of the card template, e.g. "Loyalty Card"
  • 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 (Integer) – (required) Unique Int value to identify this transaction, this can be used to reverse a previous transaction. E.g. 148240240
  • pxTransactionIdLong (Long) – (required) Unique Long value to identify this 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.

When result is authorizedVariantSuccess":

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
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 (Integer) – (required) Deprecated parameter.
  • pxTransactionIdLong (Long) – (required) Paytronix-assigned unique identifier for the transaction. Replaces pxTransactionId
  • 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 [[#Transaction Reply]] 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
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 (Integer) – (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

walletType values:

Value Type of wallet
1 Internal
2 Add
3 Redeem
4 Stored Value
5 Charge

walletContents values:

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

productType values:

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 S 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 (Integer) – (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

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.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_promotion_code Invalid promotion code
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