Guest Service

The guest service provides endpoints to obtain information about accounts, guests, and stores that is usually guest-facing.

Endpoints

Get Account Information (Balance Inquiry)

GET guest/accountInformation.json

Obtains information about an account including the wallet balances and the username associated with the account if it is registered to a user.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number associated with the account to get information about
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • username (String) – (required) Username registered for this account if applicable
  • accountStatus (String) – (required) Possible values in a success reply: ACTIVE, SUSPENDED
  • queryCardStatus (String) – (required) Possible values in a success reply: ACTIVE, DISABLED, EXCHANGED
  • isRegistered (String) – (required) true if the account is registered to a user, false otherwise
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
  • cardTemplateLabel (String) – (required) The name of the program (i.e., card template)
  • tierCode (Integer) – (required) Paytronix-assigned tier code identifying the which grouping to which this user belongs.
  • tierLabel (String) – (required) The name of the tier
  • fields (Object) – (required) See AccountFields for format of this object.
  • primaryCard (Object) – (required) Information about the current primary card associated with the account, which may differ from the requested printed card number when the account has multiple associated cards. Object has the format { "printedCardNumber": "1111222233334444", "maskedCardNumber": "334444", "status": "ACTIVE" }
  • additionalCards ([Object]) – (required) Information about additional cards associated with the account. Each object is the same format as primaryCard - { "printedCardNumber": "...", "maskedCardNumber": "...", "status": "..." }
  • storedValueBalance (Object) – (required) Information about the stored value balance of the account, if the account has stored value enabled. See BalanceInformation for format of the object.
  • chargeBalance (Object) – (required) Information about the charge balance of the account, if the account has charge enabled. See BalanceInformation for format of the object.
  • pointBalances ([Object]) – (required) Information about the point balances of the account. See BalanceInformation for format of the objects.
  • rewardBalances ([Object]) – (required) Information about the reward balances of the account. See BalanceInformation for format of the objects.

For example:

{
    "result": "success",
    "accountStatus": "ACTIVE",
    "additionalCards": [],
    "cardTemplateCode": 0,
    "cardTemplateLabel": "Loyalty Card",
    "fields": {
        "customerNumber": "",
        "externalAccounts": [],
        "perks": [
            {
                "code": 0,
                "label": "test1"
            },
            {
                "code": 1,
                "label": "test2"
            }
        ]
    },
    "pointBalances": [
        {
            "balance": "3.0000",
            "name": "Drink Stamps",
            "walletCode": 5
        }
    ],
    "primaryCard": {
        "maskedCardNumber": "200841",
        "printedCardNumber": "6000201000200841",
        "status": "ACTIVE"
    },
    "queryCardStatus": "ACTIVE",
    "rewardBalances": [
        {
            "balance": "0.0000",
            "name": "Birthday Free Drink",
            "walletCode": 3
        },
        {
            "balance": "1.0000",
            "name": "Free Drink",
            "walletCode": 6,
            "expirations": [
                {
                    "amount": 1,
                    "expirationDate": "2011-05-01"
                }
            ]
        }
    ],
    "storedValueBalance": {
        "balance": "0.0000",
        "name": "Stored Value",
        "walletCode": 0
    },
    "tierCode": 1,
    "tierLabel": "Platinum",
    "username": "mmhc-112310"
}
"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.
"result": "invalid_status"
JSON Parameters:
 
  • result (String) – (required) invalid_status
  • accountStatus (String) – (required) EXISTS, ACTIVE, SUSPENDED, TERMINATED, EXPIRED, ABANDONED
  • cardStatus (String) – (required) EXISTS, ACTIVE, DISABLED, EXCHANGED
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Get Account Information for eClub Account

GET guest/eClubAccountInformation.json

