The PingOne Fraud service provides capabilities for behavioral biometrics-based and early fraud detection services.

To set this up, use:

PingOne sessions

When your client uses the PingOne Fraud Native SDKS, the PingOne Fraud service monitors each user’s PingOne session.

PingOne Fraud session data model

Property Type Required? Mutable? Description
active Boolean N/A Read-only This value is true if this is a live session, and false otherwise.
createdAt Date N/A Read-only The date the session was created (ISO-8061 format).
environment Relationship N/A Read-only The relationship to the environment.
externalIds List[String] Required Read-only The identifiers for the client sessions. Each session can be associated with multiple external sessions, and each external session can be associated with multiple sessions.
id String N/A Read-only The UUID of the PingOne session.
updatedAt Date N/A Read-only The date the session was updated (ISO-8061 format).
user Object Required Read-only The user associated with the session. Use only if the user is authenticated.
user.id String Required Read-only If user.type is PING_ONE, use PingOne’s user ID. If user.type is EXTERNAL, use a non-personal user identifier. Use only if the user is authenticated.
user.type String Required Read-only The type can be either EXTERNAL or PING_ONE (indicating the user exists in the PingOne directory). Use only if the user is authenticated.

PingOne Fraud Evaluations

Use the Fraud Evaluations interface to specify the client platform (PingOne Fraud Native SDKS), and the user actions to monitor. You’re then able to retrieve the fraud evaluations for a specific session.

Pingone Fraud Evaluations data model

Property Type Required? Mutable? Description
action String Required Immutable The context in which the API call is triggered. This can be one of the following (case-sensitive, and must be lowercase):
  • login: Use to call the API at login.

  • registration: Use to call the API at registration.

  • search_item: Use to call the API when a user is searching for an item.

  • view_item: Use to call the API when a user is viewing an item.

  • click_on_item: Use to call the API when a user is clicking on an item (to perform some action).

  • change_user_info: Use to call the API when a user is changing their information (such as, address).

  • add_user_info: Use to call the API when a user is adding new information (such as, bank information).

  • confirm_payment: Use to call the API when a user is confirming a payment (such as, a purchase or money transfer).

  • add_payment_method: Use to call the API when a user is adding a new payment method (such as, new credit card).

  • view_user_action_history: Use to call the API when a user is viewing their history (such as, purchase history).

  • other: Use this to call the API when none of the other properties apply.
client Object Required Immutable The client associated with the session.
client.platform String Required Immutable The client that triggered the flow. This can be one of the following: ANDROID, IOS, or WEB (case-sensitive, and must be uppercase).
client.version String Optional Immutable The version of the client used (such as, “4.5.0”). The maximum string length is 128 UTF-8 characters.
clientToken String Optional (see note) Immutable This token is used for Fraud BOT detection capabilities. Use the PingOne Fraud Native SDKS to fetch the token, and share the token with your application backend so it can be passed in this field. The client needs to update the backend on every token update. Note: Despite being marked as optional, it’s necessary to pass this token to the Fraud Evaluations API (whether or not your use case includes bot dectection.) The maximum string length is 4096 UTF-8 characters.
createdAt Date N/A Read-only The date the fraud evaluation was created (ISO-8061 format).
details Object N/A Read-only The details object contains extended information about the fraud evaluation. See the Details data model following this table.
environment Relationship N/A Read-only The relationship to the environment.
id String N/A Read-only The UUID of the Fraud Evaluation resource.
session Relationship Required Immutable Fraud evaluation is performed on this session. You can specify the session.Id or session.externalID. If both are passed, session.Id is used.
session.active Boolean Optional Immutable Set this value to false if you want to perform the evaluation on non-active sessions for investigation purposes. Defaults to true. Warning: This should not be used for production, real-time purposes as it will increase the latency for API calls. For this reason, use of this property in a request is protected by a quota. If the quota is exceeded, the API returns a 429 error code in the response.
session.externalId String Required Immutable The unique identifier for the session. The same identifier must be used by the PingOne Fraud Native SDKS for the session.
session.id String Optional Immutable The UUID of the session.
updatedAt Date N/A Read-only The date the session was updated (ISO-8061 format).
user Object Optional Immutable The user associated with the session. Use only if the user is authenticated.
user.id String Optional Immutable If user.type is PING_ONE, use PingOne’s user ID. If user.type is EXTERNAL, use a non-personal user identifier. Use only if the user is authenticated.
user.type String Optional Immutable The type can be either EXTERNAL or PING_ONE (indicating the user exists in the PingOne directory). Use only if the user is authenticated.
verbose Boolean Optional Immutable If set to true, returns a list of indicators in the Fraud Evaluations response.

