Scam Detect Schema (3.1.0)

Download OpenAPI specification:Download

Scam Detect's Position in the Overall Payment Flow

Scam Detect is intended to be used by a specific financial institution (FI), or processor offering services to a number of FIs, to assess scam risk at the level of an individual payment. This solution has been primarily designed to risk assess real-time payments inbound to and outbound from an account at the FI or processor. For outbound payments Scam Detect is positioned as the last step before the FI sends a payment through the applicable rails to the payee's FI. Any other checks done by the FI (e.g. policy checks) should be done by the FI prior to sending the payment message to Scam Detect, with only approved payments being sent to Scam Detect.

An example, for an FI working with Featurespace processing faster outbound payments via a real-time payment (RTP) system, can be found below.

sequenceDiagram
    participant P as Payer
    participant N as Payer FI/Processor
    participant A as Scam Detect
    participant R as RTP
    participant E as Payee FI/Processor
    P->>N: Payment Initiated
    N->>N: Policy Checks
    N->>A: Request to Scam Detect
    A->>N: Scam Detect Response
    N->>R: Payment Request
    R->>E: Payment Request
    E->>R: Payment Response
    R->>N: Payment Response
    R->>E: Payee FI/Processor's confirmation

For inbound payments, Scam Detect would be called when the payment request is received by the payee FIs/processor, as shown in the diagram below.

sequenceDiagram
    participant N as Payer FI/Processor
    participant R as RTP
    participant E as Payee FI/Processor
    participant A as Scam Detect
    N->>R: Payment Request
    R->>E: Payment Request
    E->>A: Request to Scam Detect
    A->>E: Scam Detect Response
    E->>R: Payment Response
    R->>E: Payee FI/Processor's confirmation

Payment Event Types

This section describes the event types that are included within Scam Detect. Scam Detect uses a single monetary event type (paymentRT) to represent different types of payments to be assessed for scam. All payment events sent to Scam Detect will receive a synchronous response.

The table below lists the two event types which are required by Scam Detect along with a description of their intended use:

Event Description
paymentRT A generic payment event (either inbound or outbound).
transactionReturn An event used to send scam or fraud confirmations to Scam Detect in order to attach "labels" back to the original payments. It is mandatory to send fraud and scam confirmations for all payments integrated with Scam Detect. For more details see the Fraud Markings Section.

Scam Detect Steering Fields

The following table explains the key attributes within Scam Detect that identify the scenario that the event is representing.

Field Name Description Example
msgStatus Identifies the status of a transaction during its flow. For Scam Detect, this is always set to New.
eventType Identifies the type of event as defined in the Event API Schema. paymentRT for a payment, transactionReturn for fraud/scam confirmations
direction In which direction are funds flowing outbound represents when an account at the FI working with Featurespace is sending money out to another account. Scam Detect supports profiling and risk assessing payments inbound to an account at the FI, by setting this attribute to inbound.
For transactionReturn events the originalTransactionDirection field should be set to the same value as for the original payment.

Parties involved in a Payment

Outbound

A number of different parties are involved in making a payment. The following table explains, from the perspective of a payment outbound from an account at the FI integrating Scam Detect, who those parties are and how that is represented in the Scam Detect Schema

Field Name: Payer Field Name: Payee Description Example
accountAgentId counterpartyAgentId A unique identifier for the FI (at a global level) at which the account is held UK: One id for Barclays, another id for NatWest etc. US: One id for JPMorgan Chase, another id for Citi etc. Where different divisions are present, multiple ids can be used (e.g. one for Chase Personal and one for Business).
accountBranchId counterpartyBranchId A unique identifier for the FI (at a more granular level than the *AgentId fields) at which the account is held UK: sort code, US: routing number
accountId counterpartyId A unique identifier for the accounts that the payment is sent from (accountId) and to (counterpartyId) N/A

Inbound

