API Reference: /risk/bin/score
This section provides technical reference details for the endpoint, including schemas and response codes.
Endpoint Summary
Property
Value
Method
POST
Description
Calculates a risk score and decision for a card transaction based on provided data and external features.
Authentication
Required: X-API-Key HTTP Header
API Overview
Fingerprint
Transaction Scoring
Customer Management
Request Schema
Request Schema:Required Headers
Header
Type
Description
X-API-Key
string
Subscriber's secret key for authentication.
Request Schema:Request Body (application/json)
The request body is flexible, accepting both control flags and data fields at the root, with core transaction data nested under payload.
Field
Type
Required
Description
subscriber_id
integer
Yes
The ID of the subscriber making the request.
request_id
string
Yes
The unique Fingerprint/Session identifier for the request.
payload
object
Yes
Core transaction, card, and user details (see Payload Details).
gateway_event
object
No
Raw, unparsed event blob from a payment gateway. If provided, features are extracted automatically.
callback_url
string
No
URL to receive the final score/report asynchronously (triggers a webhook).
include_pdf
boolean
No
If true, a PDF report is generated and may be included in the response or sent via webhook.
skip_bin_enrichment
boolean
No
If true, disables external enrichment of card/BIN data.
user_id
string
No
User identifier (can also be provided inside payload).
Request Schema:Payload Details (Key fields expected inside the payload object):
Field
Type
Required
Description
transaction_amount
number
Yes
The monetary value of the transaction.
currency
string
Yes
The currency code (e.g., USD).
external_transaction_number
string
No
Your internal ID for this transaction (generated if missing).
bin
string
No
The first 6 digits of the card number.
last4
string
No
The last 4 digits of the card number.
user_id
string
No
The identifier for the end user (e.g., email or UUID).
session_id
string
No
The unique identifier for the current user session.
Response Codes and Payloads
Status Code
Description
Success/Error
Payload Structure
200 OK
Scoring executed successfully.
Success
{"input": {...}, "result": {...}, "source": "bin"}
400 Bad Request
Request body is missing a mandatory identifier (subscriber_id or request_id), or the data format is invalid.
Error
{"error": "Missing '...' in payload or body"}
401 Unauthorized
Missing or invalid API Key in the
X-API-Key header.
Error
{"error": "Missing API key"} or {"error": "Invalid API key"}
500 Internal Server Error
An unexpected exception occurred during processing.
Error
{"error": "..."}
Success Response Body (200)
Field
Type
Description
input
object
The final, combined set of features (including data from payload, gateway event parsing, and any cache lookups) used for the risk evaluation.
result
object
The core risk decision: Includes risk_score (0.0 to 1.0), risk_level (e.g., 'low', 'medium'), action (e.g., 'approve', 'review'), and rule_hits.
source
string
Always bin.
type
string
Always transaction.
async_job
object
Details regarding the asynchronous webhook/PDF job status, if a callback_url was provided in the request.