PaymentNRT

accountAddress

address

(for more information, see Appendix A: Derived Types)

Postal address the account specified in accountId is registered to.

N

N/A

accountAgentId

string

Unique identifier of the financial institution (at the global level) providing the account in accountId. accountAgentId will relate to accountBranchId, but may be less granular. For example, if accountBranchId is passed as a sort code, this code will not unqiuely identify a financial institution. accountAgentId should identify the financial institution as a whole. For example, in the UK you would have an id for Barclays, and another id for NatWest.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A

accountAgentName

string

Name of the financial institution in accountAgentId.

N

N/A

accountBalanceBefore

money

(for more information, see Appendix A: Derived Types)

The balance before the transaction of the account in accountId.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A

accountBranchAddress

address

(for more information, see Appendix A: Derived Types)

Postal address of the branch at which the account is held.

N

N/A

accountBranchId

string

Unique identifier for the branch the account is associated with at a more granular level than the accountAgentId field.

In the UK this would typically be populated by a sort code, in the US this would typically be populated by a routing number.

For examples on how the accountBranchId is defined for a region, see Appendix B: Unique Identification Definitions.

Y

N/A

accountFlag

array

Any flags on the account that aren't covered by other attributes. This is an array that can include free text values that might indicate VIP accounts, or accounts that are suspected to have been compromised.

N

N/A

accountId

string

Unique identification of the account involved in the event.

If this is an outbound transaction, accountId will be the debtor's account. If this is an inbound transaction, accountId will be the creditor's account. accountId must be consistent across different event types, and it must also be consistent over time.

For clarity, this is not an internally generated ID. accountId is a unique account number which is recognised by the payment scheme. For example, in the UK, if the sort code is 112233, and the account number is 12345678, then accountId is 11223312345678. For examples on how the accountId is defined for a region, see Appendix B: Unique Identification Definitions.

In order to ensure optimal model performance, the accountId must be consistent over time. For example, it shouldn't be represented with IBAN as well as account+sortcode.

Customers should check that the following relationships exist in their data when mapping to accountId:

• For personal banking, one accountId should be associated with a small number of customerIds

  For personal banking, one customerId should be associated with a small number of accountIds

• One accountId should belong to a single accountAgentId. For example, in a card transaction we expect accountAgentId to be an issuing financial institution, and one accountId should never be seen with two different issuers.

Y

N/A

accountIdFormat

string

Account numbers can take multiple formats, this is a free text field that describes the format of the accountId.

N

• IBAN

• UK account

• US account

accountOpenDate

date

The date the account was opened.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A

accountSubType

string

The sub type of the accountType. For example, accountType could be a current account and the subType would determine the specific product of the account type offered by the FI.

N

N/A

accountType

string

The type of account.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

• Personal

• Business

• Current

• Savings

amount

money

(for more information, see Appendix A: Derived Types)

Actual amount of the transaction in the transaction currency.

Y

N/A

approverId

array

An array containing identifiers of any approvers required to approve this action (such as making a payment or adding a payee). approverId is mainly used for commercial accounts, and identifies who approved the payment.

Do not populate this attribute if additional approval is not needed.

N

N/A

batchPaymentDetails

batchPaymentDetails

(for more information, see Appendix A: Derived Types)

Extra information that may be relevant to processing ACH transactions or other batch-type corporate payments.

Each payment in a batch payment is expected to have its own event.
Batch information is provided in batchPaymentDetails to identify specific batch payments.

N

N/A

brand

string

Indicates the group brand this payment belongs to. For use in financial institutions that operate under multiple brands, such as consumer and commercial.

N

N/A

cardId

string

A unique identifier for the card, which is a tokenised/masked PAN number and not the original PAN. For example, if populated, this must be a public card token. Unmasked and untokenised PANs are not permitted.

When using masked PANs there must be a direct 1:1 mapping back to the original PAN.

This field is expected to be populated in order to match card and non-card transactions. Alternatively, it is also expected to be populated in cases when card rails are used to make a peer-to-peer transfer.

We would expect the following relationships to be true. Customers should verify that this is the case in their own data before mapping to cardId:

• One cardId appears with only a small number of customerIds

• One cardId appears with only a small number of accountIds

N

N/A

channel

string

Channel through which the system was accessed. For example, it should be mapped to the channel through which the payment request was made. If the payer used a mobile app to make a payment into account then the channel should be set to mobile. If this information is not available, for example in case of inbound payments, channel should be set to unknown.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

Y

• online

• mobile

• atm

• branch

• lockbox

• mailed check

• post

• telephone

• agent

• unknown

