Push Notification Configuration

Push notifications are used to inform merchants of events that occurred in the system that are not a direct result of an API call.

Push Notifications

Push notifications are used to inform merchants of events that occurred in the system that are not a direct result of an API call. Merchants subscribe to any number of Event Classes, or individual Events, and receive push notifications, when those events occur. Push Notifications are HTTPS POST requests with a JSON message. Subscribe Push messages include the full related object or objects, aligned with the Event or Event Class, in JSON format. For more details, see the Push Notification chapter. In general, new events willwilll now be added only in Push 2.0. Push 2.0 sends REST API objects as the message payload for specific events. Vindicia offers 3 authentication/identification methods for the listeners/endpoints to recognize the source of the messages as coming from Retain:

HMAC key
Basic Auth
OAuth 2.0 - available only for Push 2.0

Merchants are required to provide different information in order to set up a subscription to certain event/event classes to an endpoint (listener). This is explained in depth in Push Notification chapter.

Internally Set Up Push Notification

There are three steps to setup push notifications :

Generate an HMac key to be used by the merchant to authenticate the messages are received from Vindicia. This is done as part of the merchant creation process. (Remember to enter in Merchant Option called PUSH_HMAC_KEY) Note: If Basic auth or Oauth will be used, this may not be needed.
Collect all merchant info required for the setup including general info such as event classes needed and the relevant endpoints. Merchant provides the required info in the MAC/onboarding form or as part of a support ticket. See the Download button below for a Push Notification Requirement form that can be shared with the merchant.
Define the merchant information in the merchant configuration page. Note: Don’t forget to also set the date when to start sending messages.
Merchant sets up listener.

[

](../images/PushNotificationSetupRequest.xlsx)

Field	Description	Valid Values
push_hmac_key	If using HMAC for source validation of the push messages, this is the HMAC key to provide to the merchant.	Key (string)
push_on	This parameter will define the date when push notifications will start. This is relevant only for PUSH 1. In addition, every push message class has a date when it can be started.	empty (default) or date
push_special	Only relevant to PUSH 1. The value need to be set to 1 as default. This impact mainly entitlements	0,1 (default) , null
push_soap_api_version	This will define the format of the push messages. For SOAP users, it is desirable to set this field to the same SOAP version the merchant is using. For REST users, preferable to set this to ‘rest’ - to get the same fields name	- empty - will indicate the latest soap version is used (default) - soap version (26.0) - rest - will issue the push notification on the default rest version

Push Configuration Name Value Pairs

Name	Description	Valid values
push_2_enabled	If merchant will be using Push 2.0 platform, enable this NVP.	1- enabled. 0-disabled
push_timestamp_milliseconds	Relevant for event timestamp format. When enabled, event timestamp will use a more detailed format `date-fullyear"-"date-month"-"date-mday" "time-hour":"time-minute":"time-second"."time-secfrac"-"time-numoffset`	1- enabled. 0-disabled
do_not_reformat_datetime	Allows to choose whether to convert all datetime attributes to ISO 8601 (milliseconds format) for Push 2.0. When enabled, will not convert to ISO 8601.	1- enabled. 0-disabled (default)
ReturnFullObjectInPush	Allows to return the full Subscription object for End of trial and Pre- notification Push messages- see Invoice Push Notifications.	1- enabled. 0-disabled (default)
Push 2.0 Only - OAuth 2.0 Authentication configuration
OAuth2 endpoint	The merchant’s identity provider OAuth server URL for token retrieval	URL. For example:https://uulp.stag-ozd9rfhux3s8fi2s.us.auth0.com/oauth/token
OAuth2 audience	The merchant’s identity provider app for setup or integration.	For example: myApp
OAuth2 username	Merchant-provided credentials allowing Vindicia to access the provider and retrieve initial token.	username string
OAuth2 password	Merchant-provided credentials allowing Vindicia to access the provider and retrieve initial token.	password string
OAuth2 access_token	Read Only. This is the access token received from the OAuth server and used internally.	Read only. Do not change.
OAuth2 expire_ts	Read Only. An internal timestamp indicating when the token expires and needs renewal.	Read only. Do not change.

Home

Guides

APIs

Push Notifications

Internally Set Up Push Notification

Push Configuration Name Value Pairs

​Push Notifications

​Internally Set Up Push Notification

​Push Configuration Name Value Pairs

Push Notifications

Internally Set Up Push Notification

Push Configuration Name Value Pairs