Obtains information about an account including the wallet balances associated with the account.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • email (String) – (required) Email address associated with the account to get information about.
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the eClub program to enroll the user in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • accountStatus (String) – (required) Possible values in a success reply: ACTIVE, SUSPENDED
  • queryCardStatus (String) – (required) Possible values in a success reply: ACTIVE, DISABLED, EXCHANGED
  • isRegistered (String) – (required) true if the account is registered to a user, false otherwise
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
  • cardTemplateLabel (String) – (required) The name of the program (i.e., card template)
  • tierCode (Integer) – (required) Paytronix-assigned tier code identifying the which grouping to which this user belongs.
  • tierLabel (String) – (required) The name of the tier
  • fields (Object) – (required) See AccountFields for format of this object.
  • primaryCard (Object) – (required) Information about the current primary card associated with the account, which may differ from the requested printed card number when the account has multiple associated cards. Object has the format { "printedCardNumber": "1111222233334444", "maskedCardNumber": "334444", "status": "ACTIVE" }
  • additionalCards ([Object]) – (required) Information about additional cards associated with the account. Each object is the same format as primaryCard - { "printedCardNumber": "...", "maskedCardNumber": "...", "status": "..." }
  • storedValueBalance (Object) – (required) Information about the stored value balance of the account, if the account has stored value enabled. See BalanceInformation for format of the object.
  • chargeBalance (Object) – (required) Information about the charge balance of the account, if the account has charge enabled. See BalanceInformation for format of the object.
  • pointBalances ([Object]) – (required) Information about the point balances of the account. See BalanceInformation for format of the objects.
  • rewardBalances ([Object]) – (required) Information about the reward balances of the account. See BalanceInformation for format of the objects.

For example:

{
  "result": "success",
  "accountId": 331123425,
  "accountStatus": "ACTIVE",
  "additionalCards": [

  ],
  "cardTemplateCode": 0,
  "cardTemplateLabel": "eClub",
  "enrollmentStore": {
        "code": "01",
        "label": "Store1"
  },
  "fields": {
        "enrollDate": "2015-04-22",
        "externalAccounts": [

        ],
        "perks": [

        ]
  },
  "isRegistered": true,
  "pointBalances": [

  ],
  "primaryCard": {
        "maskedCardNumber": "000571",
        "printedCardNumber": "92134000571",
        "status": "ACTIVE"
  },
  "queryCardStatus": "ACTIVE",
  "rewardBalances": [

  ],
  "tierCode": 0,
  "tierLabel": "eClub"
}
"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.
"result": "invalid_status"
JSON Parameters:
 
  • result (String) – (required) invalid_status
  • accountStatus (String) – (required) EXISTS, ACTIVE, SUSPENDED, TERMINATED, EXPIRED, ABANDONED
  • cardStatus (String) – (required) EXISTS, ACTIVE, DISABLED, EXCHANGED
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Get User Information by Username

GET guest/userInformation.json

Obtains information about an account including the wallet balances and the username associated with the account if it is registered to a user.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • username (String) – (required) Username associated with the account to get information about
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • fields (Object) – (required) See UserFields for format of this object.
  • primaryCardNumber (Object) – (required) Information about the current primary card associated with the account, which may differ from the requested printed card number when the account has multiple associated cards. Object has the format { "printedCardNumber": "1111222233334444", "maskedCardNumber": "334444" }

For example:

{
    "result": "success",
    "fields":
    {
        "address1":"307 Waverly Oaks Road",
        "address2":"A Building",
        "city":"Waltham",
        "country":"US",
        "dateOfBirth":"1990-07-18",
        "email":"ajames@paytronix.com",
        "firstName":"Anthony",
        "lastName":"James",
        "mobilePhone":"2223334444",
        "optIn":false,
        "phone":"8883335555",
        "postalCode":"02452",
        "salutation":"Mr.",
        "stateProvince":"MA",
        "username":"_px_38828819"
        "companyName":"Paytronix"
        "fax":"4444444444"
        "anniversaryDate":"1990-11-26"
    },
    "primaryCardNumbers":["6000208304000140"]
}
"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.

Get User Information by Printed Card Number

GET guest/userInformationByPrintedCardNumber.json

Obtains information about a user (name, address, phone, etc.).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number associated with the account/user to get information about
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • fields (Object) – (required) See UserFields for format of this object.
  • primaryCardNumber (Object) – (required) Information about the current primary card associated with the account, which may differ from the requested printed card number when the account has multiple associated cards. Object has the format { "printedCardNumber": "1111222233334444", "maskedCardNumber": "334444" }