checkDetails

checkDetails

(for more information, see Appendix A: Derived Types)

Extra information relevant to processing checks/cheques.

N

N/A

counterpartyAddress

address

(for more information, see Appendix A: Derived Types)

Postal address of the customer associated with counterpartyId.

N

N/A

counterpartyAgentId

string

Unique identifier of the financial institution (at the global level), providing the account for the counterparty where applicable. counterpartyAgentId relates to counterpartyBranchId, but may be less granular. For example, if counterpartyBranchId is passed as a sort code, it will not unqiuely identify a financial institution. counterpartyAgentId should identify the financial institution as a whole.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A

counterpartyAgentName

string

Name of the financial institution in counterpartyAgentId.

N

N/A

counterpartyBranchAddress

address

(for more information, see Appendix A: Derived Types)

The postal address for the branch at which the counterparty's account is held. Note that, for FI processing outbound transactions, this may only be available for "on-us" transactions, or in cases where the customer is made to supply this as part of the payment message, or using a lookup (outside of ARIC) from the counterpartyBranchId.

N

N/A

counterpartyBranchAddress

address

(for more information, see Appendix A: Derived Types)

The postal address for the branch at which the counterparty's account is held. Note that, for FI processing outbound transactions, this may only be available for "on-us" transactions, or in cases where the customer is made to supply this as part of the payment message, or using a lookup (outside of Scam Transaction Monitoring) from the counterpartyBranchId.

N

N/A

counterpartyId

string

Identification of the counterparty. If this is an outbound transaction, counterpartyId will be the creditor's account. If this is an inbound transaction, counterpartyId will be the debitor's account.

This is not an internally generated ID. This is a unique account number which is recognised by the payment scheme. For example, in the UK, if sort code is 112233 and account number is 12345678 then counterpartyId is 11223312345678.

For more information, see Appendix B: Unique Identification Definitions.

Y

N/A

counterpartyIdFormat

string

Account numbers can take multiple formats. This is a free text field that describes the format of the counterpartyId.

N

• IBAN

• UK Account

• US Account

counterpartyName

string

Name of the counterparty associated with counterpartyId. If this supplied by the customer as payee name and/or looked up if "on us".

N

N/A

counterpartyType

string

The type of account for the countepartyId.

N

• Business

• Personal

customerAddress

address

(for more information, see Appendix A: Derived Types)

Postal address the customer in customerId is registered to.

N

N/A

customerFlag

array

Field used to specify customer flags that determine treatment strategies. This is an array that can include free text values.

For retail customers this may be a vulnerability or a VIP marker. For business customers it should be related to the company.

N

N/A

customerId

string

A unique identifier for the customer. In an event with multiple customers, this must be the customer associated with the primary entity. If this is an outbound transaction, customerId will be the debtor. If this is an inbound transaction, customerId will be the creditor (which will be typically only available for "on-us" transactions).

For retail banking type use cases, this should be an individual person. However, for business banking the customerId represents the business.

customerId must be consistent across different event types. For example, the same customer should have the same customerId in paymentRT, paymentNRT, and paymentTransactionReturn. It is also essential that customerId is consistent over time.

customerId should provide a link between cards, accounts, and devices. For example, if a customer replaces a card and gets a new card number, the customerId must stay the same.

Y

N/A

customerName

string

For retail banking use cases this should be the name of the customer. For business banking use cases this would be the name of the company.

N

N/A

customerType

string

The customer type.

N

• Retail

• Commercial

declinePhase

string

Indicates which system was responsible for declining a transaction.

N

N/A

destinationCountry

string

The destination country of the funds, given as a 3 letter ISO 3166-1 Alpha-3 country code, such as GBR, AUS or CAN.

This can differ from the counterpartyAddress.country attribute, when the counterparty lives in a different country to where the funds are being sent. It will typically be the same as the counterpartyBranchAddress.country attribute, where available.

N

N/A

device

deviceDetails

(for more information, see Appendix A: Derived Types)

Details of the device used, excluding the ID.

Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A

deviceEntityId

string

Entity field for the device. This can contain the concatenation of the deviceId and the identifier of their bank (fromId/toId), or just the deviceId, depending on whether uniqueness can be guaranteed.

N

N/A

deviceId

string

A unique identifier of the device performing the event, such as the laptop/mobile phone used to log into the online banking.

If this is an outbound transaction, deviceId will be the debtor's device. If this is an inbound transaction, deviceId will be the creditor's device.

deviceId should be as consistent as possible over time. For example, a MAC address is a much better way to identify a device than an IP address. If this is used for profiling (as an entity), it is essential that deviceId satisfies several criteria. We recommend customers check their own data to ensure the following are true before using deviceId as an entity:

