Platform Account Takeover Card Testing Payment Fraud Pricing Docs Blog
Get a Demo

Developer Docs

Everything you need to integrate Riskgrove

Start with the quickstart to get a working integration in under a day. Then explore the full API reference and SDK guides for your language of choice.

Quickstart API reference

Documentation

What's in the docs

Quickstart

Get your first scoring call running in under 30 minutes. Covers API key setup, sending your first request, and reading the response.

Read quickstart

API Reference

Complete reference for the scoring endpoint, all request fields, response schema, error codes, and rate limit headers.

View API reference

SDK Guides

Installation and usage guides for Node.js, Python, Go, Ruby, PHP, and Java client libraries. Includes auth, error handling, and retry logic.

View SDKs

Webhooks

Receive asynchronous notifications for score events, review escalations, chargeback feedback, and account status changes.

Webhook reference

Signal Dictionary

Every signal name returned in the signals[] array explained: what it measures, value range, and how it contributes to the composite score.

View signals

Changelog

API version history, breaking changes, signal additions, and deprecation notices. Subscribe via RSS or check here before upgrading your SDK.

View changelog

Quickstart

Your first scoring call in 4 steps

Create an account and get your API key

Sign up at riskgrove.com. Your API key is on the Settings page. All API calls use Bearer token authentication.

Authorization: Bearer sk_live_...

Install the SDK for your language

Choose the SDK that matches your application stack. All SDKs wrap the same REST API.

# Node.js
npm install @riskgrove/node

# Python
pip install riskgrove

# Go
go get github.com/riskgrove/go-sdk

Send your first scoring request

Call the scoring endpoint before your authorization request. Minimum required fields: transaction_id, amount_cents, currency, card_fingerprint, device_id.

curl -X POST https://api.riskgrove.com/v1/score \
  -H "Authorization: Bearer $RGV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_test_001",
    "amount_cents": 8500,
    "currency": "USD",
    "card_fingerprint": "fp_test_abc",
    "device_id": "dv_test_xyz"
  }'

Act on the recommendation

Read the recommendation field in the response. Approve, review, or block based on your business policy. The signals array shows the top contributing factors.

{
  "score": 0.07,
  "recommendation": "approve",
  "signals": [],
  "latency_ms": 36,
  "request_id": "rq_..."
}

API Reference

Scoring endpoint overview

Base URL: https://api.riskgrove.com/v1

POST /score

Submit a transaction for fraud risk scoring. Returns a composite risk score, recommendation, and contributing signals within 40ms median latency.

Request fields (required)
Field Type Description
transaction_id string Your unique transaction identifier
amount_cents integer Transaction amount in smallest currency unit
currency string ISO 4217 currency code (e.g. USD)
card_fingerprint string Stable card identifier (not PAN, use gateway token)
device_id string Device fingerprint from Riskgrove client JS or mobile SDK

Changelog

Recent API changes

v1.2

Behavioral biometric signals added

Added session_behavior_score and typing_rhythm_delta signals to the ATO module. Requires Riskgrove client JS v1.2+ for data collection. Backward compatible.

v1.1

BIN cluster concentration signal

Added bin_device_cluster_score to card testing module. Evaluates BIN range concentration per device fingerprint across 1h, 6h, and 24h windows.

v1.0

Initial API release

Public API v1.0 with ATO detection module, card testing velocity module, and payment fraud velocity module. REST + Node.js, Python SDKs available at launch.