Events Publisher

Overview

Electrum generates notifications, known as events or event postings, for every transaction throughout its lifecycle. These notifications give information about the status of the transaction at a given time.

Some of the important pieces of information included in the event payload are:

  • Event class – indicates the type of information provided by the event. TRANSACTION_STATE indicates that the event provides information about the transaction's current state of processing, and is the only class currently supported.
  • Event type – for events in the TRANSACTION_STATE class, event type indicates the transaction processing stage that led to the event notification, e.g., CREDIT_AUTH_RECEIVED.
  • Transaction payload at the time of the event posting. This will be embedded inside the event posting message. Its schema, as defined by the Electrum API, will also be specified.

The example below shows a typical transaction journey of an outbound proxy resolution transaction. An event is generated each time a transaction progresses to a different state. So, for this example, you would expect to receive seven event notifications. Note that this example is illustrative – different scenarios will arise for the various transaction types that are supported.

proxy-res-outbound-1

Implementing the Events Publisher

Electrum generates event postings as a matter of course. You may choose whether or not you would like to receive these postings. These are some of the reasons that you may want to receive postings:

  • For informational and record-keeping purposes
  • To maintain an audit trail of all transactions
  • For customer support purposes – to provide a reference source for when consumers query the status of their transactions. For example, if a consumer is concerned that their payment has not been finalised after an expected time period, you could refer to the event postings and inform them if their transaction is still pending at a certain stage of the process.
Important

Event postings are purely informational. They do not affect transaction processing and do not require that you take any action.

What You Need To Implement

You will need to implement a single API endpoint, /events. Refer to our API documentation for a full definition of this call.
Once your endpoint is set up, Electrum will send a POST call for every event that occurs for every transaction that is processed.

You must also ensure that you have a system or database that can handle the receiving and storage of incoming event postings.

The events schema is shown below.

Important
Each event payload must include the class and type of the event, as well as the schema of the original transaction at the point of event generation.
Request Body schema: application/json
apiVersion
required
string

The version of the Electrum Regulated Payments Events API which the event format conforms to i.e. the version of this API.

class
required
string

The class of the event.

actionDate
required
string <date>

The date at which the transaction should take effect. The date must be formatted as defined by date-time in RFC3339

creationDateTime
required
string <date-time>

The date and time at which the event was created, in senders local timezone or UTC. The date must be formatted as defined by date-time in RFC3339

object (EventEsmPayload)
required
object (EventEsmIdentifiers)

Holds a series of identifiers to identify the transaction or an individual message that is part of a transaction.

required
object (EventEsmState)
required
object (EventEsmTransactionInfo)
application/json

Request for the inboundCreditTransferAuthorization operation is received by the Switch. A customer at Grey Bank, Bob, is paying a customer at Blue Bank, Alice, using RTC. Electrum's partner is Blue Bank.

{
  • "name": "TRANSACTION_STATE_CREDIT_AUTH_RECEIVED",
  • "apiVersion": "0.27.0",
  • "class": "TRANSACTION_STATE",
  • "type": "CREDIT_AUTH_RECEIVED",
  • "stageVersion": 1,
  • "tranInfo": {
    },
  • "messageInfo": {
    },
  • "payload": {
    }
}
Copyright © Electrum Payments (Pty) Ltd. 2019-2023. All right reserved.