Message Service

The message service provides endpoints which allows a user to retrieve messages and notifications for their account.

Endpoints

Get Notifications for Guest

GET message/myMessages.json

Obtains a list of messages for the user which have not been deleted.

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
  • messages (List[Object]) – (required) See Message for format of the objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Get Notifications for Guest by Printed Card Number

GET message/myMessagesByPrintedCardNumber.json

Obtains a list of messages for the user which have not been deleted.

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 user’s printed card number.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • messages (List[Object]) – (required) See Message for format of the objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Delete Notification

DELETE message/deleteMessage.json

Delete a single message associated to a user.

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.
  • messageCode (Long) – (required) The unique code for this message.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (Long) – (required) The code of the message that was deleted.
  • message (String) – (required) The content of the message that was deleted.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Delete Notification by Printed Card Number

DELETE message/deleteMessageByPrintedCardNumber.json

Delete a single message associated to a user.

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 user’s printed card number.
  • messageCode (Long) – (required) The unique code for this message.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (Long) – (required) The code of the message that was deleted.
  • message (String) – (required) The content of the message that was deleted.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Format Message

GET message/formatMessage.json

Format a message.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • sourceType (String) – (required) The source of the message. Indicates the application or user which generated the message. See sourceType Values.
  • eventType (String) – (required) The event type for this message. See eventType Values.
  • targetType (String) – (required) The target of this message. See targetType Values.
  • params (Map[String->String]) – (required) Parameters to be substituted.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • value (String) – (required) The formatted message.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Insert Message

PUT message/insertMessage.json

Insert a new message for a user.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • pxuserId (Integer) – (required) Paytronix-assigned pxuser ID of the user the message is being inserted for.
  • eventType (String) – (required) The event type for this message. See eventType Values.
  • params (Map[String->String]) – (required) Parameters to be substituted.
  • templateId (Integer) – (optional) ID of the template used.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (Long) – (required) The code of the message that was deleted.
  • message (String) – (required) The content of the message that was inserted.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.
"result": "retry"
Returned when the Message queue is filled and needs to be processed before inserting a new Message. Will retry after a few seconds.
JSON Parameters:
 
  • result (String) – (required) retry
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Constant Values

messageContextType Values

INVITATION_CODE
A Social Group Invitation code
WALLET_CODE
A Wallet code
GIFT_CODE
A Gift code (also called a Transfer)
CHALLENGE_CODE
A Challenge code
USER_CODE
A User code
ACCOUNT_CODE
An Account code (for a particular user)
CARD_NUMBER
The user/account’s card number
MEMBER_CODE
A Social Group Member code
STORE_CODE
A Store code
CARD_TEMPLATE_CODE
A Card Template code
TIER_CODE
A Tier code
PERK_CODE
A Perk code
SOCIAL_GROUP_CODE
A Social Group code
SALE_ORDER_CODE
A Sale Order code
CHALLENGE_OCCURRENCE_CODE
A particular instance of a Challenge (if a user took a challenge multiple times)
BADGE_CODE
A Badge Code
SURVEY_CODE
A Survey Code

sourceType Values

SYSTEM
System
MERCHANT
Merchant
USER
User
CAMPAIGN
Campaign
SOCIAL_GROUP
Group
CHALLENGE
Challenge

eventType Values

