Challenge Service ¶

The challenge service provides endpoints which allows a user or a group to take challenges and earn rewards and badges.

Topics

Challenge Service
- Endpoints
- Reply Objects

Endpoints ¶

Get Active Challenges for Guest ¶

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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Get Active Challenges for Group ¶

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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. groupCode (Long) – (required) The unique code of the group.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Get Eligible Challenges for Guest ¶

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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Get Eligible Challenges for Group ¶

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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. groupCode (Long) – (required) The unique code of the group.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Get Historical Challenges for Guest ¶

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:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. sinceDate (String) – (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.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Get Historical Challenges for Group ¶

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:

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
username (String) – (required) The username (login) of the user.
groupCode (Long) – (required) The unique code of the group.
sinceDate (String) – (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.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenges (List[Object]) – (required) See `Challenge` for format of the objects.

Opt-in to a Challenge for a Guest ¶

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:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. challengeCode (String) – (required) The unique code of the challenge. charitableOrganizationCode (String) – (optional) The unique code of the charitable organization.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenge (Object) – (required) See `Challenge` for format of the object.

Opt-out of a Challenge for a Guest ¶

POST challenge/optOutOfChallenge.json¶

User wants to terminate (opt-out of) an active challenge

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. challengeCode (Long) – (required) The unique code of the challenge.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenge (Object) – (required) See `Challenge` for format of the object.

Get Detail of a Challenge Occurrence ¶

GET challenge/challengeOccurrence.json¶

Get the details of a challenge by the challenge occurrence

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. challengeOccurrenceCode (Long) – (required) The unique code of the challenge.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` challenge (Object) – (required) See `Challenge` for format of the object.

Get Charitable Organizations For Challenge ¶

GET challenge/charitableOrganizationsForChallenge.json¶

Get the charitable organizations for a challenge

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. challengeCode (String) – (required) The unique code of the challenge.

"result": "success"

JSON Parameters:
	organizations (List[Object]) – {required) List of charitable organizations. See `CharitableOrganizationSummary` for format of the object.

Reply Objects ¶

Challenge¶

JSON Parameters:

code (Long) – (required) The unique code of this challenge.
name (String) – (required) The name of this challenge.
description (String) – (required) The description of this challenge.
startDate (Date) – (required) The date that this challenge started (or will start).
endDate (Date) – (required) The date that this challenge will end.
status (String) – (required) The status of the challenge. On one ACTIVE, COMPLETED, EXPIRED, ELIGIBLE, OPTED_OUT, OPTED_IN.
counters (List[Object]) – (required) Only present is status is ‘’’ACTIVE’’’. A list of the counters associated to the challenge. See Counter for format of the objects.

CharitableOrganizationSummary¶

JSON Parameters:
	code (String) – (required) The unique code for this charitable organization. displayName (String) – (required) The name of this charitable organization. iconCode (String) – (optional) The code which denotes the icon image to display for this charitable organization.

Counter¶

JSON Parameters:

code (Long) – (required) The unique code of this counter.
name (String) – (required) The name of this counter.
value (Decimal) – (required) The current value of this counter that the user/group has achieved.
threshold (Decimal) – (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.
details (List[Object]) – (required) A list of the details used in the calculation of the counter’s value. See CounterDetail for format of the objects.

CounterDetail¶

JSON Parameters:

memberCode (String) – (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.
numericValue (Decimal) – (required) If the calculation computes numeric values, then this field will be present.
stringValue (String) – (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.