Challenge Service ================= The challenge service provides endpoints which allows a user or a group to take challenges and earn rewards and badges. .. contents:: Topics Endpoints --------- Get Active Challenges for Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/activeChallenges.json Obtains a list of challenges which are currently active (i.e., in progress) or opted-in (i.e., challenge joined in advance of start date) for the user. 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 card of the user. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Get Active Challenges for Group ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/activeChallengesForGroup.json Obtains a list of challenges which are currently active (i.e., in progress) or opted-in (i.e., challenge joined in advance of start date) for the group. 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 username: *(required)* The username (login) of the user. :query Long groupCode: *(required)* The unique code of the group. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Get Eligible Challenges for Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/eligibleChallenges.json Obtains a list of challenges which the user can take (i.e., opt-in). 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 card of the user. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Get Eligible Challenges for Group ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/eligibleChallengesForGroup.json Obtains a list of challenges which the group can take (i.e., opt-in) 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 username: *(required)* The username (login) of the user. :query Long groupCode: *(required)* The unique code of the group. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Get Historical Challenges for Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/historicalChallenges.json Obtains a list of challenges which the user attempted in the past. 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 card of the user. :query String sinceDate: *(optional)* Date and time in UTC by default unless timezone offset specified. The format is ``yyyy-MM-dd HH:mm:ss [+-ZZZZ]``. Results will be limited to challenges that ended after this date. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Get Historical Challenges for Group ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/history/historicalChallengesForGroup.json Obtains a list of challenges which the group attempted in the past 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 username: *(required)* The username (login) of the user. :query Long groupCode: *(required)* The unique code of the group. :query String sinceDate: *(optional)* Date and time in UTC by default unless timezone offset specified. The format is ``yyyy-MM-dd HH:mm:ss [+-ZZZZ]``. Results will be limited to challenges that ended after this date. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] challenges: *(required)* See :http:jsonentity:`Challenge` for format of the objects. Opt-in to a Challenge for a Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: challenge/optInToChallenge.json User wants to take (opt-in) to a challenge (which will become active for them) 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 printedCardNumber: *(required)* The card of the user. :jsonparam String challengeCode: *(required)* The unique code of the challenge. :jsonparam String charitableOrganizationCode: *(optional)* The unique code of the charitable organization. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object challenge: *(required)* See :http:jsonentity:`Challenge` for format of the object. Opt-out of a Challenge for a Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: challenge/optOutOfChallenge.json User wants to terminate (opt-out of) an active challenge 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 printedCardNumber: *(required)* The card of the user. :jsonparam Long challengeCode: *(required)* The unique code of the challenge. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object challenge: *(required)* See :http:jsonentity:`Challenge` for format of the object. Get Detail of a Challenge Occurrence ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/challengeOccurrence.json Get the details of a challenge by the challenge occurrence 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 username: *(required)* The username (login) of the user. :query Long challengeOccurrenceCode: *(required)* The unique code of the challenge. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object challenge: *(required)* See :http:jsonentity:`Challenge` for format of the object. Get Charitable Organizations For Challenge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: challenge/charitableOrganizationsForChallenge.json Get the charitable organizations for a challenge The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String challengeCode: *(required)* The unique code of the challenge. .. http:response:: success :jsonparam List[Object] organizations: *{required)* List of charitable organizations. See :http:jsonentity:`CharitableOrganizationSummary` for format of the object. Reply Objects ------------- .. http:jsonentity:: Challenge :jsonparam Long code: *(required)* The unique code of this challenge. :jsonparam String name: *(required)* The name of this challenge. :jsonparam String description: *(required)* The description of this challenge. :jsonparam Date startDate: *(required)* The date that this challenge started (or will start). :jsonparam Date endDate: *(required)* The date that this challenge will end. :jsonparam String status: *(required)* The status of the challenge. On one ACTIVE, COMPLETED, EXPIRED, ELIGIBLE, OPTED_OUT, OPTED_IN. :jsonparam List[Object] counters: *(required)* Only present is status is '''ACTIVE'''. A list of the counters associated to the challenge. See :http:jsonentity:`Counter` for format of the objects. .. http:jsonentity:: CharitableOrganizationSummary :jsonparam String code: *(required)* The unique code for this charitable organization. :jsonparam String displayName: *(required)* The name of this charitable organization. :jsonparam String iconCode: *(optional)* The code which denotes the icon image to display for this charitable organization. .. http:jsonentity:: Counter :jsonparam Long code: *(required)* The unique code of this counter. :jsonparam String name: *(required)* The name of this counter. :jsonparam Decimal value: *(required)* The current value of this counter that the user/group has achieved. :jsonparam Decimal threshold: *(required)* The threshold of this counter. If the value meets or exceeds this threshold, then this counter is considered satisfied as part of the challenge. :jsonparam List[Object] details: *(required)* A list of the details used in the calculation of the counter's value. See :http:jsonentity:`CounterDetail` for format of the objects. .. http:jsonentity:: CounterDetail :jsonparam String memberCode: *(required)* If the challenge is for a group, then this code references the particular member whose contribution to the calculation this detail describes. If this is not present, then the (individual) user who is taking the challenge is the contributor of this calculation detail. :jsonparam Decimal numericValue: *(required)* If the calculation computes numeric values, then this field will be present. :jsonparam String stringValue: *(required)* If the calculation simply counts instances of "items", then this value would be present with the name of the item. The Counter's value could be the count of all of the Counter Detail records which contained unique items.