Social Group Service ¶

The social group service provides endpoints which allows a user to join/create a group of other members who, together, can take challenges and earn rewards and badges.

Topics

Social Group Service

Endpoints ¶

Get Social Groups Containing Friends of a Member by External Account ¶

GET socialgroup/groupsContainingMyFriendsByExternalAccounts.json¶

Obtains a list of groups which contain a member that matches one of the external accounts (e.g., Facebook IDs)

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.
externalIdentifier (String) – (required) Paytronix-assigned code. Contact Paytronix to understand what the possible values are.
accountCodes (List[String]) – (required) The list of codes (e.g., Facebook IDs). Maximum of 100.
cardTemplateCode (Integer) – (optional) Paytronix-assigned card template code identifying the card type of the user.

"result": "success"

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

Get Social Groups Containing Friends of a Member by Email Address ¶

GET socialgroup/groupsContainingMyFriendsByEmailAddresses.json¶

Obtains a list of groups (and their members) which contain a member that matches one of the email addresses

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. emails (List[String]) – (required) The list of email addresses. cardTemplateCode (Integer) – (optional) Paytronix-assigned card template code identifying the card type of the user.

"result": "success"

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

Request to Join a Social Group by Member External Account ¶

POST socialgroup/requestToJoinGroupByMemberExternalAccount.json¶

A person wants to become a member of a group (that they found using GET socialgroup/getGroupsContainingMyFriendsByExternalAccounts.json). They must also provide an external account (i.e., Facebook ID) of an existing member for security reasons. This is is an unsolicited request which means that a group admin must approve/reject the request.

The following authentication methods are allowed for this endpoint:

JSON 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.
externalIdentifier (String) – (required) Paytronix-assigned code. Contact Paytronix to understand what the possible values are.
accountCode (String) – (required) The external code (e.g., Facebook ID) of an existing member

"result": "success"

JSON Parameters:
	result (String) – (required) `success` invitation (List[Object]) – (required) See `Invitation` for format of the object.

Request to Join a Social Group by Member Email Address ¶

POST socialgroup/requestToJoinGroupByMemberEmailAddress.json¶

A person wants to become a member of a group (that they found using GET socialgroup/getGroupsContainingMyFriendsByEmailAddresses.json). They must also provide an email address of an existing member for security reasons. This is is an unsolicited request which means that a group admin must approve/reject the request.

The following authentication methods are allowed for this endpoint:

JSON 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. email (String) – (required) The email address of an existing member.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` invitation (List[Object]) – (required) See `Invitation` for format of the object.

Accept a Join Group Request ¶

POST socialgroup/acceptJoinGroupRequest.json¶

A group admin uses this call to accept an (unsolicited) request to join a group (from POST socialgroup/requestToJoinGroupByMemberExternalAccount.json or POST socialgroup/requestToJoinGroupByMemberEmailAddress.json).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

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

Reject a Join Group Request ¶

POST socialgroup/rejectJoinGroupRequest.json¶

A group admin uses this call to reject an (unsolicited) request to join a group (from POST socialgroup/requestToJoinGroupByMemberExternalAccount.json or POST socialgroup/requestToJoinGroupByMemberEmailAddress.json).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Cancel a Join Group Request ¶

POST socialgroup/cancelJoinGroupRequest.json¶

A user wishes to cancel their own request to join a group submitted via POST socialgroup/requestToJoinGroupByMemberExternalAccount.json or POST socialgroup/requestToJoinGroupByMemberEmailAddress.json.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Leave a Social Group ¶

POST socialgroup/leaveGroup.json¶

A member wants to remove themselves from the group.

The following authentication methods are allowed for this endpoint:

JSON 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`

Get Detail of a Member’s Social Groups ¶

GET socialgroup/myGroups.json¶

A member wants to view the details of all groups of which they are a member.

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. cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program of the group. If not specified, then groups from all programs are returned.

"result": "success"

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

Create a Social Group ¶

POST socialgroup/createGroup.json¶

A user wants to create a new group.

The following authentication methods are allowed for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
username (String) – (required) The username (login) of the user.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program of the group.
name (String) – (required) The name of the group.
iconCode (String) – (required) The code denoting the icon for the group.

"result": "success"

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

Invite Friend of a Member to a Social Group by External Account ¶

POST socialgroup/inviteFriendToGroupByExternalAccount.json¶

A group admin want to add a person to the group using their external account (e.g., Facebook ID). The person might not be a registered user of the system.

The following authentication methods are allowed for this endpoint:

JSON 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.
name (String) – (required) The name of the invitee.
externalIdentifier (String) – (required) Paytronix-assigned code. Contact Paytronix to understand what the possible values are.
accountCode (String) – (required) The external code (e.g., Facebook ID).
email (String) – (required) The email address of the invitee.
url (String) – (required) A URL which will be embedded in an email sent to the invitee (if configured to do so and email address is known). An invitationCode will be appended to the URL as a parameter.

