.. _guest_auth_service: 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, :ref:`oauth_service` must be used instead. .. contents:: Topics Endpoints --------- authenticateGuestPassword ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String username: *(required)* Username of the guest to be authenticated. :jsonparam String password: *(required)* Password of the guest to be authenticated. .. http:response:: authenticatedSuccess :jsonparam String result: *(required)* ``authenticatedSuccess`` :jsonparam String username: *(required)* The username of the guest which was authenticated. :jsonparam String primaryPrintedCardNumber: *(optional)* The primary printed card number of the guest which was authenticated, if such a one exists. For example: .. code:: javascript { "result": "authenticatedSuccess", "username": "matt.explosion", "primaryPrintedCardNumber": 60001234567890999 } .. http:response:: noMatchingGuests :jsonparam String result: *(required)* ``noMatchingGuests`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. authenticateGuest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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 :ref:`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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code representing what program (e.g. gift card, loyalty card, etc.) to search for the guest in :jsonparam String fields: *(required)* See :http:jsonentity:`OAuthUserFields` .. http:response:: authenticatedSuccess :jsonparam String result: *(required)* ``authenticatedSuccess`` :jsonparam String username: *(optional)* The username of the guest which was authenticated, if they have one. :jsonparam String primaryPrintedCardNumber: *(optional)* The primary printed card number of the guest which was authenticated, if such a one exists. For example: .. code:: javascript { "result": "authenticatedSuccess", "username": "matt.explosion", "primaryPrintedCardNumber": 60001234567890999 } .. http:response:: noMatchingGuests This result is returned when no guests match the provided information. :jsonparam String result: *(required)* ``noMatchingGuests`` .. http:response:: insufficientInformation This result is returned when the provided authentication information is not sufficient to identify guests. See :ref:`insufficient_information_to_authenticate` for more information. :jsonparam String result: *(required)* ``insufficientInformation`` :jsonparam Object result: *(required)* ``tryMethods`` See :ref:`insufficient_information_to_authenticate` for more information. .. http:response:: tooManyMatchingGuests This result is returned when more than one guest matches the provided authentication information. :jsonparam String result: *(required)* ``tooManyMatchingGuests`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure.