Guest Service ¶

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

Topics

Guest Service

Endpoints ¶

Get Printed Card Number For External Account ¶

GET guest/printedCardNumberForExternalAccount.json¶

Obtains information about a primary card for an account associated with an external account code.

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountCode (String) – (required) The external account code associated with the account to get primary card information about.

"result": "success"

JSON Parameters:

result (String) – (required) success
primaryCard (Object) – (required) The information about the primary card associated with the external account. See CardInformation for the format of this object.
additionalCards (List[Object]) – (required) The information about any additional cards associated with the external account. See CardInformation for the format of this object.

For example:

{
    "result": "success",
    "primaryCard": {
        "maskedCardNumber": "200841",
        "printedCardNumber": "6000201000200841",
        "status": "ACTIVE"
    },
    "additionalCards": [
        {
            "maskedCardNumber": "399785",
            "printedCardNumber": "6000201000200841",
            "status": "DISABLED"
        },
        {
            "maskedCardNumber": "374565",
            "printedCardNumber": "64556365000200841",
            "status": "ACTIVE"
        }
    ]
}

"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 Account Information (Balance Inquiry) By Printed Card Number ¶

GET guest/accountInformation.json¶

Obtains information about an account (specified by a printed card number) 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:

Query 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 accessFilterStoreGroupCode (Integer) – (optional) Paytronix-assigned store group code that the account is associated with.

"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
registrationStatus (String) – (required) Possible values in a success reply: UNREGISTERED, VERIFICATION_PENDING, REGISTERED.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program in which the account is enrolled.
cardTemplateLabel (String) – (required) The name of the program (i.e., card template)
tierCode (Integer) – (required) Paytronix-assigned tier code identifying the 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.
pendingEventRewards ([Object]) – (required) List of pending rewards in an account. See PendingEventReward.

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,
            "hideExpirationDates": false
        }
    ],
    "primaryCard": {
        "maskedCardNumber": "200841",
        "printedCardNumber": "6000201000200841",
        "status": "ACTIVE"
    },
    "queryCardStatus": "ACTIVE",
    "rewardBalances": [
        {
            "balance": "0.0000",
            "name": "Birthday Free Drink",
            "walletCode": 3,
           " hideExpirationDates": false
        },
        {
            "balance": "1.0000",
            "name": "Free Drink",
            "walletCode": 6,
            "expirations": [
                {
                    "amount": 1,
                    "expirationDate": "2011-05-01"
                }
            ],
            "hideExpirationDates": false
        }
    ],
    "storedValueBalance": {
        "balance": "0.0000",
        "name": "Stored Value",
        "walletCode": 0,
        "hideExpirationDates": true
    },
    "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 (Balance Inquiry) By Account Id ¶

GET guest/accountInformationById.json¶

Obtains information about an account (specified by an accountId) 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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountId (Integer) – (required) Account ID of the account accessFilterStoreGroupCode (Integer) – (optional) Paytronix-assigned store group code that the account is associated with.

"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
registrationStatus (String) – (required) Possible values in a success reply: UNREGISTERED, VERIFICATION_PENDING, REGISTERED.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program in which the account is enrolled.
cardTemplateLabel (String) – (required) The name of the program (i.e., card template)
tierCode (Integer) – (required) Paytronix-assigned tier code identifying the 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.
pendingEventRewards ([Object]) – (required) List of pending rewards in an account. 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.

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

Use Your Email As A Username ¶

GET guest/migrateEmailAsUsername.json¶

Allows a user to use their email address as a username.

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username of the account email (String) – (required) The email address of the account

"result": "success"

JSON Parameters:
	result (String) – (required) `success` newUsername (String) – (required) The new username (which is now the user’s email) of the account.

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

Guest email authentication

Query 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 template.

