Skip to main content

Whitelisting API

Updated:  by Brian Nyberg

Index

API information

Definitions

Whitelisted

A user with one (1) or more successful deposits.

Blacklisted

A user flagged as a potential fraudster/high risk of refund/chargeback.

Risk Score

  • 0: N/A

  • 1: N/A

  • 2: N/A

  • 3: N/A

  • 4: The user has made at least five (5) transactions

  • 5: The user has made at least three (3) transactions

  • 6: The user has made at least one (1) transaction

  • 7: The user has no successful transactions (not Black-/Whitelisted)

  • 8: N/A

  • 9: User is marked as having done Chargebacks.

  • 10: User is blacklisted. 

Lookup Email Examples

Email

Score

BL reason (if applicable)

bl.regulator@payinsight.com

10

Regulator

bl.chargeback@payinsight.com

9

Chargeback

wl.7@payinsight.com

7

Endpoint URL

Live API is available at https://whitelist.payinsight.com/. Use this URL as the base URL for all requests.

Authentication

API Authentication uses a set of pre-shared credentials, including an “Organisation ID” ({org-id}) and “API Key” ({api-key}). These credentials are unique per client, should be stored securely, and should not be shared.

To authenticate with the API, you must pass both credentials as separate headers with every request.

Method

URL            

X-ORG-ID

{org-id}

X-API-KEY

{api-key}

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

{
"type": "https://tools.ietf.org/html/rfc7235#section-3.1 ",
"title": "Unauthorized",
"status": 401,
"traceId": "00-0b0b8c8e940692bd0c6c06cc63894fe2-4805a04bc8d2c0b7-01"
}

Routes

Lookup

GET api/whitelist/lookup

Lookups are performed on a user-by-user basis; therefore, you must provide one of the following request parameters for a successful user whitelist lookup to be performed:

  1. user_email

  2. user_account

  3. user_phone_number

In addition, the following information can be passed to perform additional filters on the whitelisting rules;

  1. min_trx_count: Matches whitelist rules > value

  2. min_volume: Matches whitelist rules > value

If the psp field is not passed as a query parameter, the min_trx_count and min_volume values will be compared to the total of these values for the user, overall PSPs for which they have a record.

If a user is found, regardless of being positively whitelisted or not, then a 200 is returned.

It is not enough to only check the status code of the response; the body must be parsed to find out if the user has been whitelisted or blacklisted [see below example response]. If no user is found, the API will not return a 404, but instead return a 200 as follows: 

{
"whitelisted": false,
"blacklisted": false,
"riskScore": 7,
"blacklistReason": null
}

Request

GET api/whitelist/lookup

Parameters

Type

Params

Values

Description

QUERY

user_email

string?

Email address to check if whitelisted

QUERY

user_account

string?

User account no. to check if whitelisted. 

QUERY

user_phone_number

string?

User phone no. to check if whitelisted.

QUERY

min_trx_count

double?

Minimum transaction count (successful transactions) to accept as whitelisted.

QUERY

min_volume

double?

Minimum transaction volume (EUR) to accept as whitelisted.

QUERY

psp

string?

The Payment Service Provider (PSP) to check if the user is whitelisted on.

Validation

Parameter

Validation rules

Example

user_account

  • Masked pan validation:
    6 digits followed by 6 asterisks (*) or dots (.) followed by 4 digits

  • Card: “123456******1234” or “123456......1234” will match the same record.

  • IBAN: SE7280000810340009783242

user_phone_number

Phone numbers will be matched, ignoring ‘plus’ symbols

Input of “+123123123” OR “123123123” will match the same record. 

user_email

Valid email address

“example@mail.com”

Response

Parameters

Parameter

Type

Description

whitelisted

bool

Returns true if the user is whitelisted and false if the user is not whitelisted

blacklisted

bool

Returns true if the user is blacklisted and false if the user is not blacklisted

blacklistReason

string?

Returns the reason for the users’ blacklist

riskScore

double?

Returns the risk score of the user

error

string?

Error message returned if request is faulty

Example Response

Status 200

{
"whitelisted": true,
"blacklisted": false,
"riskScore": 0,
"blacklistReason": null
}

Status 400

{
"error": "Not enough information for whitelist request"
}

Advanced Lookup

GET api/whitelist/advancedLookup

Advanced lookups are performed on a user-by-user basis; therefore, you must provide one of the following request parameters for a successful user whitelist lookup to be performed:

  1. user_email

If a user is found, regardless of being positively whitelisted or not, then a 200 is returned.

It is not enough to only check the status code of the response; the body must be parsed to find out if the user has been whitelisted or blacklisted [see below example response]. If no user is found, the API will not return a 404, but instead return a 200 as follows: 

{
"volumes": [],
"whitelisted": false,
"blacklisted": false,
"riskScore": 6,
"blacklistReason": null
}

Request

GET api/whitelist/advancedLookup

Parameters

Type

Params

Values

Description

QUERY

user_email

string?

Email address to check if whitelisted

Validation

Parameter

Validation rules

Example

user_email

Valid email address

“example@mail.com”

Response

Parameters

Parameter

Type

Description

whitelisted

bool

Returns true if the user is whitelisted and false if the user is not whitelisted

blacklisted

bool

Returns true if the user is blacklisted and false if the user is not blacklisted

blacklistReason

string?

Returns the reason for the users’ blacklist

riskScore

double?

Returns the overall risk score of the user

volumes

arr?

Returns all whitelisted details for the user, split by userAccount

  • userAccount - string?
    Accont used

  • lastUsed - string
    When the the account was last used successfully (UTC).
    Formated as: 2024-03-11T17:00:43

  • amount - double
    Amount in {currency} that has been deposited using the account.

  • currency - string
    Currency used, at the moment, always in EUR.

  • txCount - int
    Number of deposits done successfully on the account.

  • riskScore - double
    Risk Score of the account by itself.

error

string?

Error message returned if request is faulty

Example Response

Status 200: 

{
"volumes": [
{
"userAccount": "123456******3267",
"lastUsed": "2024-03-11T17:00:43",
"amount": 2,
"txCount": 2,
"currency": "EUR",
"riskScore": 4
},
{
"userAccount": "123456******4754",
"lastUsed": "2024-03-14T02:40:35",
"amount": 100,
"txCount": 1,
"currency": "EUR",
"riskScore": 4
}
],
"whitelisted": true,
"blacklisted": false,
"riskScore": 3,
"blacklistReason": null
}

Version History

Version

Date

Author

Description

1.0

Daniel Loudon (PayInsight)

Initial draft

1.2

Nhan Doan Huu

Added risk score to whitelist lookup endpoint and added blacklist endpoints

1.3

Nhan Doan Huu

Added advanced lookup endpoint

1.4

Liam Moore (PayInsight)

Added riskScore and overallRiskScore

1.7

Duy Nguyen

Added Blacklist reason

1.9

Nhan Doan Huu

Updated the Risk Score System: doubles supported & shifted the scoring.

2.0

-

New endpoint: whitelist.payinsight.com