"result": "success"

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

Invite Friend of a Member to a Social Group by Email Address ¶

POST socialgroup/inviteFriendToGroupByEmailAddress.json¶

A group admin want to add a person to the group using their email address. The person might not be a registered user of the system.

The following authentication methods are allowed for this endpoint:

JSON 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.
name (String) – (required) The name of the invitee.
email (String) – (required) The email address of the invitee.
url (String) – (required) A URL which will be embedded in an email sent to the invitee (if configured to do so and email address is known). An invitationCode will be appended to the URL as a parameter.

"result": "success"

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

Get Pending Invitations to Social Groups ¶

GET socialgroup/pendingInvitationsToGroups.json¶

A member wants to view all of the invitations to groups of which they were invited/requested to join.

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.

"result": "success"

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

Get Details on Pending Invitation to a Social Group ¶

GET socialgroup/pendingInvitationToGroup.json¶

A person (who may or may not be a registered user of the system) wants to view the invitation and group based on an invitation code (which they probably received in an email). If they are not a registered user, then they must register before trying to later accept this invitation. However, they do not need to register if they decide to later reject the invitation.

The following authentication methods are allowed for this endpoint:

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

"result": "success"

JSON Parameters:
	result (String) – (required) `success` invitation (List[Object]) – (required) See `Invitation` for format of the object.

Get Pending Invitations to a Social Group ¶

GET socialgroup/pendingInvitationsToGroup.json¶

A group admin wants to view all of the pending invitations to the group. They can accept/reject any of the invitations which were solicited (i.e., if the wasInvited flag of the invitation is true).

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` invitations (List[Object]) – (required) See `Invitation` for format of the objects.

Accept an Invitation to Join a Social Group ¶

POST socialgroup/acceptJoinGroupInvitation.json¶

A person wants to accept an invitation to join a group (from either POST socialgroup/inviteFriendToGroupByExternalAccount.json or POST socialgroup/inviteFriendToGroupByEmailAddress.json).

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

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

Reject an Invitation to Join a Social Group ¶

POST socialgroup/rejectJoinGroupInvitation.json¶

A person wants to reject an invitation to join a group (from either POST socialgroup/inviteFriendToGroupByExternalAccount.json or POST socialgroup/inviteFriendToGroupByEmailAddress.json). The person might not be a registered user of the system.

The following authentication methods are allowed for this endpoint:

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

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Cancel an Invitation to Join a Social Group ¶

POST socialgroup/cancelJoinGroupInvitation.json¶

A group admin wants to cancel an invitation or a request to join.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. If the person is not a registered user of the system, then this field is optional. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Remove Member from a Social Group ¶

DELETE socialgroup/removeMemberFromGroup.json¶

A group admin wants to remove a member from 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. memberCode (Long) – (required) The unique code of the member.

"result": "success"

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

Modify a Social Group Member’s Role in the Group ¶

POST socialgroup/modifyMemberRoleInGroup.json¶

A group admin wants to change a member’s roles within the group.

The following authentication methods are allowed for this endpoint:

JSON 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.
memberCode (Long) – (required) The unique code of the member.
admin (Boolean) – (required) True if the member should become an admin.
owner (Boolean) – (required) True if the member should become an owner.

"result": "success"

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

Modify Details of a Social Group ¶

POST socialgroup/modifyGroup.json¶

A group owner wants to change the group’s name and icon code.

The following authentication methods are allowed for this endpoint:

JSON 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. name (String) – (required) The new name of the group. iconCode (String) – (required) The new icon code of the group.

"result": "success"

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

Create an Invitation Message ¶

POST socialgroup/createInvitationMessage.json¶

Create a message for the user based on the invitation (needed if the user registered after the invitation was sent). This call can fail if the user is not permitted to accept the invitation.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) The username (login) of the user. invitationCode (String) – (required) The unique code of the invitation.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` message (String) – (required) The message content that was created for the invitation.

Reply Objects ¶

ExternalAccountSocialGroupSummary¶

JSON Parameters:
	externalIdentifier (String) – (required) Paytronix-assigned code. Contact Paytronix to understand what the possible values are. accountCode (String) – (required) The code (e.g., Facebook IDs). group (Object) – (required) A summary of the group. See `SocialGroupSummary` for format of the object.

SocialGroupSummary¶

JSON Parameters:

code (Long) – (required) The unique code of this group.
name (String) – (required) The name of this group.
maxMembers (Integer) – (required) The maximum number of members in this group.
creator (String) – (required) The name of the member who created this group (only first name and last initial).
iconCode (String) – (required) The code which denotes the icon image to display for this group.
members (List[String]) – (required) The list of current member names (only first name and last initial).

SocialGroup¶

JSON Parameters:

