Whitelisting Engine v2

Updated: 01 Apr 2026

Index

API information

This API provides risk scoring and whitelist/blacklist evaluation for users and transactions.

Definitions

Scope

The document occasionally references scopes, which relate to entity-level data within the PayInsight system. Items that are:

Scoped: Applies only to the requesting entity
Not scoped: Derived from cross-entity data

Whitelisted

A user with one or more successful deposits across any entity (i.e., not limited to a specific entity scope).

Blacklisted

A user is only blacklisted within the scope of the entity making the API call. This means that if Entity 1 has flagged User A as blacklisted due to fraud, Entity 2 will still consider User A as whitelisted. However, the response will indicate that the user has been flagged by one or more other entities for potential fraudulent activity.

Risk Score

The risk score is represented as a four-digit code (A B C D), where each digit corresponds to a specific risk factor category. Each position in the code provides insight into the user’s profile across different dimensions of risk.

A - Risk Source
Indicates the origin and severity of risk signals associated with the user:
0: Internally blacklisted
1: Normal
2: Ghost deposits externally
3: Chargebacks externally
4: Blacklisted externally
5: Ghost deposits internally
6: Chargebacks internally

B - Deposit Count (Successful)
Represents the total number of successful deposits made by the user across all entities:
0: 0 deposits
1: 1 deposit
2: 2 deposits
3: 3 deposits
4: 4 deposits
5: 5 or more deposits

C - KYC Level
Reflects the user’s level of identity verification:
0: No KYC
1: Fully KYC verified externally
2: ID verified internally
3: Fully verified internally

D - Deposit Volume
Indicates the user’s total successful deposit volume:
0: Less than €2,000 in deposits
1: Minimum €2,000 in deposits

Lookup Email Examples

To test the API, use the STG endpoint. The emails below allow you to try different API responses.

When using ENTITY_1 credentials, the following example email addresses will return the corresponding risk scores as outlined below:

Email	Expected Score
am-6-6cd9@example.com	4500
0m-8-45d5@example.com	1320
rm-9-dd46@example.com	4411

When using ENTITY_116:

Email	Expected Score
am-6-6cd9@example.com	0500
0m-8-45d5@example.com	1320
rm-9-dd46@example.com	0411

Endpoint URL

STG API: https://stg-fraud-api.payinsight.com
Live API: https://fraud-api.payinsight.com

Use the applicable URL as the base URL for all requests.

Authentication

API authentication uses an API key ({api-key}). This credential is unique per entity, can be generated via the back office (BO), and must be stored securely and not shared. The API key must be included in the request headers for all authenticated calls.

Header	Value
X-API-KEY	{api-key}

Example Request Headers:

{ 
"X-API-KEY": "YOUR_API_KEY", 
"Content-Type": "application/json"
}

An unauthenticated request will receive a 401 response with a body containing the following content:

{
"status": 401,
"error": "Unauthorized",
"detail": "Invalid API Key",
"traceId": "0HNKF9FN6KJBT:00000001"
}

Rate Limits

Rate limit

The API does not enforce fixed per-client rate limits. However, request handling is subject to overall system capacity and dynamic scaling constraints.

The service can handle a high level of traffic and concurrent requests. During traffic spikes, requests may be delayed, throttled or rejected to maintain stability.

Clients should implement basic throttling, timeouts and retry logic with exponential backoff.

Timeout & Execution Model

The endpoint operates synchronously, returning the full result within a single 200 response. Polling or asynchronous handling is not required.

For client integrations, we recommend setting a timeout of around 5 seconds, as typical response times are currently in the 2–3 second range.

Requests are subject to a maximum server-side timeout of 300s.

IP Whitelisting

IP whitelisting is not currently required to access the API.

Versioning

Endpoints currently use path-based versioning (e.g. /v2). At this time, there is no formal versioning strategy beyond this convention.

Whitelist Check

POST /api/v2/whitelist-check

Runs risk and whitelist scoring for a customer and the associated transaction. The response includes a composite risk score, an indication of whether the customer is considered whitelisted or blacklisted for the specific check, and a transaction reference for the stored result.

It is not sufficient to rely solely on the response status code. The response body must be parsed to determine whether the user is whitelisted or blacklisted (see example response below). If no user is found, the API will return a 200 response rather than a 404, as shown below:

{
"score": "1000",
"piTransaction": "08de8f4d-75f2-45d0-8cd5-bd0848bb3488",
"whitelisted": false,
"blacklisted": false,
"blacklistReason": "",
"blacklistSubReason": "",
"blacklistComment": "",
"scoreDetails": {
"aScore": 1,
"aDescription": "Normal",
"bScore": 0,
"bDescription": "0 Deposits",
"cScore": 0,
"cDescription": "No KYC",
"dScore": 0,
"dDescription": "< €2000 EUR Successful Deposits"
}
}