"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.

Get User Information for an eClub Account

GET guest/eClubUserInformation.json

Obtains demographic information about an eClub account.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • email (String) – (required) Email address associated with the account to get information about
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the eClub program to enroll the user in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • fields (Object) – (required) See UserFields for format of this object.
  • primaryCardNumber (Object) – (required) Information about the current primary card associated with the account, which may differ from the requested printed card number when the account has multiple associated cards. Object has the format { "printedCardNumber": "1111222233334444", "maskedCardNumber": "334444" }

For example:

{
  "result": "success",
  "fields": {
        "dateOfBirth": "1990-01-01",
        "email": "test.mctest@test.com",
        "emailVerified": false,
        "firstName": "Test",
        "lastName": "McTesterson",
        "optIn": true,
        "phone": "9708675309",
        "smsOptInVerified": false,
        "textCampaignOptIn": false
  },
  "primaryCardNumbers": [
        "90012330571"
  ]
}
"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.

Get Transaction History for Account

GET guest/transactionHistory.json

Obtains transaction history for an account.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Card Number of the account
  • dateStart (Datetime) – (required) Limits the result to transactions that have happened since the date specified, in the format: yyyy-MM-dd (e.g. 2012-03-23)
"result": "success"
JSON Parameters:
 

For example:

{
    "walletInfo": [
        {
            "name": "Stored Value",
            "scale": 2,
            "walletCode": 1
        },
        {
            "name": "Free Donut",
            "scale": 0,
            "walletCode": 2
        }
    ],
    "transactions": [
        {
            "authorized": true,
            "datetime": "2012-03-23 12:01:53 -0400",
            "details": [
                {
                    "accrued": "2.34",
                    "balance": "5.89",
                    "redeemed": "0.0",
                    "walletCode": 1
                },
                {
                    "accrued": "0",
                    "balance": "4",
                    "redeemed": "1",
                    "walletCode": 2
                }
            ],
            "guestType": true,
            "operatorId": 32,
            "posTransactionNumber": "15",
            "pxAuthCode": "654321",
            "sender": "POS",
            "storeMerchant": "PX Pastries",
            "storeName": "Waltham Store",
            "storeNumber": "464",
            "terminalId": "term1",
            "transactionId": 12345
        },
        {
            "authorized": true,
            "datetime": "2012-03-23 12:01:53 -0400",
            "details": [
                {
                    "accrued": "1",
                    "balance": "5",
                    "redeemed": "0",
                    "walletCode": 2
                }
            ],
            "guestType": true,
            "operatorId": 12,
            "posTransactionNumber": "76",
            "pxAuthCode": "733745",
            "sender": "POS",
            "storeMerchant": "PX Pastries",
            "storeName": "Boston Store",
            "storeNumber": "844",
            "terminalId": "term6",
            "transactionId": 67890
        }
    ]
}
"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.

Get Transaction Annotation for Account and Transaction

POST guest/transactionAnnotation.json

Retrieves guest-visible CSR and system comments for a transaction.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation.
  • accountId (Integer) – (required) Account ID of the account
  • transactionId (Long) – (required) Transaction ID of the transaction being queried.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • annotation (Object) – (required) See TransactionAnnotation for format of this object.

For example:

{
    "result": "success",
    "annotation":{
        "comment": "A guest-visible CSR Comment",
        "systemComment": "A guest-visible system comment"
    }
}
"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.

Reset User Password

POST guest/resetPassword.json

Resets the password of the account specified by either the username, printedCardNumber or email. Only one of these three should be provided, and it is considered an error if more than one is sent.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (See description) Printed card number associated with the account
  • username (String) – (See description) The username associated with the account
  • email (String) – (See description) Email address associated with the account
  • passwordHintAnswer (String) – (optional) The answer to the password question if one is defined on the account
  • resetCode (String) – (optional) Value is inserted into the reset password email as a replacement parameter. Commonly used to append a URL parameter to a link in the reset password email to identify the guest.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • email (String) – (required) The email address to where the password information was emailed.
