Introduction

Checking customer data for any existing adverse criteria.

This request is only available if module “protect” has been ordered.
The customer check is carried out to determine the risk of non-payment of demands against customers. With the help of consumer information (adverse criteria) a score value is determined which you can use to assess the creditworthiness of the customers, get a realistic picture of the risk of non-payment and offer the corresponding types of payment.

For best results please provide “streetname” and “streetnumber” in separate fields. If not possible you can use “street” only.

For “consumerscore” first-/last name is obviously mandatory. Parameter “gender” and “birthday” are mandatory for Boniversum and optional for Arvato but recommended for best results.

 Valid combinations (Arvato, Boniversum, SCHUFA)

addresschecktype consumerscoretype businessrelation Remarks Available countries
NO, BA, PE IH, IA, IB, IF b2c (optional) Arvato Infoscore Services DE
PB CE b2c (optional) Boniversum Services DE
BS SFS b2c (mandatory) SCHUFA Services DE
BS SFS, SFM b2b (mandatory) SCHUFA Services DE
Integration
POST Request - consumerscore
Account Parameters
request
required
Fixed Value: consumerscore
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
channel
required
Fixed Value: clientapi
channelDetail
required
Permitted Value: payoneHosted
Common Parameters
addresschecktype
required
Format LIST 
Value Group Comment
BA PAYONE Services Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing
PE PAYONE Services Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address
BB Boniversum Services Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing
PB Boniversum Services Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address

Primary account number of credit card 
consumerscoretype
required
Format LIST
Value Comment
Arvato Infoscore Services  – must be combined with addresschecktype “NO”, “BA”, “PE”
IH Infoscore (hard criteria)
IA Infoscore (all criteria)
IB Infoscore (all criteria + bonus score)
IF Infoscore (all criteria + bonus score) + Informa-Consumer-Score
Boniversum Services – must be combined with addresschecktype “PB”
CE Boniversum VERITA Score including special addresses (status-codes AS1..AS8)
SCHUFA Services – must be combined with addresschecktype “BS”
SFS SCHUFA credit worthiness SHORT; can be combined with “b2b” and “b2c”
SFM SCHUFA credit worthiness MIDDLE; can be combined with “b2b” only

Specifies type of consumer score to be performed.
businessrelation
optional
Format LIST
Value Comment
b2c Indicates business to private customer
b2b indicates business to business customer (company)

Value specifies business relation between merchant and customer.

Request specific:

Consumerscoretype Comment
SFS, SFM "businessrelation" is mandatory for SCHUFA-checks
other "businessrelation" is recommended be set to "b2c" for other checks
firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
lastname
optional
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
company
optional
Format CHAR(2..50)

Comany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)
streetname
optional
Format CHAR(1..50)

Street name
streetnumber
optional
Format CHAR(1..50)

Street number
zip
optional
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode
city
required
Format CHAR(2..50)

City of customer
country
required
Format LIST
Permitted values ISO 3166 2-letter-codes
Samples

DE

GB

US

Specifies country of address for the customer

Check “BB”, “PB”: only “DE” supported
telephonenumber
optional
Format CHAR(1..30)

Phone number of customer
birthday
optional
Format DATE(8), YYYYMMDD
Samples

20190101

19991231

Date of birth of customer
language
optional
Format LIST
Permitted values ISO 639-1 (Language)2-letter-codes

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.
gender
optional
Format LIST
Permitted values
f / m/ d

Gender of customer (female / male / diverse* )

* currently not in use
Response Parameters
status
Permitted Values
VALID
INVALID
ERROR
Response parameters (Valid)- address valid
secstatus
Format LIST
Value Status Comment
10 VALID address correct
20 VALID address could be corrected / has changed
30 INVALID address could not be corrected

Response code of address check to return whether address has been corrected
scorevalue
Format NUMERIC(1..4), values and ranges see table below.
consumerscoretype Provider Range Remarks
IA, IB, IH, IF Arvato Infoscore Score: 100-990 The higher the value, the higher the degree of creditworthiness
Please refer to Decision matrix Arvato Infoscore Boni-Score/Informa-Score
CE Boniversum VERITA Score: 0-6000 The higher the value, the lower the degree of creditworthiness
Please refer to Decision matrix Boniversum VERITA score
SFS, SFM SCHUFA B2B Score: 100-600 The higher the value, the lower the degree of creditworthiness; values e.g. “100”, “204”, “202.3”
SFS SCHUFA B2C Score: 1-9999 The higher the value, the higher the degree of creditworthiness

First name of customer; optional if company is used, i.e.: you may use"company" or "lastname" or "firstname" plus "lastname"
secscore
Format LIST

For consumerscoretype: IA, IB, IH, IF; Negative criteria if registered.

Negative criteria; details see code list: Consumer score Arvato Infoscore - secscore
personstatus
Format LIST
Value Comment
<list> List of codes: AddressCheck-Returns (personstatus)

Person address check result; details see code list (“Parameters for address check person returns”)
addressstatus
Format LIST

Only available with “CE” and “PB” and only if special address is indicated:

Person address check result; details see code list: Consumer score Boniversum VERITA score addressstatus
provideruserid
Format AN..30

Only with consumerscoretype: SFS, SFM (b2b/b2c): Internal provider reference
identityconfirmed
Format LIST
Y Identity has been confirmed
N Identity has not been confirmed

Only with consumerscoretype: SFS (b2c)
gender
Format LIST
F Female
M Male

Only with consumerscoretype: SFS (b2c): gender of person
legalform
Format AN..100

Only with consumerscoretype: SFM (b2b): Legal form <code>;<text>

e.g. “21;Gesellschaft mit beschränkter Haftung”

See list of values: Consumer score SCHUFA legal form
creditlimitvalue
Format AN..10

Only with consumerscoretype: SFM (b2b): Creditlimit value
creditlimitcurrency
Format LIST

Only with consumerscoretype: SFM (b2b): Creditlimit currency (ISO-code)
foundingdate
Format AN..10

Only with consumerscoretype: SFM (b2b): Founding date in format yyyy-mm-dd
taxid
Format AN..20

Only with consumerscoretype: SFM (b2b): Tax id of company
firstname
Format LIST

First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
lastname
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
company
Format CHAR(2..50)

Comany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"
street
Format CHAR(1..50)

Street number and name (required: at least one character)
streetname
Format CHAR(1..50)

Street name
streetnumber
Format CHAR(1..50)

Street number
zip
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode
city
Format CHAR(2..50)

City of customer
Response parameters (INvalid) - address invalid
secstatus
Format LIST
Value Status Comment
>10 >VALID >address correct
>20 >VALID >address could be corrected / has changed
>30 >INVALID >address could not be corrected

Response code of address check to return whether address has been corrected
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.
customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")
Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.
customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

 
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

RESPONSE