Ingress Message Format

The ingress message format expected is Array<Transaction> or just a single Transaction where Transaction contains at least the following fields. You can provide further fields inside the meta object that the engine will include in the egress message, but the engine itself will not use the fields.

Ingress message schema

Field

Type

Required

Description

transactionId

String

Yes

Unique identifier for the transaction.

accountId

String

Yes

Unique identifier for the account.

userId

String

No

Unique identifier for the customer. N.B. If not provided, will default to the accountId.

accountType

String

Yes

The account type. Permitted values as follows:

"cash" - current accounts; "card" - credit cards; "savings" - savings accounts; "investment" - investment accounts; "loan" - loan accounts; "mortgage" - mortgage accounts; "pension" - pension accounts

txCode

String

Yes

The transaction code. Permitted values as follows:

"DEB" - general debit card transaction;
"CR" - general bank credit; "TFR" - general transfer to/from; ")))" - contactless purchase; "DD" - direct debit; "SO" - standing order; "BGC" - bank giro credit; "ATM" - cash withdrawal; "CHQ" - cheque; "CHG" - bank charge

For credit card transactions or if unsure for a transaction set to the empty string "".

Although we do accept more; please supply us a list of the transaction codes you'd like to use and we'll either let you know if they are supported or how you can map onto our transaction codes.

date

Date

Yes

The YYYY-MM-DD date of the transaction.

description

String

Yes

The transaction description, or statement reference. It is commonly a combination of the merchant name and merchant location.

amount

Amount

Yes

The transaction amount.

status

String

No

The transaction status, either pending or booked.

merchantCategoryCode

String

No

MCC code for the merchant’s primary activities. A maximum 4 digit string which we will left pad with 0s to make 4 digits if necessary.

cardPresent

Boolean

No

Indicates if the cardholder was present when the transaction occurred. Note that, online purchases are considered card holder not present. Only card holder present transactions are eligible for geotagging. Commonly derived from the POS entry mode: e.g. “07” is contactless chip read so card present. Do not specify or set to true if unknown/unsure; the engine uses this field as part of the estimation of a more accurate card present flag.

retentionUntilDate

Date

Yes

The YYYY-MM-DD date of when the transaction will be retained until.

meta

Object

No

Additional data for storage/pass-through.

Example

{
    "transactionId": "123456",
    "accountId": "5382358854398",
    "userId": "5382358854398",
    "accountType": "cash",
    "txCode": ")))",
    "date": "1970-01-01",
    "description": "Tesco BriLL 293484 SS",
    "amount": {
        "value": -10.99,
        "currency": "GBP"
    },
    "status": "booked",
    "merchantCategoryCode": "5411",
    "cardPresent": true,
    "retentionUntilDate": "1970-01-01",
    "meta": {
        "sourceSystem": "hex",
        "authorisedBy": "PStibbons",
        "yearOfCreation": "Year of the Luminous Lemur"
    }
}