.. _one_to_one_service:

One To One Service
==================

The One To One service provides endpoints which allows a user to retrieve
information related to their One To One Cadence.

.. contents:: Topics

Endpoints
---------

Get One To One User Progress
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: onetoone/userProgress.json

   Returns information about the given user's progress towards their next reward.

   The following authentication methods are allowed for this endpoint:

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

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String printedCardNumber: *(required)*  The printed card number associated with the user. If a user has multiple cards, all of them will work, but the primary card is preferable.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam BigDecimal visitsToNextReward: *(required)*  The number of visits remaining until a user receives their next reward.
   :jsonparam BigDecimal threshold: *(required)*  The number of visits between receiving the last reward and the next reward. Useful for tracking progress. This value will only change when a user receives their next reward.

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

Get One To One User Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: onetoone/oneToOneUserInformation.json

   Obtains cadence information for a given account. Cadence information includes all of the rungs of a cadence and the number of visits that the cadence resets at.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String printedCardNumber: *(required)*  The printed card number associated with the user. If a user has multiple cards, all of them will work, but the primary card is preferable.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam Object oneToOneCadence: *(required)*  See :http:jsonentity:`OneToOneCadence` for format of the objects.

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

Reply Objects
-------------

.. http:jsonentity:: OneToOneCadence

   :jsonparam BigDecimal resetThreshold: *(required)*  The threshold that the cadence resets back to zero at.
   :jsonparam List[Object] rungs: *(required)*  The rungs of this user's cadence. See :http:jsonentity:`OneToOneRungInfo` for format of the rung objects.

.. http:jsonentity:: OneToOneRungInfo

   :jsonparam BigDecimal visitThreshold: *(required)*  The number of visits required to earn this rungs reward.
   :jsonparam Integer rewardWalletCode: *(required)*  The wallet code of this rungs reward. Used to access more information about the reward wallet.
   :jsonparam String rewardWalletLabel: *(required)*  The wallet label of this rungs reward. Can be used label the reward without accessing more information about the wallet.
   :jsonparam BigDecimal rewardAmount: *(required)*  The amount of the reward given for this rung.


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

The following are the possible codes and messages that can be returned
by the One To One 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                                                                       |
+===========================================+===============================================================================+
| ``one_to_one_info.server_error``          | Internal Server error                                                         |
+-------------------------------------------+-------------------------------------------------------------------------------+
| ``one_to_one_info.card_not_found``        | Could not find the specified card                                             |
+-------------------------------------------+-------------------------------------------------------------------------------+
| ``one_to_one_info.account_not_found``     | Could not find one to one account information for this user                   |
+-------------------------------------------+-------------------------------------------------------------------------------+
| ``one_to_one_info.no_rungs``              | There are no rungs listed for this account                                    |
+-------------------------------------------+-------------------------------------------------------------------------------+
| ``one_to_one_info.wallet_not_found``      | A wallet for a given rung could not be found, so the given cadence is invalid |
+-------------------------------------------+-------------------------------------------------------------------------------+