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