• One deviceId should refer to one physical device in the world

• One deviceId should be seen with a small number of customerIds, most often 1

• deviceId cannot change too often. If the median number of events per deviceId is very small, deviceId will perform poorly as an entity.

N

N/A

direction

string

The direction of the message. Valid values are outbound (for transactions being sent from the FI) or inbound (for transactions received by the FI). This should match the direction of the flow of funds.

Y

This field has validation, and must have one of the following options in the request:

• outbound

• inbound

eventTime

date-time

The date-time the event happened in the real world, defined by ISO 8601 and validated against RFC 3339.

The eventTime should be prior (or equal to) the time the event was sent to Scam Transaction Monitoring, for example the date and time when the payment is sent or received.

In the scenario where events are being backfilled into Scam Transaction Monitoring after an outage (to update profiles) the eventTime should reflect the time the event happened, not the time it was sent to Scam Transaction Monitoring.

This field must contain a timezone designator, as specified in ISO 8601, which is either Z for UTC, or an offset from UTC in +HH:MM. eventTime should capture the time at which the event occurred in the real world. For example, the eventTime for an authorisation request should be the date and time when a request message was initiatiated.

Preference should be given to transactions, rather than to internal processes. For example, suppose a batch file is produced on October 2, containing transactions from October 1. eventTime should contain date-times from October 1.

Y

N/A

finalPaymentDate

date

The last date on which the payment will be sent. This is applicable for payments scheduled to be sent in the future.

N

N/A

firstPaymentDate

date

The first date on which the payment will be sent. This is applicable for payments scheduled to be sent in the future.

N

N/A

fraudLiability

string

If known, this is a free text field that enables you to denote who would be liable to provide the refund if the transaction turns out to be fraudulent. Typical values are account, counterparty, or shared.

This field determines which side of the transaction bears the liability (rather than distinguishing between whether it is the individual or the bank).

N

N/A

initiatingPartyName

string

Name of the initiator as identified in the intiatiatingPartyId attribute where applicable.

N

N/A

initiatingPartyType

string

This attribute details how the initiating party is being used.The field can be used to either represent that it is an individual user (in commercial banking setting) or it's open banking or other entity that initiates the payment. Example values are User or Open Banking.

N

• User

• Open Banking

localDateTime

date-time

Local date and time the transaction takes place at the payer location. Unlike eventTime, this should not have any associated timezone.

Y

N/A

locationId

string

Identifier for staff location, site, or service centre. Should only populate when the event takes place in a branch, on the phone or by mail.

N

N/A

merchantCategoryCode

string

Merchant Category Code (MCC) related to the type of services or goods the merchant provides for the transaction. It is strongly recommended that this conforms to an international standard such as ISO18245.

The merchantCategoryCode should only be populated when using this event to capture alternative payment methods, where a person pays a merchant direct from their bank account without needing a card (for example QR code based payments).

N

N/A

merchantId

string

Identifier of the merchant in a transaction. This should be fully unique. It is also essential that this merchantId is consistent over time.

The merchantId should only be populated when using this event to capture alternative payment methods, where a person pays a merchant direct from their bank account without needing a card (for example, QR code based payments). To ensure its uniqueness, consider concatenation with other card processing field(s) prior to sending this field through.

N

N/A

msgStatus

string

Identifies the status of a transaction during its flow.

This should be set to New for a payment that needs to be risk-assessed by Scam Transaction Monitoring.

Failed is for when a payment failed before it got sent to the receiving FI.

Cancelled is for scheduled payments like a standing order, specifically when a customer cancelled a payment after it was risk scored by Scam Transaction Monitoring but before the next scheduled payment was executed.

Y

This field has validation, and must have one of the following options in the request:

• Failed

• Cancelled

• Returned

• New

msgStatusReason

string

The reason for the msgStatus field. This is a free text field. It should contain useful information for an investigator, should investigation be necessary. For example, if a transaction was reversed, why this happened.

N

• New Payee

• Trusted Beneficiary

msgType

string

This attribute is used to determine the message type. It can be used to denote decline stages or settlement messages. If it's set as Request, this determines it as a request to send a payment.

In example values, Pre-decline means decline before payment was sent to Scam Transaction Monitoring. Post-decline means decline after payment was sent to Scam Transaction Monitoring.

N

• Request

• Post-decline

• Pre-decline

numberOfTransactions

integer

