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.

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:

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

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:

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

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

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

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
  • 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:

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
  • 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:

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