Riskified Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with Riskified involves a structured process that begins with establishing a partnership, followed by technical setup and a first API call. Due to the customized nature of Riskified's fraud prevention solutions, direct self-service signup for API access is not typical. Instead, the process usually commences with a sales consultation to define specific needs and configure the service appropriately for your business model and transaction volume. This initial engagement ensures that the API integration aligns with your operational requirements and Riskified's service delivery model.

The primary goal of the integration is to enable your e-commerce platform to send order data to Riskified for real-time fraud analysis and receive a decision that can inform order fulfillment. This typically involves using a RESTful API to transmit transaction details and retrieve a fraud decision. Understanding the required data fields and the expected response structure is crucial for a successful implementation. Riskified provides documentation and support throughout this process, which is often tailored to the specific platform or custom integration being performed.

Here is a quick reference for the general steps involved:

Create an account and get keys

Accessing Riskified's API requires an established merchant account. Unlike many self-service APIs, Riskified's integration process begins with direct engagement with their sales and onboarding teams. This approach allows for a customized solution that addresses the specific fraud challenges and business objectives of each merchant. To initiate this process, you should contact Riskified directly through their official contact page. During the initial consultation, you will discuss your e-commerce platform, transaction volume, existing fraud prevention strategies, and specific needs for chargeback protection or policy abuse detection.

Once a service agreement is in place, Riskified's onboarding team will guide you through the account setup process. This typically involves providing necessary business information and configuring your merchant portal. As part of this setup, you will be provisioned with the essential API credentials: an API Key and an Authentication Token. These keys are unique to your merchant account and are required to authenticate all requests made to the Riskified API. The API Key identifies your account, while the Authentication Token provides secure access and should be treated as a confidential secret, similar to how Stripe API keys are handled to prevent unauthorized access.

Riskified generally provides two sets of credentials: one for a sandbox or testing environment and another for the production environment. It is critical to use the appropriate set of keys for each environment to avoid impacting live data or incurring charges during development. Best practices dictate that API keys should be securely stored and never hardcoded directly into client-side applications. Instead, they should be managed server-side, potentially using environment variables or a secure secrets management service to protect them from exposure.

Your first request

After your account is set up and you have received your API credentials, you can proceed with making your first API request. This initial request is typically sent to the sandbox environment to ensure proper integration and data formatting without affecting live transactions. Riskified's API is primarily a RESTful API, meaning you will interact with it using standard HTTP methods (POST, GET) and JSON payloads.

A common first request involves submitting an order for fraud analysis. The endpoint for submitting an order typically looks like https://sandbox.riskified.com/api/orders (the exact URL will be provided in your specific integration documentation). You will send a POST request to this endpoint with a JSON body containing detailed information about the order.

Authentication

Each request must be authenticated using the API Key and Authentication Token provided during your account setup. These are typically sent in the HTTP headers of your request. For example:

• X-Riskified-API-Key: YOUR_API_KEY
• X-Riskified-Authentication-Token: YOUR_AUTH_TOKEN

Request Body Example (JSON)

The JSON payload for an order submission will include various details crucial for fraud assessment. While the exact schema can vary slightly based on your specific configuration, a typical order submission might look like this:

{
  "order": {
    "id": "ORDER-12345",
    "status": "pending",
    "created_at": "2026-05-29T10:00:00Z",
    "currency": "USD",
    "total_price": 100.00,
    "customer": {
      "id": "CUST-67890",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    },
    "billing_address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "province": "CA",
      "zip": "90210",
      "country": "US"
    },
    "shipping_address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "province": "CA",
      "zip": "90210",
      "country": "US"
    },
    "line_items": [
      {
        "sku": "ITEM-A",
        "price": 50.00,
        "quantity": 1,
        "title": "Product A"
      },
      {
        "sku": "ITEM-B",
        "price": 55.00,
        "quantity": 1,
        "title": "Product B"
      }
    ],
    "payment_details": {
      "credit_card_bin": "411111",
      "credit_card_last4": "1111",
      "payment_gateway": "Stripe",
      "authorization_id": "auth_12345"
    },
    "custom_fields": {
      "ip_address": "192.168.1.1",
      "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36"
    }
  }
}

Response Handling

Upon receiving an order submission, Riskified will process the data and return a decision. A successful response typically includes a status code (e.g., 200 OK or 201 Created) and a JSON body containing the fraud decision, such as 'approve', 'decline', or 'challenge'. The response will also include a Riskified ID for the order, which can be used for subsequent inquiries or updates.

