Checkin Service
===============

The checkin service provides endpoints to check in guests at locations,
as part of a social media or mobile phone integration.

.. contents:: Topics

Endpoints
---------

Check in to a Store
~~~~~~~~~~~~~~~~~~~

.. http:post:: checkin/checkinAccount.json

   Checks in a guest account at a particular location.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam String storeCode: *(Optional)*  Paytronix store code to check the account into. (If not provided, user will be checked in to the corporate store.)
   :jsonparam String checkinTime: *(required)*  Date and time formatted as ``yyyy-mm-dd hh:mm:ss Z`` to record the checkin at.  Note that the timezone ``Z`` should be a UTC offset (like ``-0400``)
   :jsonparam Object account: *(required)*  Identifying information for the account. Valid formats are ``{ "mobilePhone": "..." }`` for checkin by mobile phone number, ``{ "printedCardNumber": "..." }`` for checkin by card information and ``{ "externalAccountCode": "..." }`` for checkin using external account information.
   :jsonparam String externalStoreCode: *(Optional)*  An optional value identifying the store being checked in to within an external system, such as the store or venue ID as conceived by the software sending the checkinAccount request


.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam String shortCardNumber: *(required)*  If enabled, a short unique card number valid for the visit to the location that is easier to communicate to a cashier or server and can be used in place of the printed card number. Typically only a few digits long.
   :jsonparam String printedCardNumber: *(required)*  The primary printed card number of the account checked in.
   :jsonparam Datetime expirationTime: *(required)*  The time at which the short card number expires

.. 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.
   :jsonparam String shortCardNumber: *(required)*  If enabled and the errorCode is ``checkin.already_checked_in`` and not expired, then this will contain the short code number of the most recent checkin

Error Codes
-----------

The following are the possible codes and messages that can be returned
by the Checkin 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                         | Notes                                                              |
+=================================+=================================+====================================================================+
| ``checkin.system_error``        | System error                    |                                                                    |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+
| ``checkin.invalid_store_code``  | Invalid store code              |                                                                    |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+
| ``checkin.not_enabled``         | Checkin Service is not active   |                                                                    |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+
| ``checkin.account_not_found``   | Account not found               |                                                                    |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+
| ``checkin.future_checkin_time`` | Cannot checkin in the future    |                                                                    |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+
| ``checkin.already_checked_in``  | Already checked in              | Will provide the existing short card number in the failure reply   |
+---------------------------------+---------------------------------+--------------------------------------------------------------------+