"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
registrationStatus (String) – (required) Possible values in a success reply: UNREGISTERED, VERIFICATION_PENDING, REGISTERED.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program in which the account is enrolled.
cardTemplateLabel (String) – (required) The name of the program (i.e., card template)
tierCode (Integer) – (required) Paytronix-assigned tier code identifying the 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.
pendingEventRewards ([Object]) – (required) List of pending rewards in an account. See PendingEventReward.

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": [

        ]
  },
  "registrationStatus": "REGISTERED",
  "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:

Query 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` userInformation (Object) – (required) See `UserInformation` for format of this object.

For example:

{
    "result": "success",
    "userInformation": {
      "fields":
      {
          "addressLabel":"Primary Address",
          "address1":"307 Waverly Oaks Road",
          "address2":"A Building",
          "city":"Waltham",
          "country":"US",
          "dateOfBirth":"1990-07-18",
          "email":"[email protected]",
          "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"],
      "relatedGuests":
      {
          "relatedGuestCode": 5,
          "firstName": "Jumbo",
          "lastName": "Williams",
          "email": "[email protected]",
          "dateOfBirth": "1990-11-26",
          "salutation": "Mr."
      },
      "addresses": [
        {
          "addressId":99999,
          "addressLabel":"Primary Address",
          "address1":"307 Waverly Oaks Road",
          "address2":"A Building",
          "city":"Waltham",
          "country":"US",
          "postalCode":"02452",
          "stateProvince":"MA"
        },
        {
          "addressId":99998,
          "addressLabel":"Secondary Address",
          "address1":"45 Bagel Bite Street",
          "address2":"Suite 9",
          "city":"Waltham",
          "country":"US",
          "postalCode":"02452",
          "stateProvince":"MA"
        }
      ]
      "accountIds": ["198412384789234",
                     "594834571395877"]
    }
}

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

Query 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` userInformation (Object) – (required) See `UserInformation` 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.

Get User Information by AccountId ¶

GET guest/userInformationByAccountId.json¶

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

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountId (Integer) – (required) Account ID of the account

"result": "success"

JSON Parameters:
	result (String) – (required) `success` userInformation (Object) – (required) See `UserInformation` 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.

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:

Guest email authentication

Query 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 template.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` userInformation (Object) – (required) See `UserInformation` for format of this object.

For example:

{
  "result": "success",
  "fields": {
    "dateOfBirth": "1990-01-01",
    "email": "[email protected]",
    "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 User And Account Information for By Printed Card Number ¶

GET guest/userAndAccountInformationByPrintedCardNumber.json¶

Obtains both User Information and Account Information for a given printed card number

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) Card Number of the account

"result": "success"

JSON Parameters:
	result (String) – (required) `success` userInformation (Object) – (required) See `UserInformation` for format of this object. accountInformation (Object) – (required) See `AccountInformation` for format of this object.

For example:

          {
            "result": "success",
"userInformation": {...},
            "accountInformation": {...}
          }

"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 By Printed Card Number ¶

GET guest/transactionHistory.json¶

Obtains transaction history for an account by the printed card number.

The following authentication methods are allowed for this endpoint:

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) Card Number of the account
dateStart (LocalDate) – (optional) Limits the result to transactions that have happened since the date specified, in the format: yyyy-MM-dd (e.g. 2012-03-23)
dateEnd (LocalDate) – (optional) Limits the result to transactions that have happened before the date specified, in the format: yyyy-MM-dd (e.g. 2012-03-23)
maxNumberOfResults (Int) – (optional) The maximum number of results returned by the transaction history.
limitToBalanceAffectingTransactions (Boolean) – (optional) Only include the balance affecting transactions.
excludeNonBalanceAffectingIdentifyCustomerTransactions (Boolean) – (optional) Filter out the non balance affecting identity customer transactions.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` walletInfo (List[Object]) – (required) See `TransactionHistoryWalletInfo` for format of these objects. transactions (List[Object]) – (required) See `TransactionHistoryTransaction` for format of these objects.

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,
            "requestEvent" : "LP207"
        },
        {
            "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,
            "requestEvent" : "LP211"
        }
    ]
}

"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 by Account ID ¶

GET guest/transactionHistoryByAccount.json¶