For an inbound payment (e.g. someone getting paid their salary), the accountId, accountBranchId and accountAgentId should still represent the individual registered with the FI sending the event to Scam Detect, who, in the case of an inbound payment, will be the beneficiary. Therefore, in the case of an inbound payment, the counterpartyId, counterpartyBranchId, and the counterpartyAgentId represent the payer. For more details please look at the On-us and Inbound Payments Section.

Key Scenarios

The section describes how to use the events and steering fields described in previous sections to represent specific scenarios.

Payment

Outbound Payment

Below we describe the process for sending a payment to Scam Detect and Scam Detect returning real-time response for that payment. Note that in all cases it is the FI/Processor's responsibility to use that response to make the appropriate decision to accept, hold, or decline the payment within their payment engine.

Example

  • Alice sends Bob some money for his birthday via bank transfer. Alice's bank, Bank of Alice, offers real-time payments. This outbound real-time payment (paymentRT) event undergoes all of Bank of Alice's internal policy checks. Additionally, the payment may undergo additional checks from within the institution before being sent to Scam Detect.
  • Alice's paymentRT message is sent to Scam Detect for risk assessment
  • The scam detect score is low and so when the FI combines that with their existing risk strategy they decide to approve the payment, and it is sent through the relevant rails
  • Bob receives Alice's payment in real-time (not shown below).

Note that no additional completion or declined message is required to be sent to the Scam Detect.

sequenceDiagram
    participant S as Payer FI/Processor's Payment Engine
    participant A as Scam Detect
    participant R as Real-Time Payment System (RTP)
    S->>S: Internal Policy Checks
    S->>A: Scam Detect Formatted Payment Event
    Note right of S:{ ... <br> "eventType":"paymentRT", <br> "msgStatus":"New", <br> "direction": "outbound", <br> ... }
    A->>S: Scam Detect response
    S->>R: Payment Message

Inbound Payments

Inbound payments are dealt in a similar way; when considering the same scenario above, the processing flow would look as follows:

Example

  • Alice sends Bob some money for his birthday via bank transfer. Both Alice's and Bob's banks participate in the real time payment network. This inbound real-time payment (paymentRT) is received by Bob's bank from the RTP system.
  • Bob's inbound paymentRT message is sent to Scam Detect for risk assessment
  • The scam detect score is high and, combined with existing information, leads to Bank of Bob freezing Bob's account.
sequenceDiagram
    participant R as Real-Time Payment System (RTP)
    participant S as Payee FI/Processor's Payment Engine
    participant A as Scam Detect
    R->>S: Payment Message
    S->>A: Scam Detect Formatted Payment Event
    Note right of S:{ ... <br> "eventType":"paymentRT", <br> "msgStatus":"New", <br> "direction": "inbound", <br> ... }
    A->>S: Scam Detect response

Fraud Markings

Scam confirmations are of critical importance for the correct functioning of Scam Detect analytics; this can also include confirmation of fraudulent cases (e.g. account take over) but these won't be included in the performance reporting. Scam Detect requires fraud and scam confirmations to be sent for both fraud/scams reported by customers on payments that are let through and payments that are blocked before leaving the FI/Processor and later confirmed as fraud/scam. We expect transactionReturn events to be sent at least once a day in batch and no later than 48 hours after they were reported.

An event must be sent in for each instance of confirmed fraud. The confirmedRisk attribute must be set to "true". The originalTransactionId field in the transactionReturn event must also match the transactionId field of the corresponding payment event. Similarly, the originalTransactionDirection attribute must match the direction of the original payments that the fraud report relates to. The returnType attribute should indicate whether this is reporting a Fraud or a Scam.
The returnSubType field shall be used to provide more granularity around the type of scam; we recommend using one of the following values: advance fee scam, investment scam, invoice and mandate scam, phising/smishing, purchase scam, romance scam, vishing, and other.

Example:

  • In this example, Sandy has been the victim of a scam. He then contacts Bank X to report it.
  • After the bank has confirmed this is a scam, a transactionReturn message is sent to ARIC.
