Guest Authentication Service

The guest authentication service allows privileged B2B integrations to authenticate guests based on username and password as well as alternative identification methods such as printed card number or, depending on the merchant’s configuration, email address, phone number, or any number of other fields.

This service is intended for use by merchants’ websites and similar systems which use Paytronix as the database of record for guest login information. For mobile apps or any software running on untrusted and/or uncontrolled systems, OAuth Service must be used instead.

Endpoints

authenticateGuestPassword

POST guestauthentication/authenticateGuestPassword.json

The most common form of guest authentication, this resource is used to verify that a guest’s username and password are correct.

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 of the guest to be authenticated.
  • password (String) – (required) Password of the guest to be authenticated.
"result": "authenticatedSuccess"
JSON Parameters:
 
  • result (String) – (required) authenticatedSuccess
  • username (String) – (required) The username of the guest which was authenticated.
  • primaryPrintedCardNumber (String) – (optional) The primary printed card number of the guest which was authenticated, if such a one exists.

For example:

{
    "result": "authenticatedSuccess",
    "username": "matt.explosion",
    "primaryPrintedCardNumber": 60001234567890999
}
"result": "noMatchingGuests"
JSON Parameters:
 
  • result (String) – (required) noMatchingGuests
"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.

authenticateGuest

POST guestauthentication/authenticateGuest.json

This resource allows more flexibility in identifying guests than simple username/password authentication, with many different combinations of authentication fields being possible, though without explicit configuration only username + password or printed card number + registration code are allowed.

The functionality of this resource is similar to what’s provided by the OAuth Service’s Grant by User Fields functionality, however it does not generate an OAuth token and can only be used by trusted B2B integrations.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • cardTemplateCode (Integer) – (required) Paytronix-assigned card template code representing what program (e.g. gift card, loyalty card, etc.) to search for the guest in
  • fields (String) – (required) See OAuthUserFields
"result": "authenticatedSuccess"
JSON Parameters:
 
  • result (String) – (required) authenticatedSuccess
  • username (String) – (optional) The username of the guest which was authenticated, if they have one.
  • primaryPrintedCardNumber (String) – (optional) The primary printed card number of the guest which was authenticated, if such a one exists.

For example:

{
    "result": "authenticatedSuccess",
    "username": "matt.explosion",
    "primaryPrintedCardNumber": 60001234567890999
}
"result": "noMatchingGuests"

This result is returned when no guests match the provided information.

JSON Parameters:
 
  • result (String) – (required) noMatchingGuests
"result": "insufficientInformation"

This result is returned when the provided authentication information is not sufficient to identify guests. See Insufficient information to authenticate for more information.

JSON Parameters:
 
"result": "tooManyMatchingGuests"

This result is returned when more than one guest matches the provided authentication information.

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