Endpoint
POST https://requiems.xyz/v1/systems/transaction/risk
Score Transaction Risk
Score a transaction for fraud risk by cross-checking the card BIN country against IP geolocation and billing country. Detects VPN, proxy, and TOR use.
Parameters
| Name |
Type |
Required |
Location |
Description |
card_bin |
string |
yes |
body |
Card BIN (first 6–8 digits) to look up card issuing country. |
ip_address |
string |
yes |
body |
Customer's IPv4 or IPv6 address. Must be a valid IP. |
billing_country |
string |
no |
body |
ISO 3166-1 alpha-2 billing country code. When provided, country mismatch checks are more precise. |
amount_usd |
number |
no |
body |
Transaction amount in USD. High-value transactions via VPN incur an additional risk score boost. |
Request Example
{
"card_bin": "424242",
"ip_address": "92.168.1.1",
"billing_country": "DE",
"amount_usd": 250.00
}
Response Example
{
"data": {
"risk_score": 0.55,
"is_safe": false,
"flags": ["ip_country_mismatch", "country_mismatch", "vpn_detected"],
"signals": {
"ip_country": "NL",
"billing_country": "DE",
"bin_country": "US",
"vpn_detected": true,
"is_proxy": false,
"is_tor": false,
"country_mismatch": true
}
},
"metadata": {
"timestamp": "2026-01-01T00:00:00Z"
}
}
Response Fields
| Field |
Type |
Description |
risk_score |
number |
Transaction risk score from 0.0 to 1.0 |
is_safe |
boolean |
True when score is below 0.5 and no TOR or proxy detected |
flags |
array |
Triggered flags. Possible values: ip_country_mismatch, bin_country_mismatch, country_mismatch, vpn_detected, proxy_detected, tor_detected, high_value_vpn |
signals.ip_country |
string |
Country code resolved from the IP address |
signals.billing_country |
string |
Billing country provided in the request, or null if omitted |
signals.bin_country |
string |
Country of the card issuer resolved from the BIN |
signals.country_mismatch |
boolean |
True when any country comparison produced a mismatch |
Errors
undefined 422 — ip_address is not a valid IPv4 or IPv6 address, or card_bin is missingundefined 401 — Missing or invalid API key
1---2name: payments-intelligence-post-risk3description: Score a transaction for fraud risk by cross-checking the card BIN country against IP geolocation and billing country. Detects VPN, proxy, and TOR use.4---5
6## Endpoint
7
8**POST https://requiems.xyz/v1/systems/transaction/risk**
9
10## Score Transaction Risk
11
12Score a transaction for fraud risk by cross-checking the card BIN country against IP geolocation and billing country. Detects VPN, proxy, and TOR use.
13
14## Parameters
15
16| Name | Type | Required | Location | Description |
17| ---- | ---- | -------- | -------- | ----------- |
18| `card_bin` | string | yes | body | Card BIN (first 6–8 digits) to look up card issuing country. |
19| `ip_address` | string | yes | body | Customer's IPv4 or IPv6 address. Must be a valid IP. |
20| `billing_country` | string | no | body | ISO 3166-1 alpha-2 billing country code. When provided, country mismatch checks are more precise. |
21| `amount_usd` | number | no | body | Transaction amount in USD. High-value transactions via VPN incur an additional risk score boost. |
22
23## Request Example
24
25```json
26{
27 "card_bin": "424242",
28 "ip_address": "92.168.1.1",
29 "billing_country": "DE",
30 "amount_usd": 250.00
31}
32```
33
34## Response Example
35
36```json
37{
38 "data": {
39 "risk_score": 0.55,
40 "is_safe": false,
41 "flags": ["ip_country_mismatch", "country_mismatch", "vpn_detected"],
42 "signals": {
43 "ip_country": "NL",
44 "billing_country": "DE",
45 "bin_country": "US",
46 "vpn_detected": true,
47 "is_proxy": false,
48 "is_tor": false,
49 "country_mismatch": true
50 }
51 },
52 "metadata": {
53 "timestamp": "2026-01-01T00:00:00Z"
54 }
55}
56```
57
58## Response Fields
59
60| Field | Type | Description |
61| ----- | ---- | ----------- |
62| `risk_score` | number | Transaction risk score from 0.0 to 1.0 |
63| `is_safe` | boolean | True when score is below 0.5 and no TOR or proxy detected |
64| `flags` | array<string> | Triggered flags. Possible values: ip_country_mismatch, bin_country_mismatch, country_mismatch, vpn_detected, proxy_detected, tor_detected, high_value_vpn |
65| `signals.ip_country` | string | Country code resolved from the IP address |
66| `signals.billing_country` | string | Billing country provided in the request, or null if omitted |
67| `signals.bin_country` | string | Country of the card issuer resolved from the BIN |
68| `signals.country_mismatch` | boolean | True when any country comparison produced a mismatch |
69
70## Errors
71
72- `undefined` **422** — ip_address is not a valid IPv4 or IPv6 address, or card_bin is missing
73- `undefined` **401** — Missing or invalid API key
gabrielmoreira