CHECKIN
Checkin
NEW_PENDING_TRANSFER
New Pending Transfer
TRANSFER_ACCEPTED
Transfer Accepted
TRANSFER_REJECTED
Transfer Rejected
TRANSFER_RETURNED
Transfer Returned
CAMPAIGN
Campaign
REFERRAL_COMPLETED
Referral Completed
REGISTER
Register
ATTACH
Attach
GUEST_MESSAGING_RULE
Guest Messaging Rule
ADMIN_MESSAGING_RULE
Admin Messaging Rule
REVERSE_ENROLL
Reverse Enroll
SOCIAL_GROUP_USER_REQUESTS_JOIN
Social Group User Requests Join
SOCIAL_GROUP_GROUP_INVITES_USER
Social Group Group Invites User
SOCIAL_GROUP_USER_ACCEPTS_INVITATION
Social Group User Accepts Invitation
SOCIAL_GROUP_USER_REJECTS_INVITATION
Social Group User Rejects Invitation
SOCIAL_GROUP_REQUEST_CANCELLED
Social Group Request Cancelled
SOCIAL_GROUP_INVITATION_CANCELLED
Social Group Invitation Cancelled
SOCIAL_GROUP_GROUP_ACCEPTS_REQUEST
Social Group Group Accepts Request
SOCIAL_GROUP_GROUP_REJECTS_REQUEST
Social Group Group Rejects Request
SOCIAL_GROUP_MEMBER_LEAVES
Social Group Member Leaves
SOCIAL_GROUP_MEMBER_REMOVED
Social Group Member Removed
SOCIAL_GROUP_CHALLENGE_COMPLETED
Social Group Challenge Completed
SOCIAL_GROUP_CHALLENGE_EXPIRED
Social Group Challenge Expired
SOCIAL_GROUP_CHALLENGE_ENTERED
Social Group Challenge Entered
SOCIAL_GROUP_CHALLENGE_ELIGIBLE
Social Group Challenge Eligible
SOCIAL_GROUP_CHALLENGE_EXPIRING
Social Group Challenge Expiring
SOCIAL_GROUP_REWARD_EXPIRING
Social Group Reward Expiring
SOCIAL_GROUP_GROUP_EARNED_POINTS
Social Group Earned Points
HELP
Help
OPT_OUT
Opt Out
OPT_IN_VERIFICATION
Opt In Verification
ENROLLMENT
Enrollment
UNKNOWN_REQUEST
Unknown Request
ENTER_REGION
Enter Region
ECLUB_REGISTER
Eclub Register
RESET_PASSWORD
Reset Password
REGISTRATION_EMAIL_VERIFICATION_REQUIRED
Registration Email Verification Required
SURVEY_PARTICIPANT_ENTERED
Survey Participant Entered
SURVEY_PARTICIPANT_COMPLETED
Survey Participant Completed
EXTERNAL_NOTIFICATION_RULE
External Notification Rule
MOBILE_PAYMENT_RECEIPT
Mobile Payment Receipt
REFERRAL_INVITATION
Referral Invitation
WEB_EGIFT_ORDER_CONFIRMATION
Web Egift Order Confirmation
WEB_EGIFT_ORDER_SUSPENDED
Web Egift Order Suspended
WEB_EGIFT_ORDER_ITEM_FULFILLMENT
Web Egift Order Item Fulfillment
WEB_EGIFT_FREE_ITEM_FULFILLMENT
Web Egift Free Item Fulfillment
ONE_TIME_RECHARGE
One Time Recharge
AUTO_RECHARGE_ENABLE
Auto Recharge Enable
AUTO_RECHARGE_SUCCESS
Auto Recharge Success
MOBILE_WALLET_DELIVERY
Mobile Wallet Delivery
REST_MESSAGING_TRANSACTIONAL
REST Messaging Transactional
WALLET_EXPIRATION
Wallet Expiration
POINTS_CHALLENGE_PROGRESS
Points Challenge Progress
POINTS_CHALLENGE_COMPLETION
Points Challenge Completion
SMS_NUMBER_CHANGE_EVENT_OPT_OUT
Sms Number Change Event Opt Out
AUTO_RECHARGE_FAILURE
Auto Recharge Failure
AUTO_RECHARGE_DISABLE
Auto Recharge Disable
REST_MESSAGING_MARKETING
REST Messaging Marketing

targetType Values

USER
User
SOCIAL_GROUP
Social Group
FACEBOOK
Facebook
TWITTER
Twitter
EMAIL
Email

Reply Objects

Message
JSON Parameters:
 
  • code (Long) – (required) The unique code of this message.
  • message (String) – (required) The text of the message.
  • sourceType (String) – (required) The source of the message. Indicates the application or user which generated the message. See sourceType Values.
  • senderName (String) – (required) If available, this is the name of the user who was the source of the message.
  • senderAvatarCode (String) – (required) If available, this is the avatar code of the user who was the source of the message.
  • contextType (String) – (required) The type of the context code. The “context” of the message provides the caller with information that can be used to obtain further information to be displayed in association with the message. For example, if the message says “You completed the challenge Eat Everything On The menu”, contextType might be CHALLENGE_CODE and the contextCode would be the unique code for the particular challenge. The caller could then make another REST call (e.g., to the Challenge Service) to get the details of the challenge to display along with the message (like, long description, challenge image, etc.). See messageContextType Values.
  • contextCode (String) – (required) If available, this is a code value specified by the contextType.
  • contextLabel (String) – (required) If available, this is a short label describing the item specified by the code.
  • contextDescription (String) – (required) If available, this is a long description describing the item specified by the code.
  • contextImageCode (String) – (required) If available, this is a code or partial URL or absolute URL used to specify an image for the item specified by the code.
  • contextLink (String) – (required) If available, this is a URL for a page describing the item specified by the code.
  • contextLinkLabel (String) – (required) If available, this is the label for the contextLink.
  • date (Date) – (required) The date that this message was created.
  • pullImageLink (String) – (optional) If available, this is a CDN URL for an image associated with this message.

Error Codes

The following are the possible codes and messages that can be returned by the Message 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
message.not_implemented Not yet implemented
message.user_not_found User not found
message.messages_lookup_error Unable to get messages
message.insert_message Unable to add message
message.message_not_found Message not found
message.delete_message Unable to delete message
message.invalid_argument Invalid argument
message.system_error System error