Obtains transaction history for an account by the account ID.

The following authentication methods are allowed for this endpoint:

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
accountId (Integer) – (required) The account ID of the account.
dateStart (LocalDate) – (optional) Limits the result to transactions that have happened since the date specified, in the format: yyyy-MM-dd (e.g. 2012-03-23)
dateEnd (LocalDate) – (optional) Limits the result to transactions that have happened before the date specified, in the format: yyyy-MM-dd (e.g. 2012-03-23)
maxNumberOfResults (Int) – (optional) The maximum number of results returned by the transaction history.
limitToBalanceAffectingTransactions (Boolean) – (optional) Only include the balance affecting transactions.
excludeNonBalanceAffectingIdentifyCustomerTransactions (Boolean) – (optional) Filter out the non balance affecting identity customer transactions.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` walletInfo (List[Object]) – (required) See `TransactionHistoryWalletInfo` for format of these objects. transactions (List[Object]) – (required) See `TransactionHistoryTransaction` for format of these objects.

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

GET guest/transactionAnnotation.json¶

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

The following authentication methods are allowed for this endpoint:

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

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` username (String) – (required) The username associated with the card that was combined. survivingAccountId (Int) – (required) The accountId associated with the current user.

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

Attach and Combine Cards ¶

POST guest/attachAndCombine.json¶

Attaches a card to the user’s account and combines it to the main account of the same template linked to the current 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.
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": "attach_failure"

This failure occurs if attach and combine fails at the ‘attach’ step.

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

"result": "combine_failure"

This failure occurs if attach and combine fails at the ‘combine’ step.

JSON Parameters:
	result (String) – (required) `combine_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.

"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

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:

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

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

Get List of Referrals For User By Username ¶

GET guest/referralsByUsername.json¶

Return the list of referrals for the user/account specified by the username.

The following authentication methods are allowed for this endpoint:

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

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

Get List of Referrals For User By Printed Card Number ¶

GET guest/referralsByPrintedCardNumber.json¶

Return the list of referrals for the user/account specified by the printed card number.

The following authentication methods are allowed for this endpoint:

Query 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` numberOfAvailableUserReferrals (Integer) – (required) The number of referrals available for the user/account userReferrals (List[Object]) – (required) See `UserReferralFields` for format of this object. 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.

Get List of Referrals For User By Account ID ¶

GET guest/referralsByAccountId.json¶

Return the list of referrals for the user/account specified by the accountId.

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountId (Integer) – (required) Account ID associated with the account 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. 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.

Add Referrals By Username ¶

POST guest/addReferralsByUsername.json¶

Add new referrals to this account/user (specified by username). 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
emails (List[String]) – (required) A list of email addresses of the referents
message (String) – (optional) A message included in each email sent
cardTemplateCode (Integer) – (optional) 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. 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.

Add Referrals By Printed Card Number ¶

POST guest/addReferralsByPrintedCardNumber.json¶

Add new referrals to this account/user (specified by printed card number). 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.
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) – (optional) A message included in each email sent

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

Add Referrals By Account ID ¶

POST guest/addReferralsByAccountId.json¶

Add new referrals to this account/user (specified by accountId). 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. accountId (Int) – (required) Account ID associated with the account to get information about emails (List[String]) – (required) A list of email addresses of the referents message (String) – (optional) A message included in each email sent

"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. 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 By Username ¶

POST guest/createReferralCodeByUsername.json¶

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

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation. 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.

Create Referral Code By Printed Card Number ¶

POST guest/createReferralCodeByPrintedCardNumber.json¶

Create a code that can be used by others during enrollment, which maps back to a single referrer (specified by printed card number).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation. printedCardNumber (String) – (required) Printed card number associated with the account/user

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

Create Referral Code By Account ID ¶

POST guest/createReferralCodeByAccountId.json¶

Create a code that can be used by others during enrollment, which maps back to a single referrer (specified by account Id).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation. accountId (Integer) – (required) Account ID 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:

