paymentTransactionReturn

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 uniquely 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

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

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 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.

accountId must match the one used in the original transaction.

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

authorizationIndicator

boolean

Indicates whether the original transaction was successfully authorised or not. False indicates the authorisation was not authorised, while true indicates the transaction was authorised.

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.

cardId refers to the card involved in the original transaction and not the one involved in the reporting. This may be required for Alternative Payment Methods.

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

confirmedRisk

boolean

If true, confirms the original event is a risk (marked as a fraud or scam). This should be set to true even if a chargeback or reimbursement wasn't raised (for example, if the transaction was declined before it was sent or authorised).

In cases where non-fradulent chargebacks are also sent toScam Transaction Monitoring, set this to false so that Scam Transaction Monitoring can determine what is and isn't risk.

Y

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

counterpartyBranchId

string

Unique identifier for the specific FI's branch (at a more granular level than the agentId fields) at which the counterparty's account is held. In the UK this would typically be populated by a sort code.

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

Y

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. counterpartyId must match the one used in the original transaction.

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

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.

Y

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.

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

N

N/A

eventTime

date-time

The date-time the event happened in the real world, defined by ISO 8601 and validated against RFC3339. The eventTime should be prior (or equal to) the time the event was sent to Scam Transaction Monitoring i.e. the date-time when the confirmation of fraud / scam was sent.

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.

Y

N/A

initiatingPartyId

string

ID of the initiating party. It is expected to be mandatory for commercial use cases. The initiating party is the user initiating the payment on behalf of the business (not applicable to inbound payments).

initiatingPartyId refers to the initiatingParty involved in the original transaction and not the one involved in the reporting.

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).

merchantCategoryCode refers to the MCC involved in the original transaction and not the one involved in the reporting.

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.

merchantId refers to the merchantId involved in the original transaction and not the one involved in the reporting.

N

N/A

msgStatus

string

This attribute identifies the status of the action. Set this value to Risk when there is a confirmed fraud or scam report.

Y

This field has validation, and must have Risk as the value.

msgStatusReason

string

Explains the reason for the msgStatus field. Any free text captured as part of working the case, for example, customer sentiment reported by the analyst.

N

N/A

originalAmount

money

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

Amount of money, as provided in the original transaction.

Y

N/A

originalEventTime

date-time

Indicates the time at which the original transaction took place (and not the time at which the event was reported by the customer or risk analyst).

Y

N/A

originalTransactionDirection

string

The direction of the original message. Valid values are outbound (for transactions being sent from the FI) or inbound (for transactions received by the FI).

Y

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

• inbound

• outbound

originalTransactionId

string

A unique identifier for the transaction, used to link confirmed fraud or scam events sent through the paymentTransactionReturn event back to the original transaction.

Y

N/A

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

reportedBy

string

This is the entity reporting the originating event.

N

• Customer

• Fraud Analyst

returnedAmount

money

Total amount refunded to the customer in this event. This can be different to the original transaction amount, specificied in the originalAmount field.

N

N/A

returnSubType

string

The subtype of risk label. For payments, examples are advance fee scam, investment scam, invoice and mandate scam, phising/smishing, purchase scam, romance scam, vishing.

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

N

• Account Takeover

• Counterfeit With Unassigned IIN

• Card Not Received

• Fraudulent Account Use

• Fraudulent Application

• Counterfeit with Existing Account

• Lost Card

• Miscellaneous

• Other National

• Other Private

• Stolen Card

• Card Not Present

• Account Use

• Multiple Use Fraud

• Collusion

• 1st Party Fraud

• 2nd Party Fraud

• 3rd Party Fraud

• Card Cloned
• Advance Fee Scam
• Investment Scam
• Invoice and Mandate Scam
• Phishing/Smishing
• Purchase Scam
• Romance Scam
• Vishing