sequenceDiagram
    participant S as Fraud Operations
    participant A as Scam Detect
    rect rgba(244, 244, 244)
        S->>A: Fraud
        Note right of S:{ ... <br> "eventType":"transactionReturn" , <br> "confirmedRisk": true, <br> "originalTransactionDirection": "outbound", <br> "returnType": "Scam", <br>"returnSubType": "purchase scam", <br>... }
    end

On-us or Internal Payments

This section describes how to deal with inbound payments for On-us payments.

On-us payments are where both the payer and the payee are banking with the same FI/Processor; in other words, the payment is issued and received by the same bank or credit union.

If both inbound and outbound payments are in scope for processing by Scam Detect, two different events should be sent per on-us payment for profiles to be fully updated; this is because account and counterparty are two different entity types and states are not shared between the two.

Example

  • Alice sends Bob some money for his birthday via bank transfer. Alice and Bob are banking with Bank of Alice.This outbound real-time payment (paymentRT) event undergoes all of Bank of Alice's internal policy checks. Additionally, the payment may undergo additional checks from within the institution before being sent to Scam Detect.
  • Alice's outbound paymentRT message is sent to Scam Detect for risk assessment
  • Additionally, Bob's inbound paymentRT message is also sent to Scam Detect for risk assessment
  • The scam detect score is low and so when the FI combines that with their existing risk strategy they decide to approve the payment, and the payment is settled internally
  • Bob receives Alice's payment in real-time (not shown below).

For this single payment between Bob and Alice, both the inbound and the outbound messages must be sent to ARIC Risk Hub for processing.

sequenceDiagram
    participant S as Payer FI/Processor's Payment Engine
    participant A as Scam Detect
    S->>S: Internal Policy Checks
    S->>A: Scam Detect Formatted Payment Event
    Note right of S:{ ... <br> "eventType":"paymentRT", <br> "msgStatus":"New", <br>"accountId": "AlicesAccountId", <br>"counterpartyId":"BobsAccountId", <br>"direction": "outbound", <br>  ... }
    A->>S: Scam Detect response
    S->>A: Scam Detect Formatted Payment Event
    Note right of S:{ ... <br> "eventType":"paymentRT", <br> "msgStatus":"New", <br>"accountId": "BobsAccountId", <br>"counterpartyId": "AlicesAccountId"<br> "direction": "inbound", <br> ... }
    A->>S: Scam Detect response

If the system is only processing outbound payments, only send a single event per payment for processing.

In case fraud or scam was reported, two transactionReturn events should be sent.

events

Events

/events

Request Body schema: application/json
One of
accountAgentId
required
string

Unique identifier of the financial institution (at the global level) providing the account in accountId. In the UK you would have one id for Barclays, another id for NatWest etc. In the US you would have one id for JPMorgan Chase, another id for Citi etc.

accountBranchId
required
string

