Person Risk Check

POST /compliance/person-risk-check

Risk management and fraud prevention are elementary functional areas and sub-processes for reducing risks in the processing of payments. There are two types of risk management and fraud prevention checks that we offer. They are:

Risk checks that are applied during sale order processing of products and/or services. These are risk checks that are offered as part of the ancillary services and are covered by this product and service description.
Risk checks that are applied during a payment processing for sale order is included as part of the payment services and are not covered by this product and service description.

Risk management and fraud prevention checks include:

Blacklist checks
Velocity checks
Transaction limit checks
Customer limit checks

The following section will describe the procedure and results of a person risk check and can be analogously applied to a company risk check (see API method Company Risk Check.

Call this API method and specify as much individual-related and order-related information as possible, e.g., customer name, address, list of order items, order value, etc.

Request

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

application/json

Body
Example

Bodyrequired

merchantAccnostringrequired

Merchant account number

accnoTypestringrequired

Account number type

merchantProgramCodestringrequired

Merchant program code

customerIdstringrequired

Customer ID

firstNamestringrequired

Customer's first name

lastNamestringrequired

Customer's last name

addressLine1stringrequired

First line of the address

Possible values: <= 127 characters

numberstringrequired

Address number

Possible values: <= 10 characters

postCodestringrequired

Postal code

Possible values: <= 10 characters

citystringrequired

City of residence

Possible values: <= 54 characters

countryCodestringrequired

Country code (ISO 3166-1 alpha-2 format)

Possible values: <= 2 characters

emailAddressstring<email>required

Customer's email address

dateOfBirthstring<date>required

Customer's date of birth (YYYY-MM-DD)

orderData objectrequired

Order data including items and value

orderItems object[]

List of items in the order

Array [

articleNumberstring

Article number of the item

namestring

Name of the item

groupstring

Group of the item

pricenumber<decimal>

Price of the item

amountnumber<decimal>

Amount of the item

totalPricenumber<decimal>

Total price of the item

itemTypestring

Type of the item

]

orderValuenumber<decimal>

Total value of the order

channelstring

Channel through which the order was made

VINstring

Vehicle Identification Number

paymentOptionCodestringrequired

Payment option code

requestDateTimestring<date-time>required

Date and time of the request

{
  "merchantAccno": "000000005",
  "accnoType": "00",
  "merchantProgramCode": "COMPANY123",
  "customerId": "100001073541",
  "firstName": "Jacob",
  "lastName": "Smith",
  "addressLine1": "Anystreet",
  "number": "321",
  "postCode": "12345",
  "city": "Anycity",
  "countryCode": "DE",
  "emailAddress": "user@example.com",
  "dateOfBirth": "1965-01-01",
  "orderData": {
    "orderItems": [
      {
        "articleNumber": "4M0.054.816A 05A",
        "name": "Connected Infotainment services 3 Months",
        "group": "Infotainment",
        "price": 50,
        "amount": 1,
        "totalPrice": 50,
        "itemType": "SUBSCRIPTION"
      }
    ],
    "orderValue": 50,
    "channel": "In-Car App"
  },
  "VIN": "123456",
  "paymentOptionCode": "VISA",
  "requestDateTime": "2021-02-08T17:43:19.027Z"
}

Responses

Successful response with compliance data.

application/json

Schema
Example (auto)
Example

Schema

complianceData object

archiveIdstring

ID of the compliance archive

trafficLightstring

Risk assessment result:

GREEN: Accepted
YELLOW: Over credit limit
RED: High risk

Possible values: [GREEN, YELLOW, RED]

recommendationstring

A recommendation based on the risk check result and the reason for denial.

limitinteger

Limit associated with the risk check

denialReasonstring

Reason for denial if applicable:

BASKET_LIMIT: The order value exceeds the allowed basket limit
CUSTOMER_LIMIT: The order value exceeds the allowed customer limit
BLACKLIST: An entry in a black list was found for the provided customer information (see Compliance Checks).
VELOCITY: Unusual high number of transactions in a short period of time

Possible values: [BASKET_LIMIT, CUSTOMER_LIMIT, BLACKLIST, VELOCITY]

requestDateTimestring<date-time>

Date and time of the request

responseCodestring

Response code indicating the result of the request

responseDescriptionstring

Description of the response

additionalInformation object

Contains diagnostic or tracking metadata returned with the API response. It is primarily used for support, logging and troubleshooting purposes.

requestIdstring

Unique ID for the request

{
  "complianceData": {
    "archiveId": "string",
    "trafficLight": "GREEN",
    "recommendation": "string",
    "limit": 0,
    "denialReason": "BASKET_LIMIT"
  },
  "requestDateTime": "2024-07-29T15:51:28.071Z",
  "responseCode": "string",
  "responseDescription": "string",
  "additionalInformation": {
    "requestId": "string"
  }
}

{
  "complianceData": {
    "archiveId": "4858000025016093",
    "trafficLight": "GREEN",
    "recommendation": "All checks successful",
    "limit": 100,
    "denialReason": ""
  },
  "requestDateTime": "2021-02-08T17:43:19.027Z",
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

Bad Request

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

Forbidden

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

Not Found

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}

Person Risk Check

/compliance/person-risk-check

Request​

Header Parameters

Bodyrequired

Responses​

Request

Responses