Number of individual transactions contained in the message. This is relevant if it's related to a specific batch of payments. It would indicate a number of payments in the batch. For clarity, it is not expected that there is more than 1 payment in a single paymentRT message.

N

N/A

paymentClearingSpeed

string

This attribute determines the analytics in the payments solution and determines the speed at which the payments is expected to clear. paymentClearingSpeed is needed for payment rules as it signals what is used in payment model(s). This is related to payment clearing speed as set by the payment scheme. For example, Faster Payments would be LessThanTwoHours.

Y

This field has validation, and must have one of the following options in the request:

• LessThanTwoHours

• TwoHoursToOneDay

• MoreThanOneDay

paymentFrequency

string

If the payment is recurring, this attribute defines how often it occurs.

This field will be ignored, but should be blank, for incoming transactions.

The fields are:

• Year (YEAR)

• Month (MNTH)

• Quarterly (QURT)

• Every six months (MIAN)

• Weekly (WEEK)

• Daily (DAIL)

• Ad-hoc (ADHO)

• Event takes place several times a day (INDA)

• Fortnightly (FRTN)

N

This field has validation, and must have one of the following options in the request:

• YEAR

• MNTH

• QURT

• MIAN

• WEEK

• DAIL

• ADHO

• INDA

• FRTN

paymentGroupId

string

When the individual payment event is part of a group of payments, this identifier can be used to determine payments which belong to the same group (For example, a single order to split a payment between multiple beneficiaries).

Each individual transaction in the group should still have its own unique transactionId. If just sending individual payments, do not populate this attribute.

N

N/A

paymentMethod

string

The method being used to make the payments. Note that both Cash and Check are protected values that the solution uses to uniquely determine these types of payments. For example, in the UK, if Faster Payment payment is used, then populate this field as Faster Payment. Apart from those values this attribute should be used as a free text field that helps analysts using the UI to determine the method of payment, and to write custom rules against.

The Check value is the same as cheque. Cheque is not supported as a value for paymentMethod.

Y

• Faster Payment

• BACS

• SEPA

• CHAPS

• RTP

• ACH

• FedNow

• Check

• Wire

• Cash

• Swift

• On Us

paymentPurpose

string

Free text field that indicates the intended purpose of the payment (if available). This differs from the payment reference since customers typically enter the payment reference themselves, while with paymentPurpose they are asked to select a purpose from a range of options provided by their FI.

N

N/A

paymentReference

string

Reference for the payment added by the sender.

N

N/A

paymentSubMethod

string

Used to provide more detailed information about the paymentMethod, if required. For example if paymentMethod is Check, this attribute describes the specific type of check such as Bearer Check.

N

• Standing Order

• Future Dated Payment

• Direct Debit

• Real-time Payment

• Foreign Exchange

• Bearer Check

• Order Check

• Travellers Check

• Other

productId

string

Product ID code if applicable (this applies in re-seller use case). It needs to be the same one used by Thredd for billing and API validation purposes.

N

N/A

programManagerCode

string

Name of the program. This should be the same one used by Thredd for billing and API validation purposes. Contact Thredd if you are unsure what this attribute should be.

Y

N/A

requestExecutionDateTime

date-time

The time at which the payment is due to execute. For single immediate payments this should be close to the eventTime. However, for future dated payments this will be further in the future than the eventTime.

N

N/A

tellerId

string

The unique identifier of the individual involved in the transaction when it occurs at a Branch.

N

N/A

totalAmount

money

(for more information, see Appendix A: Derived Types)

The total amount of money moved as part of this payment request, including any additional fees.

N

N/A

transactionId

string

A unique identifier for the transaction. It can be used to link different messages as part of the same transaction (for example, payment request and confirmation messages).

transactionId is used to link transactions to confirmed fraud events sent through the paymentTransactionReturn event.

Y

N/A

transactionOnUsFlag

boolean

Indicates if the transaction is on-us, meaning when a payment's payer and payee belong to the same FI. Valid values are True or False.

N

N/A

verificationResult

string

This is the final result of the verification, indicating whether the customer was successful in verifiying themselves. The verificationType determines whether any specific verifications were failed or were successful (see description of verificationType). For example, if the customer is successfully verified and can proceed with the action, the value would be "verificationResult": "SUCC".

N

This field has validation, and must have one of the following options in the request:

• SUCC

• FAIL

verificationType

verificationType

(for more information, see Appendix A: Derived Types)

Type of the verification or authentication. The overall result of this is recorded in verificationResult.

oneTimePassword is a protected field meaning that there is a related UI functionality related to it, if it's provided. Providing this data can improve Scam Transaction Monitoring Machine Learning model performance.

N

N/A