Anonymous authentication

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 By Printed Card Number ¶

GET guest/pendingEventRewards.json¶

Get pending event rewards by printed card number.

The following authentication methods are allowed for this endpoint:

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

Get Pending Event Rewards By Account ID ¶

GET guest/pendingEventRewardsByAccountId.json¶

Get pending event rewards by account id.

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountId (Integer) – (required) Account ID 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.

Apply Visit Code ¶

POST guest/applyVisitCode.json¶

Apply a visit code to an account (this account can either be specified by an accountId or a printedCardNumber). Only one of these two should be provided, and it is considered an error if more than one is sent.

Depending on the generating system, this code may be given to the guest in plaintext, or encoded in a barcode or QR code.

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 to apply the visit code to.
accountId (Integer) – (See description) Account ID associated with the account to apply the visit code to.
code (String) – (required) The visit code to apply to an account.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` reply (Object) – (required) See `AddRedeemReply`

"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 Visit Code ¶

POST guest/validateVisitCode.json¶

Validate that a visit code can be applied to an account (this account can either be specified by an accountId or a printedCardNumber). Only one of these two 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 to apply the visit code to.
accountId (Integer) – (See description) Account ID associated with the account to apply the visit code to.
code (String) – (required) The visit code to apply to an account.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` codeInfo (String) – (required) The information of the code that was entered. See `VisitCode`

"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": "invalidVisitCode"

JSON Parameters:
	result (String) – (required) `invalidVisitCode` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure. codeInfo (String) – (required) The information of the code that was entered. See `VisitCode`

Update Message Frequency ¶

POST guest/updateMessageFrequency.json¶

Update a user’s message frequency preference, including opting in or out of messaging. Account is specified by username.

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 apply the message frequency to. preference (String) – (required) The messaging frequency the guest would like. See Message Frequency Values.

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

Update User Language Preference ¶

POST guest/updateUserLanguagePrefByUsername.json¶

Update a user’s language preference. Account is specified by username.

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 apply the language preference to. languageCode (String) – (required) The language code associated with the language to set the preference to. See Language Preference Values.

POST guest/updateUserLanguagePrefByPrintedCardNumber.json¶

Update a user’s language preference. Account is specified by printedCardNumber.

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 to apply the visit code to. languageCode (String) – (required) The language code associated with the language to set the preference to. See Language Preference Values.

POST guest/updateUserLanguagePrefByAccountId.json¶

Update a user’s language preference. Account is specified by accountId.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. accountId (Integer) – (See description) Account ID associated with the account to apply the visit code to. languageCode (String) – (required) The language code associated with the language to set the preference to. See Language Preference Values.

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

Message Frequency Values ¶

ALL: Receive all marketing messages.
ONCE_PER_WEEK: Receive a message no more than once a week.
ONCE_PER_FORTNIGHT: Receive a message no more than once every other week.
ONCE_PER_MONTH: Receive a message no more than once a month.
SNOOZE: Temporarily snooze marketing communications. Guest will not receive a marketing message for 14 days.
UNSUBSCRIBE: Unsubscribe from all marketing messages.

Language Preference Values ¶

en-US: English used in the US.
en-GB: English used in the UK.
es-ES: Spanish language.
fr-FR: French language used in France.
fr-CA: French language used in Canada.
da-DK: Danish language.
nl-NL: Dutch language.
fi-FI: Finnish language.
de-DE: German language.
it-IT: Italian language.
nb-NO: Norwegian language.
pt-BR: Portuguese language.
sv-SE: Swedish language.

Reply Objects ¶

UserInformation¶

User information can be supplied in the "userInformation" member of the reply:

JSON Parameters:

