Payments Intelligence System

Reduce failed payments and detect risky transactions

Validate BINs, IBANs, and SWIFT codes while cross-checking IP and billing country before the payment hits your processor.

Get API key

Engine

Payments Intelligence Engine

Validate financial data and assess transaction risk in one call. BIN, IBAN, SWIFT, and IP signals composed automatically.

POST /v1/systems/payment/validate

Request

{
  "card_bin": "424242",
  "iban": "DE89370400440532013000",
  "ip_address": "92.168.1.1",
  "billing_country": "DE"
}

Response

{
  "valid": true,
  "risk_score": 0.14,
  "country_mismatch": false,
  "bank": {
    "name": "Deutsche Bank",
    "country": "DE",
    "brand": "Visa"
  },
  "signals": {
    "bin_valid": true,
    "iban_valid": true,
    "ip_country": "DE",
    "billing_country": "DE"
  }
}

Failed payments cost SaaS and fintech products revenue and user trust. The Payments Intelligence Engine validates financial data and assesses transaction risk in a single call, combining finance and networking signals without requiring you to orchestrate them.

API Reference

Base URL: https://requiems.xyz

Overview

Use Cases

Validate card BIN, IBAN, and SWIFT data before submitting to a payment processor
Flag transactions where billing country mismatches IP geolocation
Verify financial identifiers during fintech onboarding flows
Reduce payment decline rates by pre-validating data before submission
Detect VPN and TOR use on high-value transactions

Features

BIN lookup with card scheme, type, level, and issuer details

IBAN format and checksum validation with bank code extraction

SWIFT/BIC code verification with institution and country

Cross-field consistency check flags mismatches between BIN, IBAN, and SWIFT countries

IP geolocation with VPN, proxy, and TOR detection for transaction risk

Risk score from 0.0 to 1.0 with named flags

API Endpoints

Validate Payment

Validate and cross-check BIN, IBAN, and SWIFT identifiers in one call. Returns per-field results and a consistency check that flags country and bank mismatches.

POST

https://requiems.xyz/v1/systems/payment/validate

Parameters

Name	Type	Required	Description
bin	`string`	Optional	Card BIN (first 6–8 digits). At least one of bin, iban, or swift is required.
iban	`string`	Optional	IBAN string to validate. Checksum and format are verified.
swift	`string`	Optional	SWIFT/BIC code to look up institution and country.

Try it out

Live Demo

Request

bin (string)

Card BIN (first 6–8 digits). At least one of bin, iban, or swift is required.

iban (string)

IBAN string to validate. Checksum and format are verified.

swift (string)

SWIFT/BIC code to look up institution and country.

Response Fields

Field	Type	Description
bin	`object`	BIN result. Null when bin was not provided. Contains valid, scheme, card_type, card_level, country_code, issuer, prepaid, luhn_prefix_valid.
iban	`object`	IBAN result. Null when iban was not provided. Contains valid, country_code, bank_code, account_number.
swift	`object`	SWIFT result. Null when swift was not provided. Contains valid, institution, country, branch.
consistency.ok	`boolean`	True when no cross-field mismatches were detected
consistency.flags	`array<string>`	Mismatch flags. Possible values: country_mismatch_bin_iban, country_mismatch_bin_swift, country_mismatch_iban_swift, bank_mismatch_iban_swift

Code Examples

curl -X POST https://requiems.xyz/v1/systems/payment/validate \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bin": "424242",
    "iban": "DE89370400440532013000",
    "swift": "DEUTDEDB"
  }'

import requests

response = requests.post(
    "https://requiems.xyz/v1/systems/payment/validate",
    headers={"requiems-api-key": "YOUR_API_KEY"},
    json={"bin": "424242", "iban": "DE89370400440532013000", "swift": "DEUTDEDB"}
)
data = response.json()["data"]

if not data["consistency"]["ok"]:
    print("Consistency flags:", data["consistency"]["flags"])
else:
    print("All identifiers consistent")

const { data } = await fetch('https://requiems.xyz/v1/systems/payment/validate', {
  method: 'POST',
  headers: { 'requiems-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ bin: '424242', iban: 'DE89370400440532013000', swift: 'DEUTDEDB' })
}).then(r => r.json());

if (!data.consistency.ok) {
  console.warn('Mismatch detected:', data.consistency.flags);
}

require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/systems/payment/validate')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { bin: '424242', iban: 'DE89370400440532013000', swift: 'DEUTDEDB' }.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(request) }
data = JSON.parse(response.body)['data']
puts data['consistency']['ok'] ? 'Consistent' : data['consistency']['flags'].inspect

Error Responses

422

validation_failed

All of bin, iban, and swift were omitted. At least one is required.

401

unauthorized

Missing or invalid API key

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.

POST

https://requiems.xyz/v1/systems/transaction/risk

Parameters

Name	Type	Required	Description
card_bin	`string`	Required	Card BIN (first 6–8 digits) to look up card issuing country.
ip_address	`string`	Required	Customer's IPv4 or IPv6 address. Must be a valid IP.
billing_country	`string`	Optional	ISO 3166-1 alpha-2 billing country code. When provided, country mismatch checks are more precise.
amount_usd	`number`	Optional	Transaction amount in USD. High-value transactions via VPN incur an additional risk score boost.

Try it out

Live Demo

Request

card_bin * (string)

Card BIN (first 6–8 digits) to look up card issuing country.

ip_address * (string)

Customer's IPv4 or IPv6 address. Must be a valid IP.

billing_country (string)

ISO 3166-1 alpha-2 billing country code. When provided, country mismatch checks are more precise.

amount_usd (number)

Transaction amount in USD. High-value transactions via VPN incur an additional risk score boost.

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<string>`	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

Code Examples

curl -X POST https://requiems.xyz/v1/systems/transaction/risk \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "card_bin": "424242",
    "ip_address": "92.168.1.1",
    "billing_country": "DE",
    "amount_usd": 250.00
  }'

import requests

response = requests.post(
    "https://requiems.xyz/v1/systems/transaction/risk",
    headers={"requiems-api-key": "YOUR_API_KEY"},
    json={
        "card_bin": "424242",
        "ip_address": "92.168.1.1",
        "billing_country": "DE",
        "amount_usd": 250.00
    }
)
data = response.json()["data"]
print(f"risk_score={data['risk_score']}, is_safe={data['is_safe']}")
if data["flags"]:
    print("Flags:", data["flags"])

const { data } = await fetch('https://requiems.xyz/v1/systems/transaction/risk', {
  method: 'POST',
  headers: { 'requiems-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    card_bin: '424242',
    ip_address: '92.168.1.1',
    billing_country: 'DE',
    amount_usd: 250.00
  })
}).then(r => r.json());

console.log(data.risk_score, data.is_safe, data.flags);

Error Responses

422

validation_failed

ip_address is not a valid IPv4 or IPv6 address, or card_bin is missing

401

unauthorized

Missing or invalid API key

Frequently Asked Questions

All-in-one backend for SaaS products

Authentication, validation, fraud detection, payments intelligence, and global data, delivered through one unified API.

Get API key Browse underlying APIs

No results found

No results found

Reduce failed payments and detect risky transactions

Payments Intelligence Engine

API Reference

Overview

Use Cases

Features

API Endpoints

Validate Payment

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Score Transaction Risk

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Frequently Asked Questions

All-in-one backend for SaaS products