===================
Guest Website Login
===================



Overview
--------
Guest websites typically require the guest to give several pieces of information in order to log in. To accomplish this function in the Paytronix system we use the OAuth standard. We offer a method to obtain an access token given a guests username and password, and a method to obtain an access token given a refresh token. Access tokens are valid for 30 minutes, so to support guests who are using your integration for an extended period of time, you must obtain new access tokens. 


Authentication
--------------

This particular flow only supports an authentication type of OAuth.


Flow
----

To obtain an access token (log a user in): 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

.. image:: login.png

1. Prompt the guest for log on credentials. Unless you have received prior approval from Paytronix, the credentials will consist of the username and password fields
2. Send a requestGuestToken call using the information gathered in the first step. Make sure to grant by username and password. 
3. The Paytronix system will return a result of success or failure

	a. If the result is success then the integration should inform the guest that the login attempt was successful. The integration should also save the access and refresh tokens for use in future REST calls. 
	b. If the result is failure then the integration should inform the guest that the login attempt was unsuccessful. We suggest that integrators use the error code and error message returned by the system to inform the guest of the problem, though the merchant should decide on the exact messages.


To obtain a new access token for a logged in user: 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. image:: refresh_token.png

1. The Integration has received a server response of invalid token. This indicates that the guest has been using the same access token for 30 minutes or more.  
2. Send a requestGuestToken call using the refresh token obtained when first logging the guest in. Make sure to grant by refresh token. 
3. The Paytronix system will return a result of success or failure

	a. If the result is success then the integration should resend the call that generated the failure in step 1. The integration should also save the new access token for use in future REST calls. 
	b. If the result is failure then the integration should present an error to the guest. We suggest that integrators use the error code and error message returned by the system to inform the guest of the problem, though the merchant should decide on the exact messages. Many integrations will return the guest to the login page.


Examples
--------

To obtain an access token (log a user in): 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

Request Body

.. code:: javascript

	{
	  "authentication": "anonymous",
	  "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK",
	  "client_secret": "654secretnx4",
	  "merchantId": 777777,
	  "grant_type": "password",
	  "scope": "user_read user_write account_read account_write",
	  "username": "johndoe",
	  "password": "open456"
	}

Response 

.. code:: javascript

	{
	  "result": "success",
	  "access_token": "rIe7dgLnotarealaccesstokenbA268pw5GP",
	  "expires_in": 1800,
	  "refresh_token": "r9vsdS4LUlnotarealrefreshtokenp9JrsJ8cb",
	  "scope": "user_read user_write account_read account_write",
	  "token_type": "bearer",
	  "username": "johndoe"
	}

To obtain a new access token for a logged in user:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

Request Body

.. code:: javascript

	{
	  "authentication": "anonymous",
	  "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK",
	  "client_secret": "654secretnx4",
	  "merchantId": 777777,
	  "grant_type": "refresh_token",
	  "scope": "user_read user_write account_read account_write",
	  "refresh_token": "r9vsdS4LUlnotarealrefreshtokenp9JrsJ8cb"
	}


Response 

.. code:: javascript

	{
	  "result": "success",
	  "access_token": "rIe7dgLnotarealaccesstokenbA268pw5GP",
	  "expires_in": 1800,
	  "printedCardNumber": "6000986775",
	  "refresh_token": "r9vsdS4LUlnotarealrefreshtokenp9JrsJ8cb",
	  "scope": "user_read user_write account_read account_write",
	  "token_type": "bearer",
	  "username": "johndoe"
	}
	
	
API Reference
-------------

Please see the following API reference page for more technical details: `OAuth Service <.././pxs_api_reference/oauth.html>`_