EML Notifications

Overview and Concepts

Introduction

Transaction Notifications allows your organisation to receive real-time notifications of transactions which have occurred on your card program with EML. They are a flexible and powerful mechanism which you can use to build a broad range of overlay (or "value-added") services on top of your base card programs.

Some example usages include:

  • Send real-time alerts to your customers via email, SMS message or push notification when spending occurs on their account, or once new funds have been loaded to their account.
  • Real-time engagement with customers in your loyalty program when they spend money at particular merchants. Trigger cash-back to their account, reward them with loyalty points, or offer incentives for a repeat visit.
  • Monitor when balances are getting low on individual cards or a disbursement account, and trigger a top-up before someone is caught short.
  • Track spending in different categories, and notify your customers when they are ahead or behind on their budget.
  • Notify customers if other services are also available at a merchant they have visited, such as Cash Top-Up, etc.

The Transaction Notifications service includes a robust security scheme to protect your organisation, and a reliability mechanism to make your overlay services resilient to system outages or transient failures.

Basic Mechanisms

This service utilises webhooks. This refers to an HTTPS endpoint which is built and deployed by your organisation, which will receive messages from EML, delivered securely over the Internet.

Once deployed and configured, we will HTTP POST a message to your webhook URL as each relevant transaction occurs on your card program. The message will contain the particulars of that transaction, as well as some relevant contextual information.

This portal contains two references:

These are complementary references, and you will need both in order to implement Transaction Notifications for your organisation.

Security and Authentication

The Notification API utilises WS3 Common Authentication to control access.

There is also a separate scheme for authenticating messages which we send to your webhook. See Webhook Authentication for more details.

Reliable Delivery

When registering a webhook, you have the option of enabling reliable delivery. This option allows you to recover messages which can not be delivered to your webhook successfully in real-time due to system outages or transient failures.

Once it is enabled, transaction notifications which we fail to deliver to your webhook will be redirected to storage where you can retrieve them later.

Recovering undeliverable messages

There is a method provided by the Notification API which allows you to access these failed deliveries. Once you've retrieved and handled a failed delivery, you should mark them as resolved by dismissing them via the same API.

Undeliverable alerts

In addition to providing the API methods for managing your failed deliveries, we will also attempt to send Undeliverable Alerts to your webhook. These can serve as a prompt to go and check your failed deliveries. These alerts will repeat at a regular interval until all undeliverable messages have been dismissed.

Limited retention

EML will not perpetually store undeliverable messages. Messages older than 7 days which have not been dismissed will automatically expire. Expired messages are deleted permanently, so you should ensure that your webhook is robust, and that you handle undelivered messages promptly.

Downgraded webhooks

If we encounter ongoing issues with delivery to your webhook, our system may automatically downgrade the status of your webhook.

Stage 1: Real-time notifications paused

Repeated failures to deliver to your webhook within a 5 minute window may cause us to downgrade your webhook to a degraded mode. In this mode, all transaction notifications will bypass your webhook and flow automatically to your undeliverable storage. If you have not enabled reliable delivery for your webhook, transaction messages processed while you are degraded will be discarded.

Your webhook will remain degraded until we deliver a Ping Message successfully to your webhook. We will attempt these ping messages once every 10 minutes.

Stage 2: Disabled

Webhooks without any successful deliveries in a 5 day period will be automatically disabled. You can re-enable it later via the API, though we will not store any messages for your webhook while it is disabled.

Filter Rules

There is an upcoming feature which allows to specify some simple rules which restrict which transactions are delivered to your webhook.

In this release, the only valid value for filter_spec is *. That is: deliver all messages to my webhook.