Stripe Radar Getting Started: Setup and First API Call (2026)

Getting started overview

Stripe Radar is a fraud detection and prevention tool integrated directly into the Stripe payment processing platform. It leverages machine learning to identify and block fraudulent transactions, helping businesses reduce chargebacks and protect revenue. For existing Stripe users, enabling Radar is a configuration step within the Stripe Dashboard. New users must first establish a Stripe account to access Radar's features. This guide outlines the steps required to get Stripe Radar operational, from account setup and API key retrieval to making a foundational API request and understanding common next steps.

Radar operates by analyzing various data points associated with a transaction, including payment information, customer behavior, and network signals, to assign a risk score. This score, combined with custom-defined rules, determines whether a transaction is allowed, blocked, or reviewed. Its deep integration with the Stripe ecosystem means that once enabled, Radar automatically screens all transactions processed through your Stripe account, whether initiated via Stripe Checkout, Payment Links, or direct API calls using Stripe's client-side SDKs. The primary goal of this guide is to facilitate a quick initial setup and verification of Radar's functionality.

The table below provides a quick reference for the initial setup process:

Create an account and get keys

Stripe Account Creation

If you do not already have a Stripe account, you must create one. Navigate to the Stripe homepage and follow the registration process. This involves providing business details, setting up two-factor authentication, and verifying your email address. Once your account is active, you will have access to the Stripe Dashboard, which serves as the central control panel for all Stripe services, including Radar.

Enabling Stripe Radar

Stripe Radar is typically enabled automatically for accounts processing payments through Stripe. To confirm its status or to manage its settings, log into your Stripe Dashboard and navigate to the Radar settings page. Here, you can review default rules, set custom rules, and configure how Radar interacts with your transactions. For example, you can choose to automatically block transactions above a certain risk score or send them for manual review.

Retrieving API Keys

API keys are essential for authenticating your application's requests to the Stripe API. Stripe uses two types of API keys:

• Publishable keys: These keys are safe to embed in your client-side code (e.g., JavaScript). They are used to create tokens and interact with Stripe's client-side components without compromising security.
• Secret keys: These keys must be kept confidential and should only be used on your server. They grant full access to your Stripe account, including the ability to create charges, manage customers, and retrieve sensitive data.

To retrieve your API keys:

1. Log in to your Stripe Dashboard.
2. Navigate to the Developers section and click on API keys.
3. You will see both your publishable key (starting with pk_test_ or pk_live_) and your secret key (starting with sk_test_ or sk_live_). For testing purposes, use the test keys. For live transactions, switch to the live keys.
4. Copy both keys. Store your secret key securely and avoid hardcoding it directly into your application's source code, especially for production environments. Environment variables or a secure configuration management system are recommended for secret keys.

Your first request

Since Stripe Radar is integrated with Stripe Payments, your first 'request' for Radar's services typically involves making a standard Stripe charge or payment intent. Radar automatically evaluates these transactions in the background. For a simple demonstration, creating a charge using one of Stripe's server-side SDKs is recommended. This example uses Python, but similar logic applies to other Stripe SDKs like Node.js or Ruby.

Before proceeding, ensure you have the appropriate Stripe SDK installed. For Python, you would install it via pip:

pip install stripe

Next, create a simple Python script to process a test charge. This script will:

1. Import the Stripe library.
2. Set your secret API key.
3. Create a Payment Intent or a Charge object.

A Payment Intent is the recommended approach for handling payment flows as it covers various scenarios, including strong customer authentication (SCA) requirements. To simulate a payment for Radar to evaluate, you need a test payment method token. Stripe provides test card numbers that can be used to generate these tokens. For example, you can use tok_visa as a placeholder token for testing purposes with a test secret key.

import stripe
import os

# Set your secret API key. Replace 'sk_test_YOUR_SECRET_KEY' with your actual test secret key.
# It's recommended to load this from an environment variable.
stripe.api_key = os.environ.get("STRIPE_SECRET_KEY", "sk_test_YOUR_SECRET_KEY_HERE")

