Guide

Sentry Guide

Sentry performs behavioral and contextual risk analysis for transactions and account activity. It evaluates signals from devices, sessions, users, and order details to estimate the likelihood that a request represents legitimate activity.

Unlike rule-based decision engines, Sentry produces a normalized confidence score that can be interpreted directly or used as input to other systems such as the Rules engine or the Pipeline API.

What Sentry Analyzes

Sentry evaluates a range of contextual information provided in the request. Supplying richer context generally improves the accuracy of the returned confidence score.

Device

Device and session information helps identify unusual browsing environments or suspicious network behavior.

Typical fields include:

  • IP address

  • User agent

  • Accept-Language header

  • Session ID

  • Session age

The IP address is the most important signal for accurate scoring, and requests without it may have reduced effectiveness.

sessionAge should be provided in seconds.

Event

The event describes the action being evaluated. This helps Sentry understand the context in which the request occurs.

Supported event types:

  • PURCHASE

  • RECURRING_PURCHASE

For a standard checkout flow, the initial transaction should always use PURCHASE.

Event data can also include identifiers such as a transaction ID and timestamp.

Order

Order data provides economic context for the transaction.

Typical fields include:

  • Transaction amount

  • Currency

  • Affiliate or referral identifiers

  • Discount codes

  • Referrer URL

Large transactions, unusual referral sources, or abnormal discount usage may influence the resulting confidence score.

Account

Account information allows Sentry to evaluate patterns related to users or identities.

Typical fields include:

  • userId

  • username

Account-level signals help detect patterns such as:

  • Account reuse across multiple devices

  • Suspicious account creation activity

  • Identity reuse across transactions

Shopping Cart

Sentry analyzes cart composition to identify suspicious purchasing patterns.

Cart items may include:

  • itemId

  • category

  • price

  • quantity

Product categories and item combinations can provide useful signals. Certain product mixes or purchase quantities may correlate with fraudulent behavior.

Understanding requestConfidence

The Sentry response returns a single risk metric:

  • requestConfidence

This value represents Sentry’s overall confidence that the request is legitimate.

Score Characteristics

  • Range: 0.0 – 1.0

  • Higher values indicate lower fraud risk

  • Lower values indicate higher fraud risk

Example interpretation:

Confidence Value

Interpretation

0.90 – 1.00

Very high confidence (very low risk)

0.70 – 0.89

High confidence

0.40 – 0.69

Moderate confidence

0.00 – 0.39

Low confidence (elevated risk)

These ranges are illustrative. Merchants should determine thresholds based on their own risk tolerance.

Using Sentry with the Rules Engine

Sentry and Rules are independent services and can be used in multiple integration patterns.

Independent Evaluation

You may call Sentry directly and interpret requestConfidence within your own decisioning logic.

Example uses:

  • Automatically approve high-confidence requests

  • Require additional verification for moderate confidence

  • Block very low-confidence requests

Rules-Based Decisioning

Sentry outputs can also be evaluated by the Rules engine.

In this model:

  1. Sentry evaluates the request

  2. requestConfidence becomes an input signal

  3. Rules determine the final decision

Pipeline Integration

When using the Pipeline API, Sentry can be executed as one stage in a multi-service workflow.

Example pipeline:

PreCheck → Sentry → Rules

If Rules runs after Sentry in the pipeline, the Sentry results are available to the Rules engine.

Custom Inputs

Sentry supports merchant-defined contextual signals through the customInputs object.

These inputs allow merchants to include additional data points that may correlate with legitimate or fraudulent behavior.

Examples include:

  • Internal customer risk scores

  • Marketing channel identifiers

  • Loyalty program status

  • Account tenure

Values must not be null. Any non-null key/value pair can be provided.

Sentry models may incorporate these inputs when evaluating request confidence.

Best Practices for Device and Session Data

To achieve the most accurate results:

  1. Always include the IP address.This is the most important signal for Sentry analysis.

  2. Provide a stable session ID.Consistent session identifiers help identify abnormal session behavior.

  3. Include a user agent.Device fingerprints help detect suspicious device patterns.

  4. Send session age when available.Newly created sessions may behave differently than long-lived sessions.

  5. Include cart and order details when available.Product composition and transaction characteristics improve model accuracy.

Real-World Fraud Detection Examples

Sentry confidence scores may be influenced by patterns such as:

  • High-risk IP networks or anonymizing proxies

  • Device mismatches across multiple accounts

  • Rapid creation of new sessions

  • Geographic inconsistencies between account, device, and transaction

  • High-velocity account or transaction activity

These signals are evaluated collectively to produce the final confidence value.

Typical Response Time

Sentry is designed for real-time checkout evaluation.

Typical response times range from:

100 ms to 500 ms

Latency may vary depending on request complexity and the amount of contextual data provided.

Example Request and Response

The following example demonstrates a minimal Sentry request containing only device information. Device-level data — especially the IP address — is sufficient for Sentry to produce a meaningful confidence score.

Minimal Example Request 

POST /api/v1/sentry
{
  "device": {
    "ipAddress": "134.25.212.56",
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36",
    "acceptLanguage": "en-US,en;q=0.8",
    "sessionId": "80b4d4c1-3767-44da-a5c6-5c46094c4414",
    "sessionAge": 1800
  }
}

This minimal request provides:

  • Client IP address

  • Browser/device information

  • Session identifiers

  • Session age in seconds

While additional data such as account information, order details, and shopping cart contents improves scoring accuracy, Sentry can still produce useful results using device-level signals alone.

Example Response 

{
  "isSuccess": true,
  "sentryResponse": {
    "requestConfidence": 0.7888
  },
  "billing": {
    "items": [
      {
        "feeType": "SENTRY",
        "fee": {
          "currency": "USD",
          "amount": 0.0500
        },
        "completed": true
      }
    ],
    "remainingBalance": {
      "currency": "USD",
      "amount": 99.5700
    },
    "amountAuthorized": {
      "currency": "USD",
      "amount": 0.0500
    },
    "amountClosed": {
      "currency": "USD",
      "amount": 0.0500
    }
  },
  "errors": null
}

The response contains three main components:

Confidence Result

  • requestConfidence — the overall confidence that the request represents legitimate activity.

Values range from 0 to 1, where higher values indicate lower fraud risk.

Billing Information

The billing object provides invoice details for the API request, including the service fee and remaining account balance.

Errors

If the request succeeds, errors will be null. If validation or processing issues occur, the errors object will contain detailed information describing the problem.

Previous
Rules Engine Guide
Next
Identity Verification (IDVerify)