"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.
"result": "more_info"
JSON Parameters:
 
  • result (String) – (required) more_info
  • fields (List[String]) – (required) A list of fields (for account verificatino) which must be provided when retrying the resetPassword call.
  • passwordHintQuestion (String) – (optional) The text of the password hint question if the question must be answered to complete the resetPassword call.

Attach Another Card to a User

POST guest/attachCard.json

Attaches another card to the user’s account.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number associated with the account.
  • otherPrintedCardNumber (String) – (required) The “other” printed card number to be attached.
  • otherRegistrationCode (String) – (required) The registration code associated to the “other” printed card number (only if one exists).
  • otherUsername (String) – (required) The username associated to the “other” card (if that card is already registered)
  • otherPassword (String) – (required) The password associated to the “other” card (if that card is already registered)
"result": "success"
JSON Parameters:
 
  • result (String) – (required) 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.
"result": "more_info"

If the account requires more information than just the card number. For each field name returned, prompt the user for its value and resubmit the call.

If the card has a registration code associated with it, then the field name registrationCode will be returned.

If the card is already registered to another user, then the fields username and password will be returned.

JSON Parameters:
 
  • result (String) – (required) more_info
  • fields (List[String]) – (required) A list of fields (for account verification) which must be provided when retrying the attachCard call

Combine Attached Card Balances

POST guest/combineCard.json

Combines a card (already attached to a user) to the main account of the same template linked to the current user.

Main account of a template is determined by number of previously combined cards, account status, enrollment date, status of primary card of the account, and printed card number.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number to be combined.
  • otherPrintedCardNumber (String) – (required) Obsolete as of v14.10. In a previous version, this is the “other” printed card number to be combined.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) 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.
"result": "accountSuspended"

Depending on the server-side configuration, the cardholder’s account may be suspended in cases where they combine too many cards to a single account. This behavior represents a potential fraud concern, though it may not be desirable to explicitly state such a concern to the user. The user would usually be directed to contact the merchant’s customer service department to resolve the issue

JSON Parameters:
 
  • result (String) – (required) accountSuspended
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Check If Cards Can Be Combined

GET guest/isCardCombinable.json

Check whether a card can be combined to the main account.

Main account of a template is determined by number of previously combined cards, account status, enrollment date, status of primary card of the account, and printed card number.

A card is combinable if it is not the main account and combine is enabled for the card template

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number to be tested.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • isCombinable (Boolean) – (required) True if card can be combined
"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.

Enable / Disable a Card

POST guest/changeCardStatus.json

Allows the guest to disable their card in the event of a lost or stolen card.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number to disable or enable
  • status (String) – (required) The status to assign to the card. Valid values are ACTIVE or DISABLED.

For example:

{
  "result": "success"
}
"result": "success"
JSON Parameters:
 
  • result (String) – (required) 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.

Get List of Referrals For User

GET guest/referrals.json

Return the list of referrals for the user/account

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • username (String) – (required) Username associated with the account to get information about. If you are OAuth authentication you must provide this parameter.
  • printedCardNumber (String) – (required) Printed card number associated with the account/user to get information about
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • numberOfAvailableUserReferrals (Integer) – (required) The number of referrals available for the user/account
  • userReferrals (List[Object]) – (required) See UserReferralFields for format of this object.
  • numberOfAvailableBulkReferrals (Integer) – (required) The number of referrals available for the CSR on behalf of the account/user
  • bulkReferrals (List[Object]) – (required) See BulkReferralFields for format of this object.
"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.

Refer Loyalty Program to Others

POST guest/addReferrals.json

Add new referrals to this account/user. Emails will be sent to each referent.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • username (String) – (required) Username associated with the account to get information about
  • printedCardNumber (String) – (required) Printed card number associated with the account/user to get information about
  • emails (List[String]) – (required) A list of email addresses of the referents
  • message (String) – (required) A message included in each email sent
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • numberOfAvailableUserReferrals (Integer) – (required) The number of referrals available for the user/account
  • userReferrals (List[Object]) – (required) See UserReferralFields for format of this object.
  • numberOfAvailableBulkReferrals (Integer) – (required) The number of referrals available for the CSR on behalf of the account/user
  • bulkReferrals (List[Object]) – (required) See BulkReferralFields for format of this object.