Request

Body

Top-level fields are required unless stated otherwise. Fields within the user & tx objects are optional.

Field	Type	Required	Description
`email`	string	YES	Customer email (must be a valid email address).
`merchantId`	string	YES	Your merchant identifier.
`txRefId`	string	YES	Your reference for this transaction or check.
`user`	object	NO	Extra user attributes (see below).
`txDetails`	object	NO	Extra transaction attributes (see below).

user object (all fields optional)

Field	Type	Description
`userId`	string	Unique identifier for the user within your system.
`sex`	string	MALE\|FEMALE\|UNKNOWN
`firstName`	string	User’s first name. Example: “Jane”.
`lastName`	string	User’s last name. Example: “Doe”.
`dob`	string	User’s date of birth. Must be in the format “YYYY-MM-DD”.
`street`	string	User’s address, including street name and number.
`city`	string	User’s city of residence.
`state`	string	User’s state, region, or province.
`country`	string	User’s country of residence (preferably in ISO 3166-1 alpha-3 format, e.g. “SWE”).
`zip`	string	User’s postal or ZIP code.
`phone`	string	Must include country code. Accepted formats include “46707010277” or “+46707010277”
`ssn`	string	User’s SSN number.

txDetails object (all fields optional)

Field	Type
`maskedPan`	string	Masked card number. Accepted formats include “555535******1234” or “555535......1234”, where the middle digits are obscured.
`bin`	string	BIN of the card. Example: “555535”.
`userAgent`	string	Represents the client’s user agent information. It is recommended to use the User-Agent Client Hints format (e.g. structured values such as platform, browser, and device details). Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"

Field

Type

maskedPan

string

Masked card number. Accepted formats include “555535******1234” or “555535......1234”, where the middle digits are obscured.

bin

string

BIN of the card. Example: “555535”.

userAgent

string

Represents the client’s user agent information. It is recommended to use the User-Agent Client Hints format (e.g. structured values such as platform, browser, and device details).

Example:
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"

Success response: 200

Field	Type	Description	Scoped to entity?
`score`	string	Four-character composite score.	Scoped
`piTransaction`	string (UUID)	Identifier for this scored check in the system.	N/A
`whitelisted`	boolean	Whether the customer is treated as whitelisted for this result.	Scoped
`blacklisted`	boolean	Whether the customer is treated as blacklisted for this result.	Scoped
`blacklistReason`	string	Reason when a blacklist applies.	Not scoped, but entity priority
`blacklistSubReason`	string	Sub-reason when applicable.	Not scoped, but entity priority
`blacklistComment`	string	Comment when applicable.	Scoped
`scoreDetails`	object	Breakdown of the score (see below).	Partly scoped

scoreDetails object

Field	Type	Description	Scoped to entity?
`aScore`	number	First score component.	Scoped
`aDescription`	string	Description for component A.
`bScore`	number	Second score component.	Not scoped
`bDescription`	string	Description for component B.
`cScore`	number	Third score component.	Scoped
`cDescription`	string	Description for component C.
`dScore`	number	Fourth score component.	Not scoped
`dDescription`	string	Description for component D.

Example Request

{
"email": "rm-9-dd46@example.com",
"merchantId": "test-merchant-1",
"txRefId": "test-ref-2",
"user": {
"userId": "user_123",
"firstName": "Jane",
"lastName": "Doe",
"sex": "FEMALE",
"street": "Storgatan 1",
"city": "Stockholm",
"state": "Stockholm",
"zip": "17732",
"country": "SWE",
"dob": "1981-01-01",
"phone": "+46733123123",
"ssn": "YYYYMMDDXXXX"
},
"txDetails": {
"maskedPan": "555535******1234",
"bin" : "123456",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"
}
}

Example Response

Status 200

{
"score": "4500",
"piTransaction": "08de8f4b-ef0c-47d9-8d37-56d99a167bf7",
"whitelisted": true,
"blacklisted": false,
"blacklistReason": "FRAUD",
"blacklistSubReason": "MULTI_ACCOUNTING",
"blacklistComment": "Seeded test data – scenario 70",
"scoreDetails": {
"aScore": 4,
"aDescription": "Blacklisted externally",
"bScore": 5,
"bDescription": "5+ Deposits",
"cScore": 0,
"cDescription": "No KYC",
"dScore": 0,
"dDescription": "< €2000 EUR Successful Deposits"
}
}

(A user may be considered whitelisted for the current entity while still having external blacklist signals.)

Errors

Error responses are JSON and include status (HTTP code), error, detail, and traceId.

401: API key missing or not valid.
400: Request could not be accepted (e.g. invalid email, invalid reason codes, validation rules not met).
5xx: Server-side problem; use traceId when reporting the issue.

Change log

Date	Event
01 Apr 2026	Initial Version