fields (Object) – (required) See UserFields for format of this object.
primaryCardNumbers (List[String]) – (required) List of primary card numbers associated with a user.
relatedGuests (List[Object]) – (optional) List of RelatedGuest objects. See RelatedGuest for format of those objects.
addresses (List[Object]) – (required) List of AddressInformation objects. See AddressInformation for format of those objects.
accountIds (List[Int]) – (required) List of Account ID’s associated with a user.

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
hideExpirationDates (Boolean) – (required) True if the wallet associated with this balance has the option to hide expiration dates from the guest selected
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.
rewardType (String) – (optional) One of “FIXED_AMOUNT”, “OPEN_AMOUNT”.
rewardValueType (String) – (optional) One of “PERCENT_DISCOUNT”, “DOLLAR_DISCOUNT”, “POS_DISCOUNT”, “REDUCE_PRICE_TO”, “PRECENT_OFF_CATEGORY”, “PER_UNIT_DISCOUNT”.

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 {"label": "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": "externalIdentifier", "accountCode": "..." }
favoriteStores (Object) – (required) List of user’s Favorite Stores, excluding the primary favorite store. Each object has the format: {"label": "Store 1", "code": "001"}

Please reach out to Paytronix for possible external account identifier values.

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 emails about special offers etc.
textCampaignOptIn (bool) – (required) Whether or not the user has opted into SMS marketing messages.
smsOptInVerified (bool) – (required) Whether or not the user has verified their SMS optIn; ie. “Double opt-in verified”
salutation (string) – (optional) “Mr.”, “Ms.”, “Mrs.”, “Dr.” or “Rev.”
firstName (string) – (optional)
lastName (string) – (optional)
email (string) – (optional)
addressLabel (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)
username (string) – (optional)
emailVerified (bool) – (optional) Whether or not the user’s email address has been verified.
userLanguagePref (string) – (optional) The user’s language preference.
relatedGuests (List[Object]) – (optional) See RelatedGuest for format of these objects.

RelatedGuest¶

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) first name of the related guest.
lastName (string) – (required) last name of the related guest.
email (string) – (optional) email of the related guest.
dateOfBirth (string) – (optional) date of birth of the related guest.
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) Usually the ID of the POS terminal sent from the POS
operatorId (Integer) – (required) Usually the Cashier ID sent from the POS
sender (String) – (required) Internal to Paytronix
pxAuthCode (String) – (required) Internal to Paytronix
details (List[Object]) – (required) See TransactionHistoryDetail for format of these objects.
requestEvent (String) – (required) Code that corresponds to transaction type internal to Paytronix.

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 from this wallet during the transaction
balance (Decimal) – (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 the 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:

A CSR associates a group of anonymous cards to an account.
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 or ClickToLoad event but the reward has not yet converted to a redeemable reward in the account:

JSON Parameters:

name (String) – (required)
tinyName (String) – (optional)
shortName (String) – (optional)
longName (String) – (optional)
amount (Decimal) – (required)
expirationDate (Date) – (optional)
eventName (String) – (required)
eventCode (String) – (required) (in some endpoints may be called clickToLoadCode).
alternateImageUrl (String) – (optional)

AddRedeemReply¶: Information about what was changed about the Wallet when the visit code was applied.

VisitCode¶

The information of a Visit Code

JSON Parameters:

storeCode (String) – (required) The code of the store associated with the Visit Code.
checkNumber (String) – (required) The number of the check associated with the Visit Code.
dollarSpent (Decimal) – (required) The dollars spend on the check associated with the Visit Code.
checkDate (Date) – (required) The date of which the Visit Code was issued.
normalizedCode (String) – (required) The normalized Visit Code.

CardInformation¶

The information of associated with a card.

JSON Parameters:
	printedCardNumber (String) – (required) The string representation of the card number. maskedCardNumber (String) – (required) The masked string representation of the card number. status (String) – (required) The status of the card. Valid values are ACTIVE or DISABLED.

AddressInformation¶

JSON Parameters:

addressId (String) – (optional) Unique id referring to existing address record. Needed for calls to edit or delete address
label (String) – (required)
address1 (String) – (optional)
address2 (String) – (optional)
city (String) – (optional)
stateProvince (String) – (optional)
postalCode (String) – (optional)
country (String) – (optional)

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