code (Long) – (required) The unique code of this group.
name (String) – (required) The name of this group.
maxMembers (Integer) – (required) The maximum number of members in this group.
creator (Object) – (required) The member who created this group. See Creator for format of the object.
iconCode (String) – (required) The code which denotes the icon image to display for this group.
members (List[Object]) – (required) A list of the members of the group. See Member for format of the objects.

Member¶

JSON Parameters:

code (Long) – (required) The unique code of this member.
name (String) – (required) The name of this member.
nickname (String) – (required) The nickname of this member.
avatarCode (String) – (required) The code which denotes the icon image to display for this member.
isAdmin (Boolean) – (required) True if this member is an administrator of the group
isOwner (Boolean) – (required) True if this member is an owner of the group
joinDate (Date) – (required) The date the member joined the group
leaveDate (Date) – (required) The date the member left the group
accountCode (Long) – (required) The account code of this member.

Creator¶

JSON Parameters:
	name (String) – (required) The name of this user. nickname (String) – (required) The nickname of this member. avatarCode (String) – (required) The code which denotes the icon image to display for this member.

Invitation¶

JSON Parameters:

code (String) – (required) The unique code of this invitation.
name (String) – (required) The name of the person who was invited/requested to join.
inviteeExternalIdentifier (String) – (required) If the person was invited through an external account (e.g., Facebook), this is thee Paytronix-assigned code. {{REST/Parameter/integrationValues}}
inviteeExternalAccountCode (String) – (required) If the person was invited through an external account (e.g., Facebook), this is their unique code in that external service.
inviteeExternalEmail (String) – (required) If the person was invited through email, this was the address where the invitation was sent.
wasInvited (Boolean) – (required) True if the person was invited by a group member to join the group. False if the person requested to join the group (unsolicited).
isRegistered (Boolean) – (required) True if the person is a registered user of the system.
memberName (String) – (required) The name of the group member who sent the invitation (if wasInvited is true) or who received the join request (if wasInvited is false).
memberAvatarCode (String) – (required) The avatar of the group member who sent the invitation (if wasInvited is true) or who received the join request (if wasInvited is false).
group (Object) – (required) The group associated to the invitation. See SocialGroupSummary for format of the object.

Error Codes ¶

The following are the possible codes and messages that can be returned by the Social Group 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
`social_group.not_implemented`	Not yet implemented
`social_group.user_not_found`	User not found
`social_group.template_not_found`	Card Template not found
`social_group.external_identifier_not_allowed`	Not permitted to search by external identifier
`social_group.user_lookup_error`	Unable to get user
`social_group.group_lookup_error`	Unable to get group
`social_group.groups_lookup_error`	Unable to get groups
`social_group.group_not_found`	Group not found
`social_group.invitation_not_found`	Invitation not found
`social_group.members_lookup_error`	Unable to get group members
`social_group.invitations_lookup_error`	Unable to get group invitations
`social_group.requests_lookup_error`	Unable to get group requests
`social_group.request_lookup_error`	Unable to get group request
`social_group.invite_lookup_error`	Unable to get group invitation
`social_group.account_lookup_error`	Unable to get account
`social_group.memberships_lookup_error`	Unable to get group memberships
`social_group.max_members`	Group contains maximum number of members
`social_group.max_invitations`	Group contains maximum number of invitations
`social_group.already_in_group`	Already a member of group
`social_group.already_have_request`	Already have a request to join group
`social_group.already_have_invite`	Already have an invitation to join group
`social_group.group_config_not_found`	Group configuration not found
`social_group.max_groups`	Request would exceed the maximum group memberships
`social_group.max_requests`	Request would exceed the maximum group requests
`social_group.max_create`	User cannot create any more groups
`social_group.ext_acct_not_in_group`	Member with given external account is not in group
`social_group.email_not_in_group`	Member with given email address is not in group
`social_group.insert_request`	Unable to add request
`social_group.insert_invitation`	Unable to add invitation
`social_group.invalid_invitation_code`	Invalid invitation code
`social_group.invalid_or_expired_invitation_code`	Invalid or expired invitation code
`social_group.not_member`	Not member of group
`social_group.not_admin`	Not an administrator of group
`social_group.insert_member`	Unable to add member
`social_group.delete_invitation`	Unable to delete invitation
`social_group.delete_member`	Unable to delete member
`social_group.update_member`	Unable to update member
`social_group.name_exists`	A group with the given name already exists
`social_group.insert_group`	Unable to create group
`social_group.update_group`	Unable to update group
`social_group.max_owners`	Group contains maximum number of owners
`social_group.max_admins`	Group contains maximum number of administrators
`social_group.invalid_name`	Group name is invalid
`social_group.invalid_arguments`	Invalid arguments
`social_group.invalid_max_members`	Maximum members is invalid
`social_group.invalid_max_owners`	Maximum owners is invalid
`social_group.invalid_max_admins`	Maximum admins is invalid
`social_group.invitation_for_another`	Invitation is for another person