Overview

Stripe has released an API update to its Radar payment risk assessment system that restructures how payment evaluation information is exposed to developers. The Payment Evaluation object has been redesigned to provide more granular risk signal data while improving the API's extensibility for future machine learning models.

What Changed

The key structural changes include:

• Removed: The insights hash has been completely removed from the Payment Evaluation object
• Added: A new signals hash containing multiple risk evaluations:
  • fraudulent_payment: Likelihood of fraudulent disputes or early fraud warnings (available by default)
  • fraudulent_dispute: Likelihood of fraudulent dispute claims (public preview)
  • early_fraud_warning: Likelihood of early fraud warnings (public preview)
• Promoted: The recommended_action property moved from nested in insights to the top level
• Enhanced precision: Score values now support 2 decimal places (changed from integers to floats)

Each signal within the signals hash contains:

• evaluated_at: Timestamp of the evaluation
• risk_level: Assessment level (normal, elevated, or highest)
• score: Numerical score with up to 2 decimal places

Required Migration Steps

This is a breaking change. If your integration currently accesses the insights hash, you must update your code:

• Replace insights.fraudulent_dispute.risk_score with signals.fraudulent_payment.score
• Replace insights.fraudulent_dispute.recommended_action with recommended_action
• Remove all references to the deprecated insights hash

Upgrade Process

To adopt this change, you'll need to:

1. View your current API version in Stripe Workbench
2. Upgrade to API version 2026-03-25.dahlia (or later)
3. Update your SDKs (Ruby, Python, PHP, Java, Node.js, Go, .NET) to the latest version compatible with the new API version
4. Update webhook endpoint configurations to use the new API version
5. Test thoroughly in Stripe's test environment
6. Perform the upgrade in Workbench (with 72-hour rollback capability available)

Learn more about Stripe API versioning and upgrades.