.. _mobile_interstitial_service:

Mobile Interstitial Service
===============

The Mobile Interstitial service provides endpoints which allows a user to retrieve
mobile interstitial notifications for their account, as well as marking them as seen.

.. contents:: Topics

Endpoints
---------

Get Mobile Interstitials for Guest
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: mobileinterstitial/interstitialsForAccount.json

   Obtains a list of mobile interstitials for the user which have not been interacted with yet or expired.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query Integer accountId: *(required)*  The account ID of the user.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam List[Object] interstitials: *(required)*  See :http:jsonentity:`InterstitialInfo` for format of the objects.

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

Get Mobile Interstitials for Guest by Printed Card Number
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. http:get:: mobileinterstitial/interstitialsForPrintedCardNumber.json

   Obtains a list of mobile interstitials for the user which have not been interacted with yet or expired.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String printedCardNumber: *(required)*  The user's printed card number.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam List[Object] interstitials: *(required)*  See :http:jsonentity:`InterstitialInfo` for format of the objects.

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

Mark Interstitials As Seen
~~~~~~~~~~~~~~~~~~~

.. http:delete:: mobileinterstitial/markInterstitialsAsSeenForAccount.json

   Marks mobile interstitials as seen for this user.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query Integer accountId: *(required)*  The account ID of the user.
   :query List[Object] interstitialsAndActions: *(required)*  The list of interstitials to be marked as seen. See :http:jsonentity:`UserActionInterstitial` for format of the objects.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam String message: *(required)*  A message describing how many interstitials were deleted, if any.

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

Mark Interstitials As Seen By Printed Card Number
~~~~~~~~~~~~~~~~~~~

.. http:delete:: mobileinterstitial/markInterstitialsAsSeenForPrintedCardNumber.json

   Marks mobile interstitials as seen for this user.

   The following authentication methods are allowed for this endpoint:

   * :ref:`b2b_auth`
   * :ref:`oauth_auth`

   :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in.
   :query String printedCardNumber: *(required)*  The user's printed card number.
   :query List[Object] interstitialsAndActions: *(required)*  The list of interstitials to be marked as seen. See :http:jsonentity:`UserActionInterstitial` for format of the objects.

.. http:response:: success

   :jsonparam String result: *(required)*  ``success``
   :jsonparam String message: *(required)*  A message describing how many interstitials were deleted, if any.

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

Reply Objects
-------------

.. http:jsonentity:: InterstitialInfo

   :jsonparam Integer interstitialId: *(required)*  The interstitial ID.
   :jsonparam Object ctaButton: *(optional)*  See :http:jsonentity:`CTAButton` for format of the object.
   :jsonparam String closeButtonColor: *(required)*  The color of the close button.
   :jsonparam String interstitialImageUrl: *(required)*  The URL of the image to be displayed for the interstitial.

.. http:jsonentity:: CTAButton

   :jsonparam String deepLinkValue: *(required)*  The string of the deep link, associated with the deep link type.
   :jsonparam String deepLinkType: *(required)*  The deep link type, one of 'appScreen', 'categoryItem', 'externalUrl', 'menuItem', or 'survey'.
   :jsonparam String ctaButtonText: *(required)*  The text of the CTA button.
   :jsonparam String ctaTextColor: *(required)*  The color of the text of the CTA button.
   :jsonparam String ctaButtonBgColor: *(required)*  The color of the background of the CTA button.

.. http:jsonentity:: UserActionInterstitial

   :jsonparam Integer interstitialId: *(required)*  The interstitial ID.
   :jsonparam Boolean clicked: *(required)*  Whether the interstitial was clicked or not.

Error Codes
-----------

The following are the possible codes and messages that can be returned
by the Mobile Interstitial 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                        |
+================================================================+================================+
| ``mobile_interstitial_failure.invalid_merchant_id``            | Invalid Merchant Id            |
+----------------------------------------------------------------+--------------------------------+
| ``mobile_interstitial_failure.invalid_mobile_interstitial_id`` | Invalid mobile interstitial ID |
+----------------------------------------------------------------+--------------------------------+
| ``mobile_interstitial_failure.invalid_mobile_deep_link_id``    | Invalid Mobile Deep Link ID    |
+----------------------------------------------------------------+--------------------------------+
| ``mobile_interstitial_failure.invalid_card_number``            | Invalid Card Number            |
+----------------------------------------------------------------+--------------------------------+
| ``mobile_interstitial_failure.system_error``                   | System error                   |
+----------------------------------------------------------------+--------------------------------+
| ``mark_interstitials_seen.invalid_card_number``                | Invalid Card Number            |
+----------------------------------------------------------------+--------------------------------+
| ``mark_interstitials_seen.system``                             | System Error                   |
+----------------------------------------------------------------+--------------------------------+