Details data model

Property Type Required? Mutable? Description
modules Object N/A Read-only The details of the detection module that provided the fraud evaluation result (such as, suspiciousDevice or botDetection).
modules.<module-name> Object N/A Read-only The module evaluation details for the specified module. See the Module Evaluation Details data model following this table for the properties used.
policies Object N/A Read-only Contains the policies used to aggregate the output of the modules.
policy.<policy name> Object N/A Read-only The policy or policies used to aggregate the output of the modules. See the Module Evaluation Details data model following this table for the properties used.
indicators List[String] Required Immutable Contains fraudulent indicators. See the Indicators data model following this table for the properties used.

Module evaluation details data model

Property Type Required? Mutable? Description
level String N/A Read-only For modules, this is one of the following: HIGH, MEDIUM, or LOW. For policies, this is one of the following: HIGH_RISK, MEDIUM_RISK, NO_THREAT, or SAFE.
score Integer N/A Read-only The trust score of the user authentication module. This is a value greater than 0 and less than 1000. A low value (score) indicates a low level of trust for the user, while a high score indicates a high level of trust.
threshold.scores List[Integer] N/A Read-only A list of the threshold scores (such as, 120, 86, 4).
clusters List[String] N/A Read-only The detection clusters this session is associated with. This is an advanced feature, and is disabled by default.

Indicators data model

Property Type Required? Mutable? Description
name String N/A Read-only The name of the fraud indicator (such as, “user_high_risk_24h”).
value Object N/A Read-only The value of the fraud indicator.
type String Optional Read-only This can be null or TOP_INDICATOR. The TOP_INDICATOR setting means the indicator had a significant impact on the detection outcome.

PingOne Fraud Feedback

Use the Fraud Feedback interface to post feedback through labels for a specific session or sessions. Posting feedback on a regular basis is required to ensure proper functioning of the detection modules.

PingOne Fraud feedback data model

Property Type Required? Mutable? Description
createdAt Date N/A Read-only The date the session was created (ISO-8061 format).
environment Relationship N/A Read-only The relationship to the environment.
id String N/A Read-only The UUID of the Fraud Feedback resource.
updatedAt Date N/A Read-only The date the session was updated (ISO-8061 format).
labels List[Object] Required Immutable Contains the Labels objects. Each Labels object must be non-null and valid, and must contain a timestamp and at least one of the following parameters: session.id or session.externalId. See the Labels data model following this table.

Labels data model

Property Type Required? Mutable? Description
fraudFeedback Relationship N/A Read-only The relationship to the PingOne Fraud feedback resource that created or updated the Label.
fraudTypes List[String] Optional Immutable Each element must be non-null and valid. The elements can be any one of the following: ACCOUNT_TAKEOVER, NEW_ACCOUNT_FRAUD, PAYMENT, OTHER, or NONE.
session Relationship Required Immutable The relationship to the session resource associated with the Label. During PingOne Fraud feedback requests, you can specify the session.Id or session.externalID. If both are passed, session.Id is used.
session.externalId String N/A Immutable The unique identifier for the session.
session.id String N/A Immutable The UUID of the session.
updatedAt Date N/A Read-only The date the session was updated (ISO-8061 format).
confidence String Optional Immutable If specified, this value can be one of the following: VERY_HIGH, HIGH, MEDIUM, LOW, or VERY_LOW.
type String Required Immutable If specified, this value must be one of: NON_FRAUD, FRAUD, UNCERTAIN, or NONE.
timestamp Date Optional Immutable The time-stamp for the labeled event.
sources List[String] Optional Immutable If specified, each element in the list can be any one of the following: MANUAL_REVIEW, CHARGEBACK, PAYMENT_DEFAULT, END_USER_FEEDBACK, or NONE.