How-To: Submit Transaction Data for Risk Scoring
This guide provides the necessary steps to submit raw transaction data—which may include raw gateway events or standardized features—to receive an immediate risk assessment and scoring decision.
Prerequisites
To execute the scoring request successfully, you must ensure the following are in place:
-
API Key: An active API key is required for authentication. This key must be supplied via a custom HTTP header for every request.
-
Transaction Identifiers: You must provide two mandatory identifiers, which can be placed at the top level of the request or within the main payload object:
-
request_id: A unique ID correlating the request (e.g., a FingerprintJS or session ID).
-
subscriber_id: The ID for your client/organization account.
-
-
Transaction Data: The request must contain either a structured payload object with features (like BIN, amount, currency) or a raw gateway_event blob for automatic processing.
API Overview
Fingerprint
Transaction Scoring
Customer Management
Procedure
Follow these steps to successfully submit a transaction for scoring.
1. Obtain and Set the Authorization Header
Supply your service key in the X-API-Key HTTP header. If this header is missing or the key is invalid, the API will return a 401 Unauthorized response.
Header
Value
Description
X-API-Key
<YOUR_API_KEY>
The key assigned to your service account.
2. Construct the JSON Request Body
The request body must be a JSON object (application/json) containing the required identifiers and the transaction data.
The core transaction features must be provided within the payload object. The API can also accept an entire gateway_event object, from which it will automatically extract the necessary features.
Example Request Body (Using Structured Payload)
JSON
{
"subscriber_id": 12,
"request_id": "FP-REQ-1A2B3C4D5E",
"payload": {
"external_transaction_number": "SPNQ-TEST-001",
"transaction_amount": 499.99,
"currency": "USD",
"bin": "411111",
"user_id": "user@example.com",
"session_id": "DEV-SESSION-XYZ"
},
"callback_url": "https://your-webhook.com/risk-update"
}
3. Execute the POST Request
Send the constructed payload using an HTTP POST method to the full endpoint URL.
Endpoint URL: https://coral-app-2-4y6qg.ondigitalocean.app/risk/bin/score
Example using cURL:
Bash
curl -X POST \
https://coral-app-2-4y6qg.ondigitalocean.app/risk/bin/score \
-H "X-API-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"subscriber_id": 12,
"request_id": "FP-REQ-1A2B3C4D5E",
"payload": {
"transaction_amount": 499.99,
"currency": "USD",
"bin": "411111",
"user_id": "user@example.com"
}
}'
4. Handle the Scoring Response (200 OK)
The API returns a synchronous 200 OK response containing the risk decision. The response includes the final calculated result and the final input feature set used for evaluation, which may contain enriched data or merged features (such as cache-derived Fingerprint data).
Example Success Response (200 OK)
JSON
{
"input": {
"subscriber_id": 12,
"bin": "411111",
"risk_score_from_cache": 0.05
},
"result": {
"risk_score": 0.15,
"risk_level": "low",
"action": "review",
"rule_hits": [
{ "rule": "High Velocity Check", "weight": 0.10 }
]
},
"source": "bin",
"type": "transaction",
"async_job": { "status": "queued", "will_callback": true }
}