Unique identifier for the branch the account is associated with, if any (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.

accountId
required
string
Examples: "591610/78956437"

Unique identification of the account involved in the event. In the UK, it would be typically be an IBAN or defined as "sortCode" + "accountNumber". In the US it would be defined as "routingNumber" + "accountNumber".

required
object (money)

Actual amount of the transaction (excluding fees)

channel
required
string
Examples: "online"

Channel through which the action was made. Permitted values are "online", "mobile", "atm", "branch", "lockbox", "mailed check", "telephone", and "call center", "other".

For the Payments solution, further free text examples can be added to fit the use case.

counterpartyBranchId
required
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, In the US this would typically be populated by a routing number.

counterpartyId
required
string

Identification of the counterparty. In the UK, it would be typically be an IBAN or defined as "sortCode" + "accountNumber". In the US it would be defined as "routingNumber" + "accountNumber".

direction
required
string
Enum: "outbound" "inbound"

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.

eventId
required
string
Examples: "8465142137"

A unique reference for the event. This reference string should be fully unqiue across the entire system. If the same eventId appears multiple times, this is interpreted as duplicate events. Please note that we advise against sequential numbering.

eventTime
required
string <date-time>
Examples: "2021-08-21T14:41:23Z"

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 ARIC. In the scenario where events are being backfilled into ARIC after an outage (to update profiles) the eventTime should reflect the time the event happened, not the time it was sent to ARIC (which may be days late).

eventType
required
string
Value: "paymentRT"
localDateTime
required
string <date-time>
Examples: "2021-10-12T10:30:00"

Local date and time the transaction takes place at the payer location. Should not have any associated timezone.

msgStatus
required
string
Examples: "New"

This attribute Identifies the status of a transaction during its flow. This should be set to "New" for a payment that needs to be risk-assessed, but other options are possible; please refer to the Schema Guide for more information.

The "Setup" value can be used to denote setting up a future-dated-payment.

schemaVersion
required
integer
Value: 1
transactionId
required
string

A unique identifier for the transaction, used to link different messages as part of the same transaction (e.g. payment request and confirmation messages) as well as to link transactions to confirmed fraud events sent through the transactionReturn event

object (money)

The account (pertaining to the account defined in the accountId) balance before the current transaction.

accountOpenDate
string <date>

The date the account was opened

accountType
string

The type of account, e.g "current", "savings", "checking" etc.

counterpartyAgentId
string

Unique identifier of the financial institution (at the global level) providing the account for the counterparty, should one exist.

deviceId
string
Examples: "FG9834YY82"

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

verificationResult
string

This is the final result of the verification, whether the customer was successful in verifiying themselves. The verificationType determines whether any specific verifications were failed or were successful (see description of verificationType). This attribute rolls that up into a single value such that if the customer was eventually successfully verified, such that they could proceed with the action, this should be set to "verificationResult": "SUCC". If the customer was trying to verify themselves and failed, such that they could not proceed with the action, you can set "verificationResult": "FAIL". Typically this wouldn't result in an event being sent to ARIC at all. However, if it's possible to feed this information into ARIC, this can be accommodated, and should be accompanied with an appropriate msgStatus value like "Verification Failed" to differentiate it from a request to score a payment that is due to be executed

object (verificationType)

This is a derived type that allows you to track multiple verifications required to perform the designated events. For example, for a payments where a customer failed in some biometric verification (e.g. fingerprint scanning) but then successfully entered their password to complete the payment, we would expect to see "verificationType": {"biometry" : "FAIL", "password": "SUCC"}.

Responses

Request samples

Content type
application/json
Example
{
  • "accountAgentId": "string",
  • "accountBranchId": "string",
  • "accountId": "591610/78956437",
  • "amount": {
    },
  • "channel": "online",
  • "counterpartyBranchId": "string",
  • "counterpartyId": "string",
  • "direction": "outbound",
  • "eventId": "8465142137",
  • "eventTime": "2021-08-21T14:41:23Z",
  • "eventType": "paymentRT",
  • "localDateTime": "2021-10-12T10:30:00",
  • "msgStatus": "New",
  • "schemaVersion": 1,
  • "transactionId": "string"
}

Response samples

Content type
application/json
{
  • "originatingEvent": { },
  • "outputTime": "2019-08-24T14:15:22Z",
  • "model": {
    },
  • "secondaryModel": {
    }
}

paymentRT Event Type

accountAgentId
required
string

Unique identifier of the financial institution (at the global level) providing the account in accountId. In the UK you would have one id for Barclays, another id for NatWest etc. In the US you would have one id for JPMorgan Chase, another id for Citi etc.

accountBranchId
required
string

Unique identifier for the branch the account is associated with, if any (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.

accountId
required
string
Examples: "591610/78956437"

Unique identification of the account involved in the event. In the UK, it would be typically be an IBAN or defined as "sortCode" + "accountNumber". In the US it would be defined as "routingNumber" + "accountNumber".

required
object (money)

Actual amount of the transaction (excluding fees)

channel
required
string
Examples: "online"

Channel through which the action was made. Permitted values are "online", "mobile", "atm", "branch", "lockbox", "mailed check", "telephone", and "call center", "other".

For the Payments solution, further free text examples can be added to fit the use case.

counterpartyBranchId
required
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, In the US this would typically be populated by a routing number.

counterpartyId
required
string

Identification of the counterparty. In the UK, it would be typically be an IBAN or defined as "sortCode" + "accountNumber". In the US it would be defined as "routingNumber" + "accountNumber".

direction
required
string
Enum: "outbound" "inbound"

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.

eventId
required
string
Examples: "8465142137"

A unique reference for the event. This reference string should be fully unqiue across the entire system. If the same eventId appears multiple times, this is interpreted as duplicate events. Please note that we advise against sequential numbering.

eventTime
required
string <date-time>
Examples: "2021-08-21T14:41:23Z"

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 ARIC. In the scenario where events are being backfilled into ARIC after an outage (to update profiles) the eventTime should reflect the time the event happened, not the time it was sent to ARIC (which may be days late).

eventType
required
string
Value: "paymentRT"
localDateTime
required
string <date-time>
Examples: "2021-10-12T10:30:00"

Local date and time the transaction takes place at the payer location. Should not have any associated timezone.

msgStatus
required
string
Examples: "New"

This attribute Identifies the status of a transaction during its flow. This should be set to "New" for a payment that needs to be risk-assessed, but other options are possible; please refer to the Schema Guide for more information.

The "Setup" value can be used to denote setting up a future-dated-payment.

schemaVersion
required
integer
Value: 1
transactionId
required
string

A unique identifier for the transaction, used to link different messages as part of the same transaction (e.g. payment request and confirmation messages) as well as to link transactions to confirmed fraud events sent through the transactionReturn event

object (money)

The account (pertaining to the account defined in the accountId) balance before the current transaction.

accountOpenDate
string <date>

The date the account was opened

accountType
string

The type of account, e.g "current", "savings", "checking" etc.

counterpartyAgentId
string

Unique identifier of the financial institution (at the global level) providing the account for the counterparty, should one exist.

deviceId
string
Examples: "FG9834YY82"

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

verificationResult
string

This is the final result of the verification, whether the customer was successful in verifiying themselves. The verificationType determines whether any specific verifications were failed or were successful (see description of verificationType). This attribute rolls that up into a single value such that if the customer was eventually successfully verified, such that they could proceed with the action, this should be set to "verificationResult": "SUCC". If the customer was trying to verify themselves and failed, such that they could not proceed with the action, you can set "verificationResult": "FAIL". Typically this wouldn't result in an event being sent to ARIC at all. However, if it's possible to feed this information into ARIC, this can be accommodated, and should be accompanied with an appropriate msgStatus value like "Verification Failed" to differentiate it from a request to score a payment that is due to be executed

object (verificationType)

This is a derived type that allows you to track multiple verifications required to perform the designated events. For example, for a payments where a customer failed in some biometric verification (e.g. fingerprint scanning) but then successfully entered their password to complete the payment, we would expect to see "verificationType": {"biometry" : "FAIL", "password": "SUCC"}.

{
  • "accountAgentId": "string",
  • "accountBalanceBefore": {
    },
  • "accountBranchId": "string",
  • "accountId": "591610/78956437",
  • "accountOpenDate": "2019-08-24",
  • "accountType": "string",
  • "amount": {
    },
  • "channel": "online",
  • "counterpartyAgentId": "string",
  • "counterpartyBranchId": "string",
  • "counterpartyId": "string",
  • "deviceId": "FG9834YY82",
  • "direction": "outbound",
  • "eventId": "8465142137",
  • "eventTime": "2021-08-21T14:41:23Z",
  • "eventType": "paymentRT",
  • "localDateTime": "2021-10-12T10:30:00",
  • "msgStatus": "New",
  • "schemaVersion": 1,
  • "transactionId": "string",
  • "verificationResult": "string",
  • "verificationType": {
    }
}

transactionReturn Event Type

accountAgentId
required
string

Unique identifier of the financial institution providing the account in accountId. It refers to the FI involved in the original transaction and not the one involved in the reporting. This field will only be typically populated for payment fraud.

accountBranchId
required
string

Unique identifier for the branch the account is associated with, if any. It refers to the branch id for the account involved in the original transaction and not the one involved in the reporting.

accountId
required
string
Examples: "CA13771612318"

Unique identification of the account involved in the event. It refers to the account involved in the original transaction and not the one involved in the reporting.

confirmedRisk
required
boolean

Set this to true if the original event is confirmed as risk (i.e. marked as a fraud or scam). This should be set to true even if a chargeback wasn't raised (e.g. if the transaction was declined before it was authorized). In cases where non-fradulent chargebacks are also sent to ARIC, set this to false so that ARIC can determine what is and isn't risk.

counterpartyBranchId
required
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. It refers to the branch id for the counterparty involved in the original transaction and not the one involved in the reporting.

counterpartyId
required
string

Identification of the counterparty, should one exist. It refers to the counterparty involved in the original transaction and not the one involved in the reporting. This field will only be typically populated for payment fraud.

eventId
required
string
Examples: "8465142137"

A unique reference for the event. This reference string should be fully unqiue across the entire system. If the same eventId appears multiple times, this is interpreted as duplicate events. Please note that we advise against sequential numbering.

eventTime
required
string <date-time>
Examples: "2021-08-21T14:41:23Z"

The date-time at which the event was reported by the customer or risk analyst (and not the time the original transaction took place - please see originalEventTime). The eventTime should be prior (or equal to) the time the event was sent to ARIC.

eventType
required
string
Value: "transactionReturn"
msgStatus
required
string
Examples: "Risk"

This attribute identifies the status of the action; e.g. set this value to "Risk" when the transactionReturn represents a fraud/scam report. Other free text values may be used (e.g. "Chargeback") that may primarily help with investigation in the UI.

required
object (money)

Amount of money, as provided in the original transaction (excluding fees).

originalEventTime
required
string <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 - see eventTime).

originalTransactionDirection
required
string
Enum: "outbound" "inbound"

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). This should only be populated for the payments solution.