def create_test_charge():
    try:
        # Create a PaymentIntent with test payment method data
        # For a full integration, you would create a PaymentMethod on the client-side
        # and pass its ID here or use a test token like 'tok_visa'.

        # In a real scenario, 'payment_method' would come from your client-side integration
        # For this quick test, we'll use a test token which is deprecated for new integrations
        # but useful for a quick server-side test without client-side setup.
        # For modern integrations, use PaymentMethod IDs.

        payment_intent = stripe.PaymentIntent.create(
            amount=2000, # Amount in cents, e.g., $20.00
            currency="usd",
            payment_method_types=["card"],
            description="Test charge for Radar evaluation",
            confirm=True, # Automatically confirm the PaymentIntent
            # For testing with minimal client-side setup, you can use a test source token.
            # For production, integrate with Stripe.js to get a payment_method_id.
            # This example uses a deprecated test token for simplicity in server-side-only context.
            # In a real app, you'd attach a PaymentMethod to the Customer or PaymentIntent.
            payment_method_data={
                "type": "card",
                "card": {
                    "token": "tok_visa" # Use a test token for quick server-side testing
                }
            },
            # You can also pass metadata to help Radar make decisions or for your own records.
            metadata={
                "customer_id": "cus_test_123",
                "order_id": "ord_xyz_456"
            }
        )

        print(f"PaymentIntent created: {payment_intent.id}")
        print(f"Status: {payment_intent.status}")
        print(f"Radar risk evaluation: {payment_intent.charges.data[0].outcome.risk_level if payment_intent.charges.data and payment_intent.charges.data[0].outcome else 'N/A'}")
        print(f"Radar rule: {payment_intent.charges.data[0].outcome.rule.id if payment_intent.charges.data and payment_intent.charges.data[0].outcome and payment_intent.charges.data[0].outcome.rule else 'N/A'}")

    except stripe.error.CardError as e:
        # Display error to the user
        print(f"A card error occurred: {e.user_message}")
    except stripe.error.StripeError as e:
        # Display a more generic error to the user
        print(f"An error occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    create_test_charge()

Run this script. If successful, it will output the PaymentIntent ID, its status, and importantly, the Radar risk evaluation. You can then view this transaction in your Stripe Dashboard under Payments, where Radar's decision (e.g., allowed, blocked, reviewed) will be visible along with the specific rules that triggered it. This confirms that Radar is actively screening your transactions.

Common next steps

After successfully making your first test request and observing Radar's evaluation, consider these common next steps to further integrate and optimize your fraud prevention:

1. Explore Radar Rules: Familiarize yourself with Stripe Radar's rule engine. You can define custom rules based on various attributes like IP address, card type, email domain, or transaction amount. These rules allow you to fine-tune Radar's behavior to match your business's specific risk profile. For example, you might create a rule to block transactions from specific countries or to review transactions above a certain value if they originate from an unfamiliar IP address.

2. Integrate Client-Side Elements: For a robust payment flow, integrate Stripe.js and Payment Element into your frontend. These components securely collect payment information and help Stripe's machine learning models gather more signals for fraud detection, improving Radar's accuracy. This is crucial for passing data like device fingerprints and browser information to Radar.

3. Monitor and Review: Regularly monitor transactions flagged by Radar in your Stripe Dashboard's Radar section. Transactions sent for review require manual inspection. Over time, reviewing these can help you refine your custom rules and improve Radar's effectiveness by marking transactions as fraudulent or safe, which feeds back into the machine learning model.

4. Handle Webhooks for Async Events: Set up Stripe webhooks to receive real-time notifications about events, including Radar reviews, chargebacks, and payment statuses. This allows your application to react to fraud decisions asynchronously, such as delaying order fulfillment for reviewed payments or updating order statuses after a chargeback.

5. Utilize Metadata: Pass relevant business-specific metadata with your Stripe API calls (e.g., customer_id, order_id, product_sku). This metadata is visible in the Stripe Dashboard and can be used within Radar rules, providing additional context for fraud analysis and review processes. Metadata fields are also used by Radar's machine learning models to identify patterns specific to your business.

6. Understand Radar for Fraud Teams: If your business requires more advanced fraud management capabilities, explore Stripe Radar for Fraud Teams. This enhanced version offers additional features such as advanced machine learning, shared fraud signals, and more granular control over review queues, which can be beneficial for businesses with higher transaction volumes or more complex fraud patterns.

Troubleshooting the first call

When making your first API call to Stripe (and by extension, utilizing Radar), you might encounter common issues. Here are some troubleshooting tips:

• Invalid API Key: Ensure you are using the correct API key (secret key for server-side operations, publishable key for client-side). Double-check for typos. Remember that test keys (sk_test_...) work only in test mode, and live keys (sk_live_...) work only in live mode. You can toggle between test and live mode in the Stripe Dashboard API keys settings.

• Authentication Errors: If you receive an authentication error, verify that your secret key is correctly set in your environment variables or configuration. Ensure no extra spaces or characters are included. The Stripe API expects the Authorization header to contain Bearer YOUR_SECRET_KEY for server-side requests.

• Incorrect API Version: Stripe's API evolves. While SDKs generally handle versioning, ensure your installed SDK is up to date and that your API requests conform to the version configured in your Stripe Dashboard developer settings. Mismatches can lead to unexpected behavior or deprecated API usage errors.

• Missing Required Parameters: Review the Stripe API reference for Payment Intents to confirm all required parameters (e.g., amount, currency, payment_method_data) are included and correctly formatted. Errors often provide specific details about missing or invalid parameters.

• Network Issues: Confirm your server or development environment has internet connectivity and can reach Stripe's API endpoints. Check firewall rules or proxy settings if you are operating in a restricted network environment. You can test connectivity with a simple curl https://api.stripe.com command.

• Test Mode vs. Live Mode Data: Remember that data created in test mode (e.g., test charges, test customers) is entirely separate from live mode data. You cannot view test transactions in the live dashboard or vice-versa. Always check the correct mode in your Stripe Dashboard when looking for test transactions.

• Stripe Dashboard Logs: The Stripe Dashboard's Developers > Logs section is an invaluable resource. Every API request made to your account, whether successful or failed, is logged here. You can inspect request and response bodies, status codes, and error messages, which often provide granular details about what went wrong.

• Rate Limits: While unlikely to affect a first call, be aware that Stripe enforces API rate limits to prevent abuse. If you are making many requests in quick succession during development, you might temporarily hit these limits. The API will return a 429 Too Many Requests status code in such cases.

• Stripe Status Page: If you suspect a wider issue, check the Stripe Status Page for any ongoing service disruptions or outages that might be affecting the API.