Event Notification File

A record of notable events which have occurred in Helix since the last file (about 15 minutes).

📘

This is a master file

This is the master events file. All events occurring within your Helix instance will appear in this file. For certain event types, there are additional event-specific data points that are not included in this file. To get the additional data points you can match the UserEventId found in this file with the same UserEventId in the extension files. For additional card event data, see the Card Event Notification File. For additional statement event data, see the Statement Event Notification File.

Event Notification File Definition

The Event Notification File is created by Helix on an hourly basis. It has the following properties:

  1. Fixed-length
  2. ANSI encoded
  3. Line endings are Windows-style CarriageReturn + LineFeed (\r\n, or 0x0D0A)
  4. File will be available in the relative directory of /EventNotification
  5. File name follows a specific, case-sensitive pattern of: yyyyMMddhhmm_EVENTNOTIFICATION.TXT
🚧

Format Disclaimer
Helix reserves the right to append new field(s) to the end of any Header or Content line without notice. This is to allow new data points to be added as needed in a timely fashion.

Implementation Note
Your code should be written such that unexpected characters after the "last" field but prior to the end of each line should be ignored. That is, if the file is documented as being 872 bytes per line, receiving a file with 984 bytes per line should not disrupt your processing. This applies to both Header and Content lines.

File Name Disclaimer
The date in file name should be used as a guideline for human eyes only. Any date-related programmatic dependencies should rely on the FileCreatedDate or FileEffectiveDate contained within the header line of each file, as these will be precise to the second and will be in the appropriate timezone.

Header Row

Property

Data Type (Length)

Alignment

Start Position

Description

Record Type

string (1)

Left

1

The flag for the header row. Will always be H.

File Name

string (50)

Left

2

The name of this request file excluding path.
Format: yyyyMMddhhmm_EVENTNOTIFICATION.TXT
Example: 201809060605_EVENTNOTIFICATION.TXT

Record Count

integer (10)

Right

52

The number of records represented within the file. This field is zero-padded on the left side.
Example: 0000000872

File Created Date

datetime (34)

Left

62

The date the file was created. Follows same format as API.
Example: 2014-10-20T10:30:31.456-05:00
See data format guidelines

File Effective Date

datetime (34)

Left

96

The date to which the data in the file pertains. Follows same format as API.
Example: 2014-10-20T23:59:59.999-05:00
See data format guidelines

Content Row

Property

Data Type (Length)

Alignment

Start Position

Description

Customer ID

integer (10)

Right

1

The unique identifier for a customer. This field is zero-padded on the left side.
Example: 0000000872

Customer Tag

string (50)

Left

11

The client-supplied unique identifier for the customer, aka the tag property on the customer object. This may be empty as it is an optional property.

Account ID

integer (10)

Right

61

The unique identifier for the account to which this event applies. May be 0000000000 if this event does not apply to a specific account. This field is zero-padded on the left side.
Example: 0008309285
This is NOT an account number. It is the accountId of an account object.

Account Tag

string (50)

Left

71

The client-supplied unique identifier for the account, aka the tag property on the account object to which this event applies. This is an optional field and may be empty.

External Account ID

integer (10)

Right

121

The unique identifier for the externalAccount object to which this event applies. May be 0000000000 if this event does not apply to a specific external account. This field is zero-padded on the left side.
Example: 0008309285
This is NOT an account number. It is the externalAccountId of an externalAccount object.

External Account Tag

string (50)

Left

131

The client-supplied unique identifier for the external account, aka the tag property on the externalAccount object. This may be empty as it is an optional property.

Transaction ID

long integer (19)

Right

181

The unique identifier for the transaction. This field is zero-padded on the left side.
Example: 0000000000008309285

Transaction Tag

string (50)

Left

200

The client-supplied unique identifier for the transaction. See transaction object definition for details.

Description

string (50)

Left

250

A human-readable description of the event.

Event Type ID

integer (10)

Right

300

The type of event that occurred. See Event Types for possible values

Transaction Type Code

string (6)

Left

310

A programmatic code for the type of transaction. See Transaction Types for details.

Transaction Settled Date

string (34)

Left

316

The date and time the transaction was settled. See transaction object definition for details.

Transaction Available Date

string (34)

Left

350

The date and time the funds associated with the transaction became available. See transaction object definition for details.

User Event ID

integer (19)

Right

384

This is a unique identifier for each event. Can be used to cross reference against the Card Event Notification File, Statement Event Notification File or the Realtime Event sent via Azure Service Bus.

Master ID

long integer (19)

Right

403

All related transactions will have the same MasterId.

Transaction Amount

integer (15)

Right

422

The amount of funds this transaction represents. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32.

Transaction Created Date

string (34)

Left

437

The date and time the transaction was requested. See transaction object definition for details.

Transaction Subtype Code

string (6)

Left

471

The Merchant Category Code of the merchant where the transaction originated. Categorizes merchants with similar lines of business together.

Transaction Type Code

string (6)

Left

477

The typeCode of the transaction object.

From Account ID

integer (10)

Right

483

The unique identifier for the account from which funds were withdrawn (i.e. account was debited). This field is zero-padded on the left side.
Example: 0008309285
This is NOT an account number. It is the accountId of an account or an externalAccountId of an externalAccount object.

From Available Balance

integer (15)

Right

493

The availableBalance property of the account object that was debited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

From Account Balance

integer (15)

Right

508

The accountBalance property of the account object that was debited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

From Pending Balance

integer (15)

Right

523

The pendingBalance property of the account object that was debited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

To Account ID

integer (10)

Right

538

The unique identifier for the account to which funds were deposited (i.e. account was credited). This field is zero-padded on the left side.
Example: 0008309285
This is NOT an account number. It is the accountId of an account or an externalAccountId of an externalAccount object.

To Available Balance

integer (15)

Right

548

The availableBalance property of the account object that was debited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

To Account Balance

integer (15)

Right

563

The accountBalance property of the account object that was credited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

To Pending Balance

integer (15)

Right

578

The pendingBalance property of the account object that was credited as a result of the action that caused the event. This field is zero-padded on the left side and two decimals will be assumed, e.g., 000000000000832 represents an amount of $8.32. -00000000000832 represents an amount of -$8.32.

Modified By ID

integer (10)

Right

593

The unique identifier for the Customer, Admin User, or 0 for system generated events. This field is zero-padded on the left side.
Example: 0008309285

Event Date

string (34)

Left

603

The date and time the event was triggered on.

Is Admin User

integer (1)

Left

637

Flag to indicate if ModifiedById is an Admin User. Value will be 1 if ModifiedById is an Admin User and 0 otherwise.

Customer Lock Status

integer (1)

Left

638

The isLocked property of the customer object.
Possible values:

  • 1: - Locked
  • 0: - Is not Locked

Account Lock Status

integer (1)

Left

639

The isLocked property of the account object. Possible values:

  • 1: - Locked
  • 0: - Is not Locked

Return Reason Code

string (3)

Left

640

The Nacha return code representing why the transaction was returned.

Card ID

integer
(10)

Right

643

Helix-assigned unique ID for the card

New Card ID

integer (10)

Right

653

Helix-assigned unique ID for a renewed card

{ "file_type": "fixed_length" }