{
  "order": {
    "id": "ORDER-12345",
    "riskified_id": "RISK-ORDER-ABCDE",
    "decision": "approve",
    "score": 85, // Example score
    "description": "Order approved for fulfillment."
  }
}

It is essential to implement robust error handling to manage cases where the API returns an error status (e.g., 400 Bad Request, 401 Unauthorized, 500 Internal Server Error). This ensures your application can gracefully handle issues such as invalid data, authentication failures, or service disruptions. For more detailed guidance on API status codes, consult the MDN Web Docs on HTTP status codes.

Common next steps

After successfully making your first API call to Riskified, several common next steps will help you fully integrate and optimize the fraud prevention solution:

1. Integrate Decision Handling: Implement logic within your order management system to automatically act on Riskified's decisions. For 'approve' decisions, proceed with fulfillment. For 'decline', cancel the order. For 'challenge' or 'review' decisions (if applicable to your service tier), route the order for manual review by your team.
2. Webhooks Configuration: Set up webhooks to receive real-time updates from Riskified. While the initial API call provides an immediate decision, Riskified may update the decision later (e.g., after further analysis or if new information becomes available). Webhooks are crucial for keeping your system synchronized with the latest fraud decisions without continuous polling.
3. Production Deployment Planning: Begin planning the transition from the sandbox environment to production. This involves updating API endpoints and credentials, ensuring your application can handle production-level traffic, and confirming that your data submission is complete and accurate for live transactions.
4. Monitor and Optimize: Regularly monitor the performance of your integration, including API response times, decision accuracy, and the impact on your chargeback rates. Work with your Riskified account manager to review performance metrics and identify opportunities for optimization, such as adjusting data submission frequency or enriching data points.
5. Explore Additional APIs/Features: Depending on your Riskified contract, explore other available APIs or features. This might include APIs for updating order status, retrieving detailed fraud analysis reports, or integrating with other Riskified products like Account Protection or Policy Abuse detection.
6. Maintain Security Best Practices: Continuously adhere to security best practices for API key management, data transmission (e.g., ensuring HTTPS for all communications), and access control. Regularly review and rotate API keys as part of your security policy.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems to address:

• Authentication Errors (401 Unauthorized):
  • Incorrect API Key/Token: Double-check that the X-Riskified-API-Key and X-Riskified-Authentication-Token in your request headers precisely match the credentials provided for your environment (sandbox vs. production). Copy-pasting errors are frequent.
  • Missing Headers: Ensure both authentication headers are included in every request.
  • Expired Credentials: While less common for initial setup, confirm your credentials are still active. If issues persist, contact Riskified support to verify key validity.
• Bad Request Errors (400 Bad Request):
  • Invalid JSON Payload: Verify that your request body is valid JSON. Use a JSON linter or formatter to check for syntax errors (e.g., missing commas, unclosed brackets, incorrect data types for fields).
  • Missing Required Fields: The Riskified API requires specific fields in the order submission. Consult your integration documentation to ensure all mandatory fields are present and correctly formatted. Common omissions include id, total_price, currency, and various customer/address details.
  • Incorrect Data Types: Ensure numerical fields are numbers, boolean fields are true/false, and string fields are strings. For example, total_price should be a number, not a string like "100.00".
• Network or Connection Issues:
  • Incorrect Endpoint: Verify that you are sending requests to the correct Riskified API endpoint (e.g., sandbox vs. production URL).
  • Firewall/Proxy Restrictions: Ensure your network or server's firewall or proxy settings are not blocking outbound requests to Riskified's API domains.
  • SSL/TLS Issues: Confirm your HTTP client is configured to properly handle SSL/TLS certificates. Most modern HTTP clients do this automatically, but older systems might require specific configurations. Cloudflare's SSL troubleshooting guide offers general advice on common SSL issues.
• Unexpected Response Status (e.g., 500 Internal Server Error):
  • This typically indicates an issue on Riskified's side. While rare, if you encounter persistent 5xx errors, it's best to contact Riskified support with your request details, including the request ID if available, the timestamp, and the full error response.
• No Response/Timeout:
  • Network Latency: If calls are timing out, check your network connection and confirm there isn't excessive latency.
  • API Rate Limits: While less common during initial testing, be aware of potential API rate limits. If you are sending a very high volume of requests quickly, you might hit a limit, resulting in connection issues or error responses.

When seeking support, provide Riskified with as much detail as possible: the exact request you sent (excluding sensitive authentication tokens), the full response received (including headers and body), timestamps, and any relevant error messages from your application logs. This information helps their support team diagnose and resolve issues efficiently.