originalTransactionId
required
string

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

returnType
required
string

Type of risk label. Some examples are: Scam/Fraud or 1st/2nd/3rd party.

schemaVersion
required
integer
Value: 1
counterpartyAgentId
string

Unique identifier of the financial institution providing the account for the counterparty, should one exist. It refers to the FI involved in the original transaction and not the one involved in the reporting. This field will only be typically populated for payment fraud.

deviceId
string
Examples: "FG9834YY82"

A unique identifier of the device performing the event, such as the mobile/cell phone used for a transaction. It refers to the device involved in the original transaction and not the one involved in the reporting.

returnSubType
string

The subtype of risk label. For card fraud, examples are lost and stolen / card cloned. For payments, examples are investment scam, or romance scam etc.

{
  • "accountAgentId": "string",
  • "accountBranchId": "string",
  • "accountId": "CA13771612318",
  • "confirmedRisk": true,
  • "counterpartyAgentId": "string",
  • "counterpartyBranchId": "string",
  • "counterpartyId": "string",
  • "deviceId": "FG9834YY82",
  • "eventId": "8465142137",
  • "eventTime": "2021-08-21T14:41:23Z",
  • "eventType": "transactionReturn",
  • "msgStatus": "Risk",
  • "originalAmount": {
    },
  • "originalEventTime": "2019-08-24T14:15:22Z",
  • "originalTransactionDirection": "outbound",
  • "originalTransactionId": "string",
  • "returnSubType": "string",
  • "returnType": "string",
  • "schemaVersion": 1
}