REST Message Service

The rest message service provides endpoints which allows a user to send messages to a guest user identified by printed card number, account id, or email address. Must have a corresponding email template with the necessary parameters already set up in the Paytronix portal.

Endpoints

Send Marketing Message By Printed Card Number

POST messaging/sendMarketingMessageByPrintedCardNumber.json

Sends a message to a given Printed Card Number

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in
  • campaignMessageTemplateCode (Integer) – (required) Campaign Message Template Code that uniquely identifies the Campaign Message Template
  • printedCardNumber (String) – (required) Printed Card Number to send message to
  • replacementParams (Map[String->String]) – (required) Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
  • deliveryMethod (String) – (required) String specifying message type current this is only enabled for EMAIL
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"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.

Send Marketing Message By Account Id

POST messaging/sendMarketingMessageByAccountId.json

Sends a message to a given Account Id

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • campaignMessageTemplateCode (Integer) – (required) Campaign Message Template Code that uniquely identifies the Campaign Message Template
  • accountId (Integer) – (required) Paytronix-assigned unique identifier for the Account
  • replacementParams (Map[String->String]) – (required) Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
  • deliveryMethod (String) – (required) String specifying message type current this is only enabled for EMAIL
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"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.

Send Transactional Message By Printed Card Number

POST messaging/sendTransactionalMessageByPrintedCardNumber.json

Sends a message to a given Printed Card Number ignoring the opted-in status

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • campaignMessageTemplateCode (Integer) – (required) Campaign Message Template Code that uniquely identifies the Campaign Message Template
  • printedCardNumber (String) – (required) Printed Card Number to send message to
  • replacementParams (Map[String->String]) – (required) Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
  • deliveryMethod (String) – (required) String specifying message type current this is only enabled for EMAIL
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"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.

Send Transactional Message By Account Id

POST messaging/sendTransactionalMessageByAccountId.json

Sends a message to a given Account Id ignoring the opted-in status

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • campaignMessageTemplateCode (Integer) – (required) Campaign Message Template Code that uniquely identifies the Campaign Message Template
  • accountId (Integer) – (required) Account ID to send message to
  • replacementParams (Map[String->String]) – (required) Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
  • deliveryMethod (String) – (required) String specifying message type current this is only enabled for EMAIL
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"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.

Send Transactional Message By Email Address

POST messaging/sendTransactionalMessageByEmailAddress.json

Sends a message to a given email address ignoring the opted-in status. The provided email address does not need to have an associated Paytronix user. Emails to existing Paytronix users should be sent using one of the other sendTransactionalMessageBy… endpoints rather than this one.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • campaignMessageTemplateCode (Integer) – (optional) Campaign Message Template Code that uniquely identifies the Campaign Message Template. This field is required if eventType isn’t being sent.
  • emailAddress (String) – (required) Email address to send message to
  • replacementParams (Map[String->Object]) – (required) Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created. See TemplateSubstitutionParameter below for the format of the object.
  • deliveryMethod (String) – (required) String specifying message type current this is only enabled for EMAIL
  • eventType (String) – (optional) String specifying event type, currently this is only enabled for ONLINE_ORDERING_RECEIPT. Do not send this value unless explicitly instructed to do so by Paytronix
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
"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.
  • fieldErrors (Set[FieldAndError]) – (optional) A set of all the validation errors on replacementParams by field. See FieldAndError below for the format of the object.

Constant Values

deliveryMethod Values

EMAIL
Send an email message

Request Objects

TemplateSubstitutionParameter
This object can be one of String, Integer, Decimal, or Seq[Map[String -> TemplateSubstitutionParameter]]
Sequences should be named JSON arrays containing TemplateSubstitutionParameter

Example:

"replacementParams": {
        "FirstName": "Bob",
        "LastName": "Bilder",
        "OrderNumber": "ORDER1",
        "order_items": [
                {
                        "name": "chocolate cake",
                        "quantity": 1,
                        "price": 5.32,
                        "modifiers": [
                                {
                                        "modifier_type": "fruit",
                                        "modifier_value": "strawberry"
                                },
                                {
                                        "modifier_type": "size",
                                        "modifier_value": "8 inches"
                                }
                        ],
                        "Discount": "None"
                },
                {
                        "name": "cookie",
                        "quantity": 10,
                        "price": 3,
                        "modifiers": [
                                {
                                        "modifier_type": "cutlery",
                                        "modifier_value": "No"
                                }
                        ],
                        "Discount": "None"
                }
        ],
        "specialInstructions": "Please write 'Happy Birthday' on the cake",
        "SubTotal": "21.50",
        "DiscountTotal": "0.00",
        "Tax": "1.47",
        "Total": "22.97",
        "PaymentType": "Credit Card"
}

Response Objects

FieldAndError

This object has a field and an error attribute.

Possible values for the error attribute:

missing_field
expected_sequence
unexpected_sequence

Example:

"fieldErrors":
[
   {
           "field": "CheckTotal",
           "error": "missing_field"
   },
   {
           "field": "ordered_items",
           "error": "expected_sequence"
   }
]

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
restmessaging.invalid_template_code Campaign Message Template code is invalid
restmessaging.invalid_user User does not exist
rest messaging.invalid_email_address Email Address provided is invalid
rest messaging.field_errors Some required replacementParameters are missing. Please correct them and then retry.
restmessaging.user_opted_out User is opted out
restmessaging.user_email_failed User’s email is marked failed
restmessaging.system_error Failed to validate replacement parameters against email template
restmessaging.system_error System error
system.error At deliveryMethod: “<method>” is not a valid enumeration value (valid values: EMAIL)