"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.

Create Referral Code for Referring Many

POST guest/createReferralCode.json

Create a code that can be used by others during enrollment, which maps back to a single referrer.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation.

There are two ways to call this endpoint:

Option One - Include the following:

JSON Parameters:
 
  • printedCardNumber (String) – (required) Printed card number associated with the account/user

Option Two - Include the following:

JSON Parameters:
 
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program in which to enroll the user.
  • username (String) – (required) Username associated with the account on which you’d like information.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (String) – (required) The referral code
  • name (String) – (required) The name of the referrer associated to this code (if available).
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
  • url (String) – (required) The URL will be a string representation of the specific reverse-enroll URL for the individual and card template type.
"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.

Validate a Referral Code

POST guest/validateReferralCode.json

Validate the given referral code.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • code (String) – (required) The referral code
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (String) – (required) The referral code
  • name (String) – (required) The name of the referrer associated to this code (if available).
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
"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.

Get Pending Event Rewards

GET guest/pendingEventRewards.json

Get pending event rewards.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • printedCardNumber (String) – (required) Printed card number associated with the account to get information about
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • rewards ([Object]) – (required) See PendingEventReward
"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.

Constant Values

Referral status Values

INVITATION_SENT
Invitation (email) sent by referrer
ENROLLED
The referent has enrolled but has not yet satisfied the conditions for rewarding the referrer
REWARD_EARNED
The referrer has earned their reward from this referral
CARD_LINKED
Bulk card associated to this account
CARD_USED
Bulk card used but has not yet satisfied the conditions for rewarding the referrer<br/>

Reply Objects

BalanceInformation

Balance information is returned in several locations in the reply and gives information about a single wallet for the account. A wallet is a discrete balance associated with the account, such as “Points”, “Stored Value”, or “Free Bagels”.

JSON Parameters:
 
  • walletCode (Integer) – (required) Code number for the wallet. This will never change for a particular wallet unless Paytronix makes a specific change to do so. For example, wallet code 0 might be associated with “Points”.
  • name (String) – (required) Human readable label for the wallet which may change over time. Should only be used for display to a user, as the name might change from time to time.
  • balance (Decimal) – (required) Current balance of the wallet, e.g. "120.33"
  • expirations ([Object]) – (required) List of expiring balances, if some or all of the balance of the wallet might expire. Each object is of the form { "amount": "12", "expirationDate": "2011-05-01" }
  • additionalExpiringBalance (Decimal) – (required) Points balance which will expire at some later date(s) not explicitly shown
  • giftable (Boolean) – (required) True if items in this wallet can be sent as a gift.
  • description (String) – (required) If available, this is a long description of the wallet.
  • imageCode (String) – (required) If available, this is a code or partial URL or absolute URL used to specify an image of the wallet.
  • link (String) – (required) If available, this is a URL for a page describing the wallet.
  • linkLabel (String) – (required) If available, this is the label for the link.
  • tinyName (String) – (required) Tiny version of wallet name.
  • shortName (String) – (required) Short version of wallet name.
  • longName (String) – (required) Long version of wallet name.
AccountFields

Additional account information can be supplied in the "fields" member of the reply:

JSON Parameters:
 
  • customerNumber (String) – (required) The external customer number of the account, usually used to maintain accurate tracking with an external billing or customer tracking system. Its use varies by program.
  • perks ([Object]) – (required) Any perks associated with the account, in the form { "code": 123, "label": "Gluten free" }
  • perksModifiedDate (Date) – (required) The last time the perks were modified for this account
  • favoriteStore (Object) – (required) User’s Favorite Store formatted as {"name": "Store 1", "code": "001"}
  • enrollDate (Date) – (required) The date the account was enrolled
  • externalAccounts ([Object]) – (required) List of associations with external accounts in other systems (e.g., social media). Each object has the format: { "integration": "see below", "accountCode": "..." }

