Public preview

Customer account evaluations Public preview

Get risk evaluations for account registration and login events using the Customer Account Evaluations API.

Availability

You can use the Account Evaluations API in a sandbox with any Radar plan. To use the API in live mode, you must have Radar Pro or a Radar Pro trial.

The Account Evaluations API provides risk intelligence for your registration and login flows to detect multi-accounting patterns and suspicious account sharing:

• No payment collection required : Evaluate risk during registration and at login, before collecting any payment information.
• Get risk scores earlier : Apply decision signals earlier in your workflow to get risk scores sooner (login or registration) than you can from a payment. This can help you make informed decisions about allowing or blocking account access where service abuse is suspected.

Multi-account abuse

The user_multi_accounting signal identifies whether a single fraudulent actor is registering multiple accounts to abuse your service.

Account sharing abuse

The user_account_sharing signal identifies whether a single user account is being used simultaneously in multiple locations.

Account evaluation lifecycle

To request an account evaluation to detect abuse:

1. On the client side, use Stripe.js to create a Radar Session that captures device metadata, then send the session token to your server.
2. Create a customer (or use an existing Customer object). Reference this customer as account _ details. customer in the evaluation request. If you can’t create one at registration time, see Entityless evaluations .
3. Request an AccountEvaluation when customers register or log in.
4. After the customer registers or logs in, report the outcome to Stripe to improve future evaluations.

The following diagram shows the high-level interactions between you (the business), Stripe and your end customer at registration time.

Create a Radar Session

Before requesting an account evaluation, you must capture device metadata from the client using Stripe.js. Pass the Radar Session token from the response to your server to use it in the account evaluation request.

Note

Radar Sessions expire shortly after creation. Create the session as close to submitting the evaluation as possible to avoid a timeout.

If session creation fails or times out

If stripe.createRadarSession() fails or times out (for example, due to an ad blocker or network error), you can still request an evaluation by passing the user’s IP address using client_details.data instead of client_details.radar_session. You can also include user_agent and referrer to improve signal quality. For referrer, use document.referrer from the client if available.

Command Line

cURL

An IP-only evaluation produces less accurate scores than a full Radar Session because it lacks device-level signals. When possible, resolve the root cause of session creation failures rather than relying on this fallback long-term. See Radar Session troubleshooting for more information.

Create an AccountEvaluation

After you create a Radar Session to capture device metadata, request an AccountEvaluation to get risk signals from Stripe. Include the registration or login activity in the same request through account_activity_details, so Stripe can evaluate the signal and record the activity in a single call.

To send registration and login events without requesting a risk score, see Customer account activity.

Registration flow

Request the user_multi_accounting signal to evaluate new user registrations. Reference an existing Customer in account_details.customer. To ensure accurate fraud detection, preserve the customer ID to use in future payment requests.

Command Line

cURL

Login flow

Request the user_account_sharing signal to evaluate user login attempts and detect account sharing patterns. Use the same customer ID that you created during registration.

Command Line

cURL

Note

user_multi_accounting and user_account_sharing evaluate synchronously. The score is returned inline in evaluated_signals on the create response, with an empty pending_signals array. You don’t need to wait for a webhook event or poll the AccountEvaluation before acting.

Risk signals

Stripe returns risk signals in the response based on the evaluation type. Use these signals to make informed decisions about allowing or blocking the action.

Score interpretation

Each signal returns a score from 0 to 100 and a corresponding risk_level that categorises the score into a qualitative band. Use the risk_level to make quick decisions, or use the raw score for fine-grained control.

Entityless evaluations

If you can’t create a Customer or Account object for your architecture at registration time, pass account_details.data.contact_email instead of account_details.customer or account_details.account.

Note

Use a Customer or Account object whenever possible. It helps Stripe make more accurate risk assessments over time.

Because Stripe has no ID to look up prior activity for an entityless request, you must include the current registration or login attempt (with its client_details) in the same request through account_activity_details. Stripe can’t fall back to a previously reported activity like it can for a Customer or Account.

Example of an entityless registration flow

Command Line

cURL

Report outcome

After you act on an account evaluation, report the outcome back to Stripe so Stripe can improve future evaluations for your account.

Create an AccountActivity with a *_decision type, referencing the AccountEvaluation you’re reporting on:

Command Line

cURL

Status values

Reporting outcomes trains Stripe’s models to better distinguish abusive from legitimate behaviour on your platform.

Test your integration

Use a Customer with one of the following test email addresses in your account evaluation requests to simulate specific risk scores in a sandbox:

Reuse the customer for payments

When creating payments, you must use the same customer ID that you used for the account evaluation. This connects registration, login and payment activity for the same customer, which improves risk assessment accuracy.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Note

The customer parameter at the time of payment must match the customer ID used when creating the AccountEvaluation.

Review results in the Dashboard

After you start sending evaluations, use the Radar overview to monitor customer account abuse. Under Customer account fraud, select Multi-accounting abuse signups to review registrations.

Select a date range, then filter evaluations by score, abuse reason, reported outcome, email address, or customer ID. The chart shows the distribution of evaluation scores over time, and the table shows the evaluations that match your filters. Select a customer ID to view the customer’s details.

Use the summary metrics to review the results:

For example, filter by higher scores to see how many evaluations you might act on. Precision shows the percentage of those evaluations that Stripe identifies as abuse, while recall shows the percentage of identified abuse that your filter captures. These metrics use the Stripe abuse labels and don’t indicate whether you reported a blocked or restricted outcome.

Check the integration health indicator for missing customer email addresses, Radar Sessions, or IP addresses. Hover over the indicator to view issues detected in the past seven days. To improve evaluation quality, provide the missing data and report the outcomes of your decisions.

Understand abuse reasons

Abuse reasons describe patterns associated with an evaluation. Use them with the score to investigate results and filter evaluations in the Dashboard. An abuse reason alone doesn’t confirm abuse, and an evaluation can have multiple reasons or no reason.