.. _rest_message_service:

REST Message Service
====================

The rest message service provides endpoints which allows a user to send
messages to a printed card number or account id

.. contents:: Topics

Endpoints
---------

Send Marketing Message By Printed Card Number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:post:: messaging/sendMarketingMessageByPrintedCardNumber.json

   Sends a message to a given Printed Card Number

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in
   :jsonparam Integer campaignMessageTemplateCode: *(required)* Campaign Message Template Code that uniquely identifies the Campaign Message Template
   :jsonparam String printedCardNumber: *(required)*           Printed Card Number to send message to
   :jsonparam Map[String->String] replacementParams:    *(required)* Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
   :jsonparam String deliveryMethod: *(required)*       String specifying message type current this is only enabled for EMAIL

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.

Send Marketing Message By Account Id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:post:: messaging/sendMarketingMessageByAccountId.json

   Sends a message to a given Account Id

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam Integer campaignMessageTemplateCode: *(required)* Campaign Message Template Code that uniquely identifies the Campaign Message Template
   :jsonparam Integer accountId: *(required)*           Paytronix-assigned unique identifier for the Account
   :jsonparam Map[String->String] replacementParams:    *(required)* Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
   :jsonparam String deliveryMethod: *(required)*       String specifying message type current this is only enabled for EMAIL

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.

Send Transactional Message By Printed Card Number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

   * :ref:`b2b_auth`

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

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.


Send Transactional Message By Account Id
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam Integer campaignMessageTemplateCode: *(required)* Campaign Message Template Code that uniquely identifies the Campaign Message Template
   :jsonparam Integer accountId: *(required)*           Account ID to send message to
   :jsonparam Map[String->String] replacementParams:    *(required)* Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created
   :jsonparam String deliveryMethod: *(required)*       String specifying message type current this is only enabled for EMAIL

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.


Send Transactional Message By Email Address
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`

   :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :jsonparam Integer campaignMessageTemplateCode: *(required)* Campaign Message Template Code that uniquely identifies the Campaign Message Template
   :jsonparam String emailAddress: *(required)*         Email address to send message to
   :jsonparam Map[String->Object] replacementParams:    *(required)* Key-Value relation for the external_field replacement the key is specified by the user when the Email Template was created. See :http:jsonentity:`TemplateSubstitutionParameter` below for the format of the object.
   :jsonparam String deliveryMethod: *(required)*       String specifying message type current this is only enabled for EMAIL

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``

.. http:response:: failure

   :jsonparam String result: *(required)*  ``failure``
   :jsonparam String errorCode: *(required)*  The error code of the failure.
   :jsonparam String errorMessage: *(required)*  The (human readable) error message of the failure.
   :jsonparam Set[FieldAndError] fieldErrors: *(optional)* A set of all the validation errors on replacementParams by field. See :http:jsonentity:`FieldAndError` below for the format of the object.


Constant Values
---------------

.. _delivery_method:

``deliveryMethod`` Values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``EMAIL``
    Send an email message

Request Objects
~~~~~~~~~~~~~~~

.. http:jsonentity:: TemplateSubstitutionParameter

   This object can be one of String, Integer, Decimal, or Seq[Map[String -> TemplateSubstitutionParameter]]

Example

.. code:: javascript

   [{
      "name": "Visits",
      "code": 0
      "balance": 5.0
   },{
      "name": "Reward Dollars",
      "code": 1
      "balance": 2.5
   }]

Response Objects
~~~~~~~~~~~~~~~

.. http:jsonentity:: FieldAndError

   This object has a field and an error attribute.

Possible values for the error attribute:
.. code::

  missing_field
  expected_sequence
  unexpected_sequence


Example

.. code:: javascript

   [{
       "field": "item_name",
       "error": "missing_field"
   },{
       "field": "price",
       "error": "missing_field"
   }]


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.delivery_method``                          | Delivery method is invalid                                                              |
+------------------------------------------------------------+-----------------------------------------------------------------------------------------+
| ``restmessaging.system_error``                             | Failed to validate replacement parameters against email template                        |
+------------------------------------------------------------+-----------------------------------------------------------------------------------------+
| ``restmessaging.system_error``                             | System error                                                                            |
+------------------------------------------------------------+-----------------------------------------------------------------------------------------+