Possible externalAccount values:

  • Facebook - xhDE_Ea4QhsfC8h3pUtHJnLZ9lRXYgysJVXnR4XNO0
  • Foursquare - 1gVdgGicN7m7MD9BxzXar2uqCnH3I4Qf7Zcw2mjYXL
  • Twitter - LUozKjcV2jxM0B4Gueb6kzH7W_5UPqZ_5zkOJgjpCe

Please note that additional setup is required to use externalAccounts.

UserFields

Additional account information can be supplied in the "fields" member of the reply:

JSON Parameters:
 
  • optIn (bool) – (required) Whether or not the user has opted to receive information about special offers etc.
  • salutation (string) – (required) “Mr.”, “Ms.”, “Mrs.”, “Dr.” or “Rev.”
  • firstName (string) – (optional)
  • lastName (string) – (optional)
  • email (string) – (optional)
  • address1 (string) – (optional)
  • address2 (string) – (optional)
  • city (string) – (optional)
  • stateProvince (string) – (optional)
  • postalCode (string) – (optional)
  • phone (string) – (optional)
  • fax (string) – (optional)
  • mobilePhone (string) – (optional)
  • dateOfBirth (string) – (optional)
  • anniversaryDate (string) – (optional)
  • country (string) – (optional)
  • passwordHintQuestion (string) – (optional)
  • username (string) – (optional)
  • emailVerified (bool) – (optional) Whether or not the user’s email address has been verified.
  • relatedGuests (List[Object]) – (optional) See RelatedGuests for format of these objects.
RelatedGuests

Information pertaining to a guest related to an account holder. This user does not have an account of their own.

JSON Parameters:
 
  • relatedGuestCode (int) – (required) Unique number identifying the related guest
  • firstName (string) – (required)
  • lastName (string) – (required)
  • email (string) – (optional)
  • dateOfBirth (string) – (optional)
  • salutation (string) – (optional) “Mr.”, “Ms.”, “Mrs.”, “Dr.” or “Rev.”
TransactionHistoryWalletInfo

Columns describe all the possible wallets used in the transactions. The walletCode in the columns will correspond to the walletCode in the details inside the transactions.

JSON Parameters:
 
  • walletCode (Integer) – (required) Code for the wallet.
  • name (Integer) – (required) The name of the wallet
  • scale (Integer) – (required) The scaling factor for the Decimal wallet amount in the Details
TransactionHistoryTransaction

Additional account information can be supplied in the "fields" member of the reply:

JSON Parameters:
 
  • transactionType (String) – (required) The name of the transaction
  • guestType (Boolean) – (required) True if this transaction should be displayed to the user (guest).
  • authorized (Boolean) – (required) True if this transaction was authorized. If false, do not display this transaction to the user (guest)
  • transactionId (Integer) – (required) The unique id of this transaction
  • posTransactionNumber (String) – (required) Usually the “Check Number” sent from the POS
  • datetime (String) – (required) The date and time the transaction occurred
  • storeMerchant (String) – (required) The name of the merchant
  • 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
  • storeName (String) – (required) Full name of the store
  • terminalId (String) – (required) Internal to Paytronix
  • operatorId (Integer) – (required) Internal to Paytronix
  • sender (String) – (required) Internal to Paytronix
  • promotionName (String) – (required) Internal to Paytronix
  • pxAuthCode (String) – (required) Internal to Paytronix
  • details (List[Object]) – (required) See TransactionHistoryDetail for format of these objects.
TransactionHistoryDetail

The details of the change to a particular wallet

JSON Parameters:
 
  • walletCode (Integer) – (required) Code for the wallet.
  • accrued (Decimal) – (required) The amount added to this wallet during the transaction
  • redeemed (Decimal) – (required) The amount removed to this wallet during the transaction
  • accrued(required) The final balance of the wallet after the accrued and redeemed values have been applied to the wallet
TransactionAnnotation

The guest-visible comments of a particular transaction

JSON Parameters:
 
  • comment (String) – (optional) The CSR comment for a transaction, if it exists and is guest-visible
  • systemComment (String) – (optional) The system comment for a transaction, if it exists and is guest-visible
UserReferralFields

Information about each referral initiated by the account/user:

JSON Parameters:
 
  • email (String) – (required) The email to which he referral was sent.
  • status (String) – (required) See Referral status Values.
  • reward (String) – (required) The reward earned by the referrer
BulkReferralFields

Information about each bulk referral. A bulk referral is when the referrer does not explicitly identify the people to refer. There are 2 types of bulk referrals:

  1. A CSR associates a group of anonymous cards to an account.
  2. An encrypted referralCode is embedded in an enrollment link inside an email or posted on a social media site.
JSON Parameters:
 
  • detail (String) – (required) The masked card number linked to this referral if the bulk referral was by anonymous cards or the name of the referent if the bulk referral was created using a referralCode
  • status (String) – (required) See Referral status Values.
  • reward (String) – (required) The reward earned by the referrer
PendingEventReward

Information about a pending reward in an account which is part of an active ActionToLoad event but the reward has not yet converted to a redeemable reward in the account.

Error Codes

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

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

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

Code Message
account_info.error failed to perform operation
account_info.invalid_card could not load given card
account_info.invalid_account could not load account
account_info.invalid_user could not load user
account_info.invalid_card_status card in invalid state
account_info.invalid_account_status account in invalid state
account_info.no_template_error no card template associated with account
account_info.no_tier_error no tier associated with account
attach_card.error Failed to perform operation
attach_card.invalid_card Could not load card
attach_card.invalid_other_card Could not load other card
attach_card.invalid_account Could not load account
attach_card.invalid_user Could not load user
attach_card.invalid_address Could not load address
attach_card.not_enabled Attach Card feature not enabled
attach_card.invalid_reg_code Other registration code is invalid
attach_card.already_attached Other card already attached
attach_card.account_not_active Account not active
attach_card.card_not_active Card not active
attach_card.other_account_not_active Other account not active
attach_card.other_card_not_active Other card not active
attach_card.user_pwd_invalid Other username or password invalid
attach_card.invalid_card_template Could not load other card template
combine_card.error Failed to perform operation
combine_card.not_enabled Combine Card feature not enabled
combine_card.not_attached The other card does not exist or is not attached to this account
combine_card.not_combinable_template Cards of this type cannot be combined
combine_card.same_card Cannot combine a card with itself
combine_card.already_combined The specified cards are already combined
combine_card.account_not_active Account not active - cannot combine an account that is not active
combine_card.card_not_active Card not active - cannot combine a card that is not active
combine_card.other_account_not_active Other account not active - cannot combine with an account that is not active
combine_card.other_card_not_active Other card not active - cannot combine with a card that is not active
combine_card.invalid_card Could not load card
combine_card.invalid_other Could not load other card
combine_card.combine_different_templates Cannot combine cards of different types
combine_card.account_suspended Account suspended. Contact support.
referral_code.invalid_code Invalid referral code
reset_password.invalid_card Could not load card
reset_password.invalid_account Could not load account
reset_password.invalid_user Could not load user
reset_password.invalid_argument Must supply only one of: printedCardNumber, username or email
reset_password.invalid_argument Must supply printedCardNumber, username or email
reset_password.invalid_email_address Invalid email address format
reset_password.email_not_unique More than one user matches the specified email address; cannot uniquely identify whose password to reset
reset_password.non_matching_email No user found with the specified email address
reset_password.not_registered Cardholder is not registered
reset_password.no_email No email address defined for cardholder
reset_password.email_excluded Email address is undeliverable for cardholder
reset_password.is_juvenile Cardholder is a juvenile
reset_password.invalid_answer Invalid answer
reset_password.server_error Internal server error
reset_password.email_not_sent  
transaction_history.error Failed to perform operation
transaction_history.card_not_found could not load given card
transaction_history.card_exchanged card exchanged
transaction_history.card_inactive card inactive
transaction_annotation.error Failed to perform operation
card_status.invalid_merchant Invalid merchant ID
card_status.account_not_active Account not active
card_status.card_exchanged Card has been exchanged
card_status.card_inactive Card is not active
card_status.invalid_status Cards cannot be set to the requested status
card_status.invalid_card Failed to find the card
card_status.internal_error An internal error occurred