Basics

Welcome to Covery API documentation

API follows the REST architecture where endpoints are built around the concept of resources, actions are represented by the respective HTTP verb and response statuses are represented using HTTP status codes.

For your convenience, we have also prepared a PHP Client.

If you have any questions or need an assistance, please contact us.

API endpoint

https://api.covery.ai

Encoding

API uses UTF-8 character encoding.

Access tokens

Every request, sent to the Covery API, must contain access token and signature, based on token secret. Access information is always supplied to customers in pairs during the onboarding process:

Type	Example
Access token	21a3358f36e5af968b75357590b75c28
Token secret	eNfrVfsXQtI+yCIQ9XmuKYP5yBjK0ip7

Token levels

There are seven token levels:

Level	Permission
event	accountConfigurationStatus, sendEvent, nodeName and cardId
decision	accountConfigurationStatus, sendEvent, makeDecision, nodeName, cardId and clientManagement
media	Storage
payment description	paymentDescription
trustchain	getReputation
ip screening	makeIpScreening
device fingerprint	device-fingerprint-js
device screening	device-fingerprint-js and makeDeviceScreening

Requests

Request must have a JSON encoded body and following headers:

Header		Description
X-Auth-Token	mandatory	Access token, received from Covery administrators
X-Auth-Nonce	mandatory	Random unique string, used as salt in packet signature
X-Auth-Signature	mandatory	Packet signature
X-Identities		List of identity nodes in format name1=id1&name2=id2&…, used only in Event and Decision APIs

hash('sha256', $nonce . $request->getContent() . $secret)

X-Auth-Signature is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

Responses

HTTP/1.1 200 OK
Content-Type: application/json
X-Maxwell-Status: OK

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Maxwell-Status: Exception
X-Maxwell-Error-Type: Maxwell\Exception\NoRouteException
X-Maxwell-Error-Message: Unable to found route for POST /api/wrong/endpoint

API response body can be empty or JSON encoded object or array.

API response status is reported using the appropriate HTTP status code. Additional details are provided by headers.

Name		Description
Content-Type	mandatory	application/json for most cases, but can be text/plain for errors
X-Maxwell-Status	mandatory	OK for success, Exception for errors
X-Maxwell-Error-Type	optional	Exception class name in common
X-Maxwell-Error-Message	optional	Exception text in common
X-Maxwell-Error-Context	optional	May contain additional information about error, such as id when trying to insert entry, that already exists

Status codes

Code	Description
200	OK
204	OK, but no content to respond
401	One of mandatory headers is missing
403	Token access level not sufficient to access requested API
404	No API method for URL or wrong HTTP method
406	Wrong/malformed incoming request data
409	Entry already exist, inspect X-Maxwell-Error-Context header for id
410	Entry not found
429	Too many requests with same sequence_id or request_id
500	Internal error
503	API method presents but misconfigured in dependency injection. Please contact us ASAP
509	Too many requests
510	Failed to build application using dependency injection config. Please contact us ASAP

Account status API

Covery account configuration details can be checked with Account configuration status API. You will be able to see basic configurations and all active additional services on your account. In case you'll find that you need to make some changes in your account settings, please contact support@covery.ai

Detail	Description
Method	GET
Endpoint	api/accountConfigurationStatus
Access level	Event, Decision

Response fields

Field	Type	Description
actualEventTypes	string list	List of evet types available for your account
baseCurrency	string	Currency that Covery will use to convert payment amounts
decisionCallbackUrl	string	Your URL that can be used to receive asynchronous responses
manualDecisionCallbackUrl	string	Your URL that will be used to send end status of event after manual decision, see Decision API
ongoingMonitoringWebhookUrl	string	Your URL that will be used to send Ongoing monitoring result, see Ongoing monitoring API
mediaStorageWebhookUrl	string	Your URL that will be used to send callbacks about Media uploading status change, see Document storage callback
fraudAlertCallbackUrl	string	Your URL that will be used to send fraud alert matching results, see Fraud alert API
cardIdGeneration	bool
deviceFingerprintGeneration	bool
sequenceIdGeneration	bool	see event merge Event merge
sequenceIdGenerationMethod	string	Possible values: Using email or Using user id
amlService	string list	Name of your watchlist database provider
amlServiceStatus	bool
dowJonesDataBaseDate	long
lexisNexisDataBaseDate	long
kycProvider	string	Name of your KYC provider

Event API

Use Event API to send user actions in your product for further analysis of events sent to Decision API.

Download Postman collection

Detail	Description
Method	POST
Endpoint	api/sendEvent
Access level	Event

Install

Download Postman Install

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be install
install_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255
sequence_id	string	255		See event merge
group_id	string	255		See event merge
country	string	255		ISO ALPHA-3 format, e.g. usa
website_url	string	255
traffic_source	string	255
affiliate_id	string	255
campaign	string	255
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Registration

Download Postman Registration

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be registration
registration_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
age	int
country	string	255		ISO ALPHA-3 format, e.g. usa
email	string	255
password	string	255		Encrypted user password
firstname	string	255
lastname	string	255
gender	string	255
phone	string	255
social_type	string	255
user_name	string	255
website_url	string	255
traffic_source	string	255
affiliate_id	string	255
campaign	string	255
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Confirmation

Download Postman Confirmation

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be confirmation
confirmation_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
email	string	255
phone	string	255
email_confirmed	bool
phone_confirmed	bool
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Login

Download Postman Login

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be login
login_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
login_failed	bool
email	string	255
password	string	255		Encrypted user password
phone	string	255
gender	string	255
traffic_source	string	255
affiliate_id	string	255
campaign	string	255
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Order item

Download Postman Order Item

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be order_item
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
amount	float	decimal(26,12)	mandatory
currency	string	255	mandatory
order_type	string	255	mandatory	Examples: sku, tax, fee, shipping, complex
amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
sequence_id	string	255		See event merge
group_id	string	255		See event merge
user_merchant_id	string	255
email	string	255
firstname	string	255
lastname	string	255
phone	string	255
product_description	string	1024
product_name	string	255
product_quantity	float
website_url	string	255
product_url	string	255
product_image_url	string	255
customer_comment	string	255
social_type	string	255
affiliate_id	string	255
campaign	string	255
coupon_end_date	long			Unix timestamp in seconds
coupon_id	string	255
coupon_name	string	255
coupon_start_date	long			Unix timestamp in seconds
shipping_address	string	255
shipping_city	string	255
shipping_country	string	255		ISO ALPHA-3 format, e.g. usa
shipping_currency	string	255
shipping_fee	float	decimal(26,12)
shipping_fee_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
shipping_state	string	255
shipping_zip	string	255
transaction_id	string	255
carrier	string	255
carrier_shipping_id	string	255
carrier_url	string	255
carrier_phone	string	255
delivery_estimate	long			Unix timestamp in seconds
order_source	string	255
source_fee	float	decimal(26,12)
source_fee_currency	string	255
source_fee_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
tax_currency	string	255
tax_fee	float	decimal(26,12)
tax_fee_converted	float	decimal(26,12)
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Order submit

Download Postman Order Submit

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be order_submit
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
amount	float	decimal(26,12)	mandatory
currency	string	255	mandatory
items_quantity	int		mandatory
amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
sequence_id	string	255		See event merge
group_id	string	255		See event merge
user_merchant_id	string	255
email	string	255
firstname	string	255
lastname	string	255
phone	string	255
website_url	string	255
product_url	string	255
product_image_url	string	255
customer_comment	string	255
social_type	string	255
affiliate_id	string	255
campaign	string	255
coupon_end_date	long			Unix timestamp in seconds
coupon_id	string	255
coupon_name	string	255
coupon_start_date	long			Unix timestamp in seconds
shipping_address	string	255
shipping_city	string	255
shipping_country	string	255		ISO ALPHA-3 format, e.g. usa
shipping_currency	string	255
shipping_fee	float	decimal(26,12)
shipping_fee_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
shipping_state	string	255
shipping_zip	string	255
transaction_id	string	255
carrier	string	255
carrier_shipping_id	string	255
carrier_url	string	255
carrier_phone	string	255
delivery_estimate	long			Unix timestamp in seconds
order_source	string	255
source_fee	float	decimal(26,12)
source_fee_currency	string	255
source_fee_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
tax_currency	string	255
tax_fee	float	decimal(26,12)
tax_fee_converted	float	decimal(26,12)
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Transaction

Download Postman Transaction

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be transaction
transaction_amount	float	decimal(26,12)	mandatory
transaction_currency	string	255	mandatory	ISO ALPHA-3 format, e.g. usd
transaction_id	string	255	mandatory
transaction_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
payment_method	string	255
payment_system	string	255
payment_mid	string	255
transaction_mode	string	255
transaction_type	string	255
payment_account_id	string	255
card_id	string	255		See card id generation
card_bin	int
card_last4	string	4
expiration_month	int
expiration_year	int
age	int
billing_address	string	255
billing_city	string	255
billing_country	string	255		ISO ALPHA-3 format, e.g. usa
billing_fullname	string	512		If not sent, will consist of billing first and last names
billing_firstname	string	255
billing_lastname	string	255
billing_state	string	255
billing_zip	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
email	string	255
firstname	string	255
lastname	string	255
gender	string	255
merchant_ip	string	255
merchant_country	string	255		ISO ALPHA-3 format, e.g. usa
mcc	string	255
acquirer_merchant_id	string	255
phone	string	255
product_description	string	1024
product_name	string	255
product_quantity	float
transaction_amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
user_name	string	255
website_url	string	255
transaction_source	string	255
affiliate_id	string	255
campaign	string	255
links_to_documents	string list	2048		List of links to the documents saved outside Covery
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Refund

Download Postman Refund

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be refund
refund_timestamp	long		mandatory	Unix timestamp in seconds
refund_id	string	255	mandatory
refund_amount	float	decimal(26,12)	mandatory
refund_currency	string	255	mandatory	ISO ALPHA-3 format, e.g. usd
refund_amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
user_merchant_id	string	255
sequence_id	string	255		See event merge
group_id	string	255		See event merge
email	string	255
phone	string	255
refund_method	string	255
refund_system	string	255
refund_mid	string	255
refund_source	string	255
refund_type	string	255		E.g. full, partial
refund_code	string	255		Reason code why refund issued
refund_reason	string	255		Reason why refund issued
agent_id	string	255		Person who issued refund
links_to_documents	string list	2048		List of links to the documents saved outside Covery
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Payout

Download Postman Payout

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be payout
payout_timestamp	long		mandatory	Unix timestamp in seconds
payout_id	string	255	mandatory
user_merchant_id	string	255	mandatory
payout_amount	float	decimal(26,12)	mandatory
payout_currency	string	255	mandatory	ISO ALPHA-3 format, e.g. usd
payout_amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
sequence_id	string	255		See event merge
group_id	string	255		See event merge
payout_method	string	255
payout_system	string	255
payout_mid	string	255
payout_account_id	string	255
payout_card_id	string	255		See card id generation
firstname	string	255
lastname	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
email	string	255
phone	string	255
payout_card_bin	int
payout_card_last4	string	4
payout_expiration_month	int
payout_expiration_year	int
links_to_documents	string list	2048		List of links to the documents saved outside Covery
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Transfer

Download Postman Transfer

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be transfer
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
amount	float	decimal(26,12)	mandatory
currency	string	255	mandatory	ISO ALPHA-3 format, e.g. usd
account_system	string	255
account_id	string	255
second_account_id	string	255
amount_converted	float	decimal(26,12)		If not sent, will be converted to base currency of your account
sequence_id	string	255		See event merge
group_id	string	255		See event merge
operation	string	255
transfer_source	string	255
firstname	string	255
lastname	string	255
fullname	string	512
bic	string	255		SWIFT code
iban	string	255
email	string	255
phone	string	255
birth_date	long			Unix timestamp in seconds
gender	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
state	string	255
city	string	255
address	string	255
zip	string	255
second_user_merchant_id	string	255
second_firstname	string	255
second_lastname	string	255
second_fullname	string	512
second_iban	string	255
second_email	string	255
second_phone	string	255
second_birth_date	long			Unix timestamp in seconds
second_gender	string	255
second_country	string	255		ISO ALPHA-3 format, e.g. usa
second_state	string	255
second_city	string	255
second_address	string	255
second_zip	string	255
product_name	string	255
product_description	string	1024
product_quantity	float
links_to_documents	string list	2048		List of links to the documents saved outside Covery
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Document

Download Postman Document

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be document
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
document_type	string	255	mandatory	Possible values: international_passport, national_passport, id_card, residence_permit, drivers_license, bank_statement, tax_declaration, invoice, receipt, utility_bill, personal_photo, other
sequence_id	string	255		See event merge
group_id	string	255		See event merge
document_country	string	255		ISO ALPHA-3 format, e.g. usa
document_number	string	255
file_name	string	255
email	string	255
firstname	string	255
lastname	string	255
fullname	string	512
birth_date	long
age	int
gender	string	255
nationality	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
state	string	255
city	string	255
zip	string	255
address	string	255
issue_date	long			Unix timestamp in seconds
expiry_date	long			Unix timestamp in seconds
authority	string	255
record_number	string	255
personal_number	string	255
description	string	1024
product_quantity	float
payment_method	string	255
amount	float	decimal(26,12)
amount_converted	float	decimal(26,12)
currency	string	255
mrz_document_type	string	255
mrz_country	string	255		MRZ country format, e.g.usa
mrz_lastname	string	255
mrz_firstname	string	255
mrz_fullname	string	255
mrz_document_number	string	255
mrz_nationality	string	255		MRZ country format, e.g.usa
mrz_personal_number	string	255
mrz_birth_date	long			Unix timestamp in seconds
mrz_gender	string	255
mrz_expiry_date	long			Unix timestamp in seconds
mrz_record_number	string	255
mrz_check_digits_validation	bool
extracted_text	string	16000
text_language_details	string list	1024
translated_extracted_text	string	16000
translated_from	string	255		ISO-639-1 format, e.g.en. The auto-detection language option is available with the value auto
translated_to	string	255		ISO-639-1 format, e.g.en
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

Profile update

Download Postman Profile Update

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be profile_update
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
operation	string	255		What exactly was changed. For example: password updated, limit updated
account_id	string	255
currency	string	255		ISO ALPHA-3 format, e.g. usd
phone	string	255
phone_confirmed	bool
email	string	255
email_confirmed	bool
contact_email	string	255
contact_phone	string	255
2fa_allowed	bool
user_name	string	255
password	string	255		Encrypted user password
social_type	string	255
game_level	string	255
firstname	string	255
lastname	string	255
fullname	string	512
birth_date	long			Unix timestamp in seconds
age	int
gender	string	255
marital_status	string	255
nationality	string	255
physique	string	255
height	float	decimal(5,2)
weight	float	decimal(5,2)
hair	string	255
eyes	string	255
education	string	255
employment_status	string	255
source_of_funds	string	255
industry	string	255
final_beneficiary	bool
wallet_type	string	255
website_url	string	255
description	string	1024
country	string	255		ISO ALPHA-3 format, e.g. usa
state	string	255
city	string	255
zip	string	255
address	string	255
address_confirmed	bool
second_country	string	255		ISO ALPHA-3 format, e.g. usa
second_state	string	255
second_city	string	255
second_zip	string	255
second_address	string	255
second_address_confirmed	bool
profile_id	string	255
profile_type	string	255
profile_sub_type	string	255
document_country	string	255		ISO ALPHA-3 format, e.g. usa
document_confirmed	bool
reg_date	long			Unix timestamp in seconds
issue_date	long			Unix timestamp in seconds
expiry_date	long			Unix timestamp in seconds
reg_number	string	255
vat_number	string	255
purpose_to_open_account	string	255
one_operation_limit	float	decimal(26,12)
daily_limit	float	decimal(26,12)
weekly_limit	float	decimal(26,12)
monthly_limit	float	decimal(26,12)
annual_limit	float	decimal(26,12)
active_features	string list	1024
promotions	string list	1024
links_to_documents	string list	2048		List of links to the documents saved outside Covery
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

KYC procedure

Download Postman KYC Procedure

We provide an opportunity to work with many KYC providers through one universal API. User data can enter the Covery both directly from the provider and from the client. Procedure in a general view is as follows:

1. You send a KYC start request, which describes the conditions for passing the KYC procedure, such as language, photo or video verification, the number of documents, etc.
2. Covery analyzes the request and transfers it to the KYC provider
3. Covery returns a response with the URL to which end user must be redirected or which will be displayed in an iframe
4. End user follows the URL, and goes through the procedure or not. If end user has gone through the procedure to the end (successfully or not) he will be redirected to the URL specified in the KYC start request.
5. If the procedure is interrupted at the user's initiative or as a result of a timeout, you can receive KYC start callback from Covery
6. After the end user passes the procedure, a new KYC profile event is generated on Covery. This event contains all the information received from the KYC provider and passes all the prepared risks controls and AML checks. As a result you receive a decision callback for this event.
7. The procedure is completed. To obtain photo / video proofs, use the KYC proof method

For complex verification of a legal entity, when it is necessary to receive a KYC procedure for several beneficiaries (individuals and legal entities), can be used an additional type of KYC submit event

KYC start

Download Postman KYC start

This event initiates KYC procedure for the end user. If it wouldn't be rejected by risk logic - in the decision you will receive a verification URL, where you need to redirect end user.

Field	Type	Length		Description
type	string	255	mandatory	Value has to be kyc_start
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory	string
verification_mode	string	255	mandatory	Possible values: any, image, video
verification_source	string	255	mandatory	Possible values: any, online, offline
consent	bool		mandatory
number_of_documents	int			Number of documents that should be checked in this procedure. Allowed values: 0, 1, 2. By default = 1
allowed_document_format	string list	255		This field can additionally allow to provide a documents in special formats. Allowed values: paper, laminated, photocopy.
allow_na_ocr_inputs	bool			If the parameter value is set to 0, the end-user will be required to fill all input fields on OCR confirmation form.
decline_on_single_step	bool			When the value of this parameter is set to 1, it declines the entire verification request when any one of the verification steps fails
backside_proof	bool			If the value of this parameter is set to 1, the end-user will require to capture/upload both sides of the document to verify the identity
sequence_id	string	255		See event merge
group_id	string	255		See event merge
country	string	255		ISO ALPHA-3 format, e.g. usd
kyc_language	string	255		ISO ALPHA-2 format, e.g. en
redirect_url	string	255
email	string	255
firstname	string	255
lastname	string	255
profile_id	string	255
phone	string	255
birth_date	long			Unix timestamp in seconds
reg_number	string	255
issue_date	long			Unix timestamp in seconds
expiry_date	long			Unix timestamp in seconds

Implement device fingerprinting to investigate suspicious devices.

KYC start callback

This method returns callbacks about KYC start session statuses.

If it is configured, Covery will send callback for every KYC start session status changes to the defined by Covery customer URL.

With the following headers:

Method: POST

Header	Description
X-Auth-Nonce	Signature salt
X-Auth-Signature	Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.

Response example

{
  "requestId": 7896010,
  "type": "transaction",
  "createdAt": 1449049571,
  "sequenceId": "3f3c5e978f90f2a9495bce7492467a65f61333be",
  "merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b",
  "status": "timeout"
}

Response fields

Field	Type	Description
requestId	long	kyc start requestId
type	string	value: "kycStartCallback"
createdAt	long	kyc start status change timestamp
sequenceId	string	sequence_id from request
merchantUserId	string	user_merchant_id from request
status	string	possible values: timeout, cancelled, completed

KYC profile

Download Postman KYC Profile

The event is used to send data about particular profile, e.g. person or company, for ongoing KYC procedure.

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be kyc_profile
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
status	string	255		Profile status
code	string	255
reason	string	255
provider_id	string	255		KYC provider event id
provider_result	string	255		Result from third-party provider
provider_code	string	255
provider_reason	string	255
links_to_documents	string list	2048		List of links to the documents saved outside Covery
profile_id	string	255		Profile ID
profile_type	string	255		Profile type e.g. person, company or document
profile_sub_type	string	255		Profile subtype e.g. company or document type
firstname	string	255
lastname	string	255
fullname	string	512		Can be also used to send company name
gender	string	255
industry	string	255
wallet_type	string	255
website_url	string	255
description	string	1024		E.g. clarification of industry or document details
employment_status	string	255
source_of_funds	string	255
birth_date	long			Unix timestamp in seconds
reg_date	long			Unix timestamp in seconds
issue_date	long			Unix timestamp in seconds
expiry_date	long			Unix timestamp in seconds
reg_number	string	255
vat_number	string	255
email	string	255
email_confirmed	bool
phone	string	255
phone_confirmed	bool
contact_email	string	255
contact_phone	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
state	string	255
city	string	255
address	string	255
address_confirmed	bool
zip	string	255
nationality	string	255
second_country	string	255		ISO ALPHA-3 format, e.g. usa
second_state	string	255
second_city	string	255
second_address	string	255
second_address_confirmed	bool
second_zip	string	255
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

KYC submit

Download Postman KYC Submit

The event is used to submit ongoing KYC procedure for the analysis.

Request fields

Field	Type	Length		Description
type	string	255	mandatory	Value has to be kyc_submit
event_id	string	255	mandatory
event_timestamp	long		mandatory	Unix timestamp in seconds
user_merchant_id	string	255	mandatory
sequence_id	string	255		See event merge
group_id	string	255		See event merge
status	string	255		Profile status
code	string	255
reason	string	255
provider_id	string	255		KYC provider event id
provider_result	string	255		Result from third-party provider
provider_code	string	255
provider_reason	string	255
links_to_documents	string list	2048		List of links to the documents saved outside Covery
profile_id	string	255		Profile ID
profile_type	string	255		Profile type e.g. person, company or document
profile_sub_type	string	255		Profile subtype e.g. company or document type
firstname	string	255
lastname	string	255
fullname	string	512		Can be also used to send company name
gender	string	255
industry	string	255
wallet_type	string	255
website_url	string	255
description	string	1024		E.g. clarification of industry or document details
employment_status	string	255
source_of_funds	string	255
birth_date	long			Unix timestamp in seconds
reg_date	long			Unix timestamp in seconds
issue_date	long			Unix timestamp in seconds
expiry_date	long			Unix timestamp in seconds
reg_number	string	255
vat_number	string	255
email	string	255
email_confirmed	bool
phone	string	255
phone_confirmed	bool
contact_email	string	255
contact_phone	string	255
country	string	255		ISO ALPHA-3 format, e.g. usa
state	string	255
city	string	255
address	string	255
address_confirmed	bool
zip	string	255
nationality	string	255
second_country	string	255		ISO ALPHA-3 format, e.g. usa
second_state	string	255
second_city	string	255
second_address	string	255
second_address_confirmed	bool
second_zip	string	255
document_id	int list

Implement device fingerprinting to investigate suspicious devices.

KYC proof

Download Postman KYC proof

This method allows you to receive a link to photo / video proofs collected during KYC procedure.

Request must have a JSON encoded body and following headers:

Header		Description
X-Auth-Token	mandatory	Access token, received from Covery administrators
X-Auth-Nonce	mandatory	Random unique string, used as salt in packet signature
X-Auth-Signature	mandatory	Packet signature

X-Auth-Signature is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

Detail	Description
Method	POST
Endpoint	api/kycProof
Access level	Event or Decision

Request fields

Field	Type	Length		Description
kyc_start_id	long		mandatory	kyc start requestId

Response example

{
  "requestId":7896010,
  "type":"kycProof",
  "createdAt":1449049571.123,
  "verificationVideo":"https://covery.ai/comics",
  "faceProof":"https://covery.ai/comics",
  "documentProof":"https://covery.ai/comics",
  "documentTwoProof":"https://covery.ai/comics",
  "consentProof":"https://covery.ai/comics"
}

Response fields

Field name	Type	Description
requestId	long	ID of inserted data
type	string	value: kycProof
createdAt	long	timestamp
verificationVideo	string	link on a document
faceProof	string	link on a document
documentProof	string	link on a document
documentTwoProof	string	link on a document
consentProof	string	link on a document

Event merge

Sequence of user actions

sequence_id is an optional field in all the events. It is used to associate consecutive user actions inside your product for deeper understanding of user behavior and more precise decisions.

Sequence example: registration and then transaction made by user within relatively short period of time.

Group of user actions

group_id is an optional field in the events that support grouping. It is used to associate a set of user actions under particular sequence_id to divide the whole sequence into smaller groups of actions.

Group example: registration, [KYC profile of personal details, KYC profiles of documents, KYC submit] - this is a group, and then transaction.

Decision API

Use Decision API to get a risk assessment of user actions in your product. Events which are used only for analysis of other actions should be sent to Event API.

Detail	Description
Method	POST
Endpoint	api/makeDecision
Access level	Decision

Response example

{
  "requestId": 7896010,
  "type": "transaction",
  "createdAt": 1449049571,
  "sequenceId": "3f3c5e978f90f2a9495bce7492467a65f61333be",
  "merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b",
  "score": 80,
  "accept": false,
  "reject": true,
  "manual": false,
  "reason": "User 5 cards 1 day, Disposable email domain, Anonymous proxy",
  "action": "Additional verification",
  "agentId": 12345,
  "note": "Customer verified manually",
  "checkedInCategory": ["person terror, person sanctions list, company sanctions list"],
  "verificationUrl": "https://covery.ai/comics",
  "notSavedFields": ["lastname, phone"]
}

Response fields

Field	Type	Description
requestId	long	Internal event identifier in the Covery
type	string	type from request
createdAt	long	Unix timestamp in seconds
sequenceId	string	Sequence_id from request
merchantUserId	string	User_merchant_id from request
score	int	Calculated risk score
accept	bool	Event accepted
reject	bool	Event rejected
manual	bool	Event sent to manual review
reason	string	Explanation of made decision
action	string	Business flow for made decision
agentId	int	An identifier of user, that made a manual decision on a Covery portal
note	string	Any comments, that were left during manual decision on a Covery portal
checkedInCategory	string list	Returns watchlists, against which event was checked. Relevant only in case AML screening service is used
verificationUrl	string	The link, to which the user should be transferred after decision. For event KYC Start only
notSavedFields	string list	If event was send with correct mandatory fields, but not valid by length or type optional fields, Covery will save and analyze such event without those fields. For your attention we will return list of not saved fields here

If manual: true - you are able to make one more final decision inside my.covery.ai portal. In this case one more callback will be sent on chosen URL (please provide it to Covery team). Callback will have the same the format of the body as first synchronous response, with next header:

Header		Description
X-Auth-Signature	mandatory	Manual decision callback signature must be calculated as sha256 checksum from provided by you secret + event request id

Postback API

Request example when request_id is known

{
  "request_id": 123456,
  "transaction_status": "success",
  "code": "4002",
  "reason": "Insufficient funds",
  "secure3d": "0",
  "avs_result": "U",
  "cvv_result": "M"
}

Request example when only transaction_id is known

{
  "transaction_id": "TR123456",
  "transaction_status": "success",
  "code": "4002",
  "reason": "Insufficient funds",
  "secure3d": "0",
  "avs_result": "U",
  "cvv_result": "M"
}

Response example

{
  "requestId": 123456
}

This API is used to supply additional data after event processing.

Detail	Description
Method	POST
Endpoint	api/postback
Access level	Event

Request fields

Field	Type	Length	Description
request_id	long		mandatory if no transaction_id present
transaction_id	string	255	mandatory if no request_id present (This field will not be supported from the next version of the API)
transaction_status	string	255
code	string	255
reason	string	255
secure3d	string	255
avs_result	string	255
cvv_result	string	255
psp_code	string	255
psp_reason	string	255
provider_code	string	255
provider_reason	string	255
provider_result	string	255
merchant_advice_code	string	255
merchant_advice_text	string	255
arn	string	255

Response fields

Field	Type
requestId	long

Node name API

Request example

{ "nodeNames" : [
  {
    "nodeType": "Node type1",
    "nodeId": "Node id1",
    "nodeName": "name1"
  },
  {
    "nodeType": "Node type2",
    "nodeId": "Node id2",
    "nodeName": "name2"
  }
]
}

With Node name API method you can map Node id into readable in reports Node name:

Detail	Description
Method	PUT
Endpoint	api/nodeName
Access level	Event, Decision

Request fields

Field	Type		Description
nodeNames	object list	mandatory
nodeType	string	mandatory
nodeId	int	mandatory
nodeName	string	mandatory

Card ID API

This method allows to generate unique sustainable ID of the card. Card ID would be generated only for valid card number. If you do not have proper PCI DSS certification - you are prohibited to save card number from request in any, even temporary log, storage.

Detail	Description
Method	POST
Endpoint	api/cardId
Access level	Event and Decision

Download Postman Card Id

Request fields

Field	Type	Length		Description
card_number	string	20	mandatory	Full number of card

Response example

{
  "requestId": 7896010,
  "createdAt": 1449049571,
  "cardId": "5aaaa194f3baaaaade427"
}

Response fields

Field	Type	Description
requestId	long	ID of inserted data
createdAt	long	timestamp
cardId	string	use as card_id or as payout_card_id

Document API

Use Document storage to upload document files and connect them to end-user events. Inside the Covery portal, you can review uploaded data and get more information extracted from it. We are using AI and Computer vision to get not only the metadata of a file but also to detect some information on the documents and images.

Storage

This method will allow you to upload your document files to the Covery storage. As a result of the request, you will receive a temporary URL by which you can store the document file. In case there are multiple pages in the document, you will need to specify the number of document pages and upload each page via a separate URL. We work only with jpeg, png, and gif file formats.

Download Postman Storage.

Detail	Description
Method	POST
Endpoint	api/documentStorage
Access level	Document

Header		Description
X-Auth-Token	mandatory	Access token, received from Covery administrators
X-Auth-Nonce	mandatory	Random unique string, used as salt in packet signature
X-Auth-Signature	mandatory	Packet signature. Is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

Request fields

Field	Type	Length		Description
user_merchant_id	string	255	mandatory
document_type	string	255	mandatory	Possible values: international_passport, national_passport, id_card, residence_permit, drivers_license, bank_statement, tax_declaration, invoice, receipt, utility_bill, personal_photo, other
document_country	string	255		ISO ALPHA-3 format, e.g. usa
sequence_id	string	255		See event merge
group_id	string	255		See event merge
file_name	string	255		In case a value is present - replace the filename with a specific value in this field
ocr	bool			false by default
number_of_pages	int			1 by default. Use the number_of_pages field to specify when there is more than one page related to a certain document. Based on the specified number of pages there will be generated appropriate amount of URLs to upload each page separately
translated_from	string	255		ISO-639 format, e.g.en. The auto-detection language option is available with the value auto
translated_to	string	255		ISO-639 format, e.g.en

Response fields

Field	Type	Description
uploadUrl	string list	URL can be used for uploading the file during 10 minutes
documentId	int	ID of inserted document file
createdAt	long	Unix timestamp in seconds

Implement device fingerprinting to investigate suspicious devices.

Storage callback

This method returns callbacks about Document uploading status changes and Document event creation info. If it is configured, Covery will send a callback for every upload page session status change and the result of the Document event creation to the defined by Covery customer URL.

Method: POST

Header	Description
X-Auth-Nonce	Signature salt
X-Auth-Signature	Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.

Response fields

Field	Type	Description
status	string	Possible values: success, error
errorReason	string	Error reason description
errorCode	int	Error reason code
documentId	int	ID of inserted document file
pageNumber	int	Document page number
createdAt	long	Unix timestamp in seconds

Connection

With this method, you can bind the document file that was sent to our storage with the envelope sent before. You can bind more than one document file with one envelope. Also, one document file can be bound to multiple envelopes.

Document connection method

Detail	Description
Method	PUT/DELETE
Endpoint	api/documentConnection
Access level	Document

Header		Description
X-Auth-Token	mandatory	Access token, received from Covery administrators
X-Auth-Nonce	mandatory	Random unique string, used as salt in packet signature
X-Auth-Signature	mandatory	Packet signature. Is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

Request fields

Field	Type	Length		Description
request_id	long		mandatory	Internal event identifier in the Covery
document_id	int list		mandatory	Internal document identifier in the Covery

Client management API

Use Client management API to create user profile and establish its ongoing monitoring on needed regular basis.

Detail	Description
Method	PUT and DELETE
Endpoint	api/clientManagement
Access level	Decision

Request fields

Field	Type	Length		Description
type	string	255	mandatory	value has to be user_profile
sequence_id	string	255	mandatory
client_type	string	255	mandatory for PUT only
ongoing_monitoring	bool			false by default
ongoing_monitoring_frequency	int	3		value in days starting from 1

Ongoing monitoring

When ongoing monitoring is set up for an end user you will start to receive our callbacks each time it has been done. Please, provide for those needs your callback URL to the Covery team.

Header	Description
X-Auth-Nonce	Signature salt
X-Auth-Signature	Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.
Method	POST

Response fields

Field	Type	Description
requestId	long	internal Covery ID
type	string	ongoing monitoring
createdAt	long	timestamp
sequenceId	string	sequence_id from request
merchantUserId	string	user_merchant_id from request
monitoringResult	string	possible values: Safety, Alert, Warning
riskRating	float	calculated risk rating based on sum of all triggered Rule scores, possible value from 0 to 6
reason	string	list of rules with decision true, from decisive scenario
scenario	string	name of decisive ongoing monitoring scenario
assessmentResult	string	possible values: Safety, Alert, Warning. Will be present in a second webhook, in case of manual decision
agentId	int	ID of the user who performed assessment in the portal. Will be present in a second webhook, in case of manual decision
note	string	comment supplied during assessment, length 1024. Will be present in a second webhook, in case of manual decision.
checkedInCategory	string list	Returns watchlists, against which event was checked. Relevant only in case AML screening service is used

Payment description API

This method can be used to find persons, companies and dual-use goods mentioned in the payment description inside world wide watchlists. To make it the best it can be - we are using AI and math methods, and supporting more than 130 languages.

Detail	Description
Method	POST
Endpoint	api/paymentDescription
Access level	Payment description

Request fields

Field	Type	Length		Description
event_id	string	255	mandatory	Unique identifier of payment event
product_description	string	1024	mandatory	Text that must be analysed by system to find dual-use goods or names in watchlist
watchlist	bool		mandatory	Send True if AML matching must be done for names, found with NLP model
dual-use goods	bool		mandatory	Send True if Dual-use matching must be done

Response fields

Field	Type	Description
requestId	long	Internal event identifier in the Covery
createdAt	long	Unix timestamp in seconds
matchedAmlId	int list	Returns lists of profile ids inside AML provider watchlist DB
checkedInCategory	string list	Returns watchlists, against which event was checked. Relevant only in case AML screening service is used
dualUseGoodCode	string list	List of matched Item codes
dualUseGoodIssuer	string list	List of issuers for matched dual-use good
checkedInDualUseGoodSourses	string list	Returns watchlists, against which event was checked. Relevant only in case dual-use goods screening service is used

Trustchain API

This API is used to get item reputation details from Trustchain database.

Detail	Description
Method	POST
Endpoint	api/getReputation
Access level	Trustchain

Request fields

Field	Type		Description
itemType	string	mandatory	Possible values: email, email_domain, card_id, phone, ip, system_account_id, device_fingerprint, device_id, entity_id, person_id, iban, bic
itemValue	string	mandatory

Response example

{
  "requestId": 12,
  "createdAt": 1579590089,
  "private": {
    "reputation": "trusted",
    "sources": "Test data, Pilot data",
    "firstSeenDate": 1579076134,
    "reputationСhangeDate": 1579076134
  },
  "global": {
    "reputation": "trusted",
    "sources": "Test data, Pilot data",
    "firstSeenDate": 1579076134,
    "reputationСhangeDate": 1579076134
  },
  "industries": [
    {
      "name": "charity",
      "reputation": "trusted",
      "sources": "Test data, Pilot data",
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    {
      "name": "airlines",
      "reputation": "trusted",
      "sources": "Test data, Pilot data",
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    }
  ]
}

Response fields

Field	Type	Description
requestId	long	ID of inserted data
createdAt	long	Timestamp
private	object	See Private and Global Object
global	object	See Private and Global Object
industries	object	See Industries Object

Private and Global Objects

Field	Type	Description
reputation	string	Possible values: Trusted, Suspicious, Untrusted, Neutra
source	string list	Possible values: Auto decision - fraud, Auto decision - hacked, Auto decision - not fraud, Auto decision - verified, Client request - fraud, Client request - hacked, Client request - not fraud, Client request - verified, Manual decision - fraud, Manual decision - hacked, Manual decision - not fraud, Manual decision - verified, Bonus abuse, Emulation, Bot, Self-exclusion, VIP customer, Underage, Watch list, Payment - bank negative list, Payment - canceled subscription, Payment - chargeback, Payment - fraud alert, Payment - lost or stolen card, Payment - retrieval request, Pilot data, Test data, Third party - marketing, Third party - other
firstSeenDate	long
reputationСhangeDate	long

Industries Object

Field	Type	Description
name	string	Possible values: Airlines, Charity, Crowdfunding, Dating, Digital, Educatoin, Finance, Food, Gambling, Gaming, Hospitality, Insurance, Luxury, Manufacturing, Nutra, Other, Payment aggregators, Pharma, Retail, Telecommunications, Ticketing, Transportation, Travel, Utilities
reputation	string	Possible values: Trusted, Suspicious, Untrusted, Neutra
source	string list	Possible values: Auto decision - fraud, Auto decision - hacked, Auto decision - not fraud, Auto decision - verified, Client request - fraud, Client request - hacked, Client request - not fraud, Client request - verified, Manual decision - fraud, Manual decision - hacked, Manual decision - not fraud, Manual decision - verified, Bonus abuse, Emulation, Bot, Self-exclusion, VIP customer, Underage, Watch list, Payment - bank negative list, Payment - canceled subscription, Payment - chargeback, Payment - fraud alert, Payment - lost or stolen card, Payment - retrieval request, Pilot data, Test data, Third party - marketing, Third party - other
firstSeenDate	long
reputationСhangeDate	long

IP screening API

This API is used to get risk assessment of IP.

Response example

{
  "requestId": 12,
  "createdAt": 1579590089,
  "reputation": {
    "private": {
      "reputation": "trusted",
      "sources": "Test data, Pilot data",
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "global": {
      "reputation": "trusted",
      "sources": "Test data, Pilot data",
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "industries": [
      {
        "name": "charity",
        "reputation": "trusted",
        "sources": "Test data, Pilot data",
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      },
      {
        "name": "airlines",
        "reputation": "trusted",
        "sources": "Test data, Pilot data",
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      }
    ]
  },
  "ipProperties": {
    "city": "battle creek",
    "country": "usa",
    "countryLanguages": [
      "en-us",
      "en-us",
      "en",
      "es-us",
      "es-us",
      "es",
      "haw",
      "fr"
    ],
    "countryTimeZones": [
      -420,
      -600,
      -360,
      -540,
      -300,
      -480,
      -240
    ],
    "isp": "comcast cable communications inc.",
    "latitude": -85.2066,
    "longtitude": 42.2967,
    "postalCode": "49015",
    "isProxy": true,
    "proxyType": "corporate"
  },
  "screeningResult": {
    "score": 80,
    "reason": ["User 5 cards 1 day, Disposable email domain, Anonymous proxy"],
    "decision": "reject",
    "action": "Additional verification"
  }
}

Details	Description
Method	POST
Endpoint	api/makeIpScreening
Access level	Ip screening

Request fields

Field	Type	Description
IP	string	mandatory

Response fields

Field	Type	Description
requestId	long	ID of inserted data
createdAt	long	Timestamp
reputation	object	See reputation object
ipProperties	object	See ipProperties object
score	int	Calculated risk score
reason	string list	Explanation of made decision
decision	string	Possible values: accept, manual, reject
action	string	business flow for made decision

Reputation Object

Field	Type	Description
private	object	See Private and Global Object
global	object	See Private and Global Object
industries	object	See Industries Object

ipProperties Object

Field	Type	Description
city	string
country	string
countryLanguages	string list
countryTimeZones	int list
isp	string
latitude	double
longtitude	double
postalCode	string
isProxy	boolean
proxyType	string

Device fingerprint

We scan user device and grab an enormous amount of parameters, including an operating system, browser and its version, installed plug-ins, screen resolution, platform, IP address, and many others. Using the combination of these parameters, our system generates unic device fingerprint ID.

Use method device fingerprint to get your own device fingerprint pixel js. We recommend to update the pixel at least once a day, so you will be sure that you have our latest version

Details	Description
Method	GET
Endpoint	resources/device-fingerprint-js
Access level	Device fingerprint or Device screening

Device fingerprint pixel

Example of handleCoveryFpKey function

<script>
  var deviceFingerprint;
  function handleCoveryFpKey(key) {
  deviceFingerprint = key;
  // device fingerprint is stored
  // in a global variable deviceFingerprint
}
</script>

Every event contains optional fields listed below to help us investigate suspicious devices. In order to allow us handle all the work for you, please follow the next steps:

1. Use method Device fingerprint to get your own device fingerprint pixel js

2. Put received on first step device fingerprint pixel JS on your conversion page. For example: <script async src=“https://your_storage_domain/file_name.js“></script>

3. Send the device fingerprint in the field device_fingerprint, in subsequent user event

Device fields

Field	Type	Length	Description
ajax_validation	bool		presence of AJAX - Asynchronous JavaScript And XML
cookie_enabled	bool		cookie option in a web browser
cpu_class	string	255	central processing unit (CPU) of the device
device_fingerprint	string	255	unique device identifier, the "key" from js responce
device_id	string	255	mobile device identifier assigned inside the mobile app lication
do_not_track	bool		official HTTP header field, designed to allow internet users to opt-out of tracking by websites
anonymous	bool		incognito mode in a web browser
ip	string	255
real_ip	string	255	IP behind the proxy server
local_ip_list	string list	1024	list of local IP addresses connected to the device
language	string	255	user's browser language
languages	string list	1024	user's preferred languages
language_browser	string list	1024	user's operating system language
language_user	string	255	user's locale operating system language
language_system	string	255	default operating system language
os	string	255	operating system of the device
screen_resolution	string	255	resolution of the device screen
screen_orientation	string	255	orientation of the device screen
client_resolution	string	255	web browser or other application resolution that displays the web page
timezone_offset	int		current minute offset from UTC (Coordinated Universal Time) for the given time zone
user_agent	string	2048	string of user agent
plugins	string list	8192	list of installed plugins on web browser
referer_url	string	2048
origin_url	string	2048

Device screening

This API is used to get risk assessment of device.

Response example

{
  "requestId": 12,
  "createdAt": 1579590089,
  "ipReputation": {
    "private": {
      "reputation": "trusted",
      "sources": [
        "Test data",
        "Pilot data"
      ],
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "global": {
      "reputation": "trusted",
      "sources": [
        "Test data",
        "Pilot data"
      ],
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "industries": [
      {
        "name": "charity",
        "reputation": "trusted",
        "sources": [
          "Test data",
          "Pilot data"
        ],
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      },
      {
        "name": "airlines",
        "reputation": "trusted",
        "sources": [
          "Test data",
          "Pilot data"
        ],
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      }
    ]
  },
  "ipProperties": {
    "city": "battle creek",
    "country": "usa",
    "countryLanguages": [
      "en-us",
      "en-us",
      "en",
      "es-us",
      "es-us",
      "es",
      "haw",
      "fr"
    ],
    "countryTimeZones": [
      -420,
      -600,
      -360,
      -540,
      -300,
      -480,
      -240
    ],
    "isp": "comcast cable communications inc.",
    "latitude": -85.2066,
    "longtitude": 42.2967,
    "postalCode": "49015",
    "isProxy": true,
    "proxyType": "corporate"
  },
  "deviceReputation": {
    "private": {
      "reputation": "trusted",
      "sources": [
        "Test data",
        "Pilot data"
      ],
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "global": {
      "reputation": "trusted",
      "sources": [
        "Test data",
        "Pilot data"
      ],
      "firstSeenDate": 1579076134,
      "reputationСhangeDate": 1579076134
    },
    "industries": [
      {
        "name": "charity",
        "reputation": "trusted",
        "sources": [
          "Test data",
          "Pilot data"
        ],
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      },
      {
        "name": "airlines",
        "reputation": "trusted",
        "sources": [
          "Test data",
          "Pilot data"
        ],
        "firstSeenDate": 1579076134,
        "reputationСhangeDate": 1579076134
      }
    ],
    "deviceProperties": {
      "ajaxValidation": "false",
      "cookieEnabled": "true",
      "cpuClass": "554",
      "deviceFingerprint": "dvtwl9ef7d98faf03e93ff19619e19d2",
      "doNotTrack": "false",
      "ipList": [
        "192.168.1.1",
        "192.168.1.2"
      ],
      "language": "fr-fr",
      "languageBrowser": "fr-fr",
      "languageSystem": "fr-fr",
      "languageUser": "fr-fr",
      "languages": "fr-fr",
      "os": "windows 10",
      "screenOrientation": "horizontal",
      "screenResolution": "1366x768",
      "clientResolution": "674x496",
      "timezoneOffset": 60,
      "userAgent": "mozilla\/5.0 (windows nt 10.0; win64; x64) applewebkit\/537.36 (khtml, like gecko) chrome\/79.0.3945.130 safari\/537.36",
      "plugins": [
        "chrome pdf plugin",
        "native client",
        "chrome pdf viewer"
      ],
      "refererUrl": "https:\/\/hpp.covery.com",
      "originUrl": "https:\/\/hpp.covery.com"
    },
    "screeningResult": {
      "score": 80,
      "reason": [
        "User 5cards 1day",
        "Disposable email domain",
        "Anonymous proxy"
      ],
      "decision": "reject",
      "action": "Additional verification"
    }
  }
}

Details	Description
Method	POST
Endpoint	api/makeDeviceScreening
Access level	Device screening

Request fields

Field	Type	Description
device_fingerprint	string	mandatory

Response fields

Field	Type	Description
requestId	int	ID of inserted data
createdAt	int	Timestamp
ipReputation	object	See Reputation object
deviceReputation	object	See Reputation object
ipProperties	object	See ipProperties object
deviceProperties	object	See deviceProperties object
score	int	Calculated risk score
reason	string list	Explanation of made decision
decision	string	Possible values: accept, manual, reject
action	string	Business flow for made decision

deviceProperties Object

Field	Type	Description
cookieEnabled	boolean
deviceFingerprint	string
doNotTrack	boolean
ipList	string list
language	string
os	string
screenResolution	string
clientResolution	string
timezoneOffset	int	offset in minutes
userAgent	string
plugins	string list
refererUrl	string
originUrl	string

Fraud alert API

This subset of APIs is dedicated for fraud alert handling.

Fraud alert fields

Fraud alert example

{
  "id": 8464503,
  "source": "ethoca",
  "externalId": "5SNLJ1WOKODEUPLY396439RT4",
  "type": "issuer_alert",
  "state": "none",
  "cardBin": "502006",
  "cardLast4": "7616",
  "alertTimestamp": 1459521191,
  "transactionTimestamp": 1459521191,
  "transactionAmount": 28.55,
  "transactionCurrency": "USD",
  "is3dSecure": null,
  "arn": "43792622030200003292612",
  "authCode": "ab1234",
  "chargebackAmount": 0,
  "chargebackCurrency": "",
  "chargebackReasonCode": "",
  "merchantDescriptor": "EXAMPLE",
  "transactionId": "ABS123456789",
  "nodeType": "companyId",
  "nodeId": 123123
}

Field	Type	Description
id	int	Fraud alert identifier
source	string	Fraud alert source
externalId	string	External fraud alert identifier
type	string	Fraud alert type
state	string	Current fraud alert state
cardBin	string	First 6 numbers of user's credit card number
cardLast4	string	Last 4 numbers of user's credit card number
arn	string	Acquirer reference number
authCode	string	Authorization code
merchantDescriptor	string	Merchant descriptor
is3dSecure	boolean or null	Was transaction under 3D secure or not (true, false, null for unknown)
alertTimestamp	int	Alert time (Unix timestamp)
transactionAmount	float	Original transaction amount
transactionCurrency	string	Original transaction currency
transactionTimestamp	int	Original transaction time (Unix timestamp)
chargebackAmount	float	Chargeback amount
chargebackCurrency	string	Chargeback currency
chargebackTimestamp	int	Chargeback time (Unix timestamp)
transactionId	string	Transaction_id of matched event
nodeType	string	Node type of matched
nodeId	int	Node name of matched event

List of values for type field

Value	Description
empty string
issuer_alert	Confirmed fraud
fraudreporter_alert	Confirmed fraud
customerdispute_alert	Customer dispute

Confirmed fraud states

Value	Description
none	Fraud alert just received
stopped
partially_stopped
previously_cancelled
missed
notfound
account_suspended
in_progress
shipper_contacted
other

Customer dispute states

Value	Description
none	Fraud alert just received
resolved
previously_refunded
unresolved_dispute
notfound
other

Latest alerts

Use this API to receive all latest fraud alerts available for your account.

Detail	Description
Method	POST
Endpoint	api/manage/fraud/latest
Access level	Decision, Management

Request fields

Field	Type	Description
limit	int	Limit amount of entries (1-100)

Response

List of fraud alerts with the fields listed above.

Alert by ID

Use this API to receive details for particular fraud alert using its ID.

Detail	Description
Method	POST
Endpoint	api/manage/fraud/find
Access level	Decision, Management

Request fields

Field	Type	Description
id	int	Identifier of fraud alert

Response

Single fraud alert with the fields listed before.

Alert confirmation

Use this API to confirm retrieval of fraud alerts.

Detail	Description
Method	POST
Endpoint	api/manage/fraud/confirm
Access level	Decision

Request fields

Field	Type	Description
id	int	Identifier of fraud alert

Response

Empty response.

Alert feedback

Use this API to process received fraud alerts.

Detail	Description
Method	POST
Endpoint	api/manage/fraud/feedback
Access level	Management

Request fields

Field	Type	Description
id	int	Identifier of fraud alert
result	string	See Confirmed fraud and Customer dispute states
refunded	string	none, refunded, not_refunded, not_settled

Response

Empty response.

Alert callback

If it is configured, Covery will send callback for every incoming fraud alert to the defined URL.

Callback contains fraud alert details (same as get fraud alert by ID) with the following headers:

Type	Description
X-Auth-Nonce	Signature salt
X-Auth-Signature	Callback signature

$signature = $hash = hash('sha256', $nonce . $body . $secret);

Callback signature is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was sent to you during the configuration process.

If you have any questions or need an assistance, please contact us.

Top-Level Object

Field	Type		Description
arn	string	mandatory, if was present in request	Acquirer Reference Number associated with settled transactions, Max Length 23
orderId	string	mandatory, if was present in request	Merchant-created unique value that references the cardholders purchase request
orderDate	int	mandatory, if was present in request	Date of the order
paymentDescriptor	string	mandatory, if was present in request	Merchant payment descriptor found on the cardholder’s bank statement, Max Length 25
authorizationCode	string	mandatory, if was present in request	Authorization code for the transaction
authorizationDate	int	mandatory, if was present in request	Authorization date of the transaction
authorizationCurrency	string	mandatory, if was present in request	Authorization currency for the transaction
authorizationAmount	float	mandatory, if was present in request	Authorization amount of the transaction
settlementDate	int	mandatory, if was present in request	Settlement date of the transaction
settlementCurrency	string	mandatory, if was present in request	Settlement currency for the transaction
settlementAmount	float	mandatory, if was present in request	Settlement amount of the transaction
creditCardBin	int	mandatory, if was present in request	First 6 digits (BIN) of the credit card used for the transaction
creditCardLast4	string	mandatory, if was present in request	Last 4 digits of the credit card used for the transaction
details	object		Details Object

Details Object

Field	Type	Description
transactionDetail	object	Transaction Detail Object
customerInformation	object	Customer Information Object
pastTransactions	object list	Past Transactions Object
productPurchased	object list	Product Purchased Object
customFields	object list	Custom Fields Object
deliveryDetails	object	Delivery Details Object
crmDetails	object list	CRM Details Object
attachments	object list	Attachments Object

Transaction Detail Object

Field	Type	Description
taxAmount	float list	Tax amount(s) charged on the transaction
taxAmountCurrency	string list	Tax amount currency(ies) for the transaction. The number of tax amounts must be equal to the number of tax currencies.
shippingAndHandlingAmount	float list	Shipping and handling amount(s) for the purchase
shippingAndHandlingCurrency	string list	Shipping and handling currency(ies) for the purchase. The number of shipping and handling amounts must be equal to the number of shipping and handling currency(ies).
totalAmount	float	Total amount of the transaction, including purchase price, tax, and shipping and handling
totalAmountCurrency	string	Total amount currency for the transaction
recurringTransaction	string	If recurring transactions, state frequency for recurring period, eg. month on 25th, every 4 weeks, annually on May15, etc
paymentInstrument	string	Card type – Visa, MC, AMEX or Discover
billingAddress	string	Customer’s billing address – if billing address is not collected then indicate “billing address not collected”
shippingAddress	string list	Address(es) listed for associated delivery
billingAddressDetails	object	Address Object
shippingAddressDetails	object list	Address Object
avsChecked	boolen	Whether credit card AVS response was received
avsResultCode	string	AVS response code received – provide the code and description e.g., Y – exact match or A – zip match only
cvvChecked	boolen	Whether credit card CVV code was checked
cvvResultCode	string	CVV response code received – provide the code and description e.g., M – match or N – no match
threeDSHallenged	boolen	Whether there was a 3DSecure attempt from the merchant
threeDSEciCode	string	Two-digit code indicating the outcome of the 3DSecure attemp. Max Length 2
threeDSTransactionId	string	Transaction identifier resulting from 3DSecure call (xid)
threeDSAuthenticationValue	string	Cardholder Authentication Verification. Value resulting from completion of 3DSecure (cavv)
refundProcessed	boolen	True if a refund was processed
refundAmount	float	Refund amount, if applicable
refundCurrency	string	Refund currency
dateOfRefund	int	Date of refund. If multiple, provide the most recent date of refund
registeredCustomer	boolen	True if the customer is registered with the merchant.
deviceName	string	Name of device used to submit order (e.g., John’s iphone or John’s desktop)
deviceId	string	Device ID that was used to place order
deviceLocation	string	Location of device at the time of the order (city, state, country)
ipAddress	string	IP address associated with the device
orderChannel	string	Identifies how the order was submitted: web, physical store, mobile, etc
orderLocation	string	Location of order: GPS coordinates, friendly location, city name, street address, etc.
paymentTerms	string	The seller’s payment terms (Merchant Link)
refundPolicy	string	The seller’s refund policy (Merchant Link)
warrantyTerms	string	The seller’s warranty terms (Merchant Link)
termsAndConditions	string	The seller’s terms and conditions (Merchant Link)
notes	string	Any seller notes

Customer Information Object

Field	Type	Description
firstName	string	Customer’s first name
lastName	string	Customer’s last name
dateOfBirth	int	Customer’s date of birth
customerId	string	Unique customer ID with merchant
firstTransactionDate	int	Date of customer’s first transaction
lengthOfRelationship	string	Length of customer relationship: 5 years, 3 months, etc.
authenticationUsed	string	Authentication completed by customer to begin subscription: driver’s license, facebook profile, etc.
notes	string	Any notes associated with the customer
phoneNumber	object list	Phone Number Object
emailAddress	object list	Email Address Object

Address Object

Field	Type	Description
address	string list	Street address plus additional address lines such as suite number, apartment, etc.
city	string	City
state	string	State
zip	string	Zip or postal code
country	string	Country, ISO ALPHA,-3 format, e.g. usa

Phone Number Object

Field	Type	Description
phoneType	string	Customer’s phone type: home, work, etc
phoneNumber	string	Customer’s phone number

Email Address Object

Field	Type	Description
emailName	string	Customer’s email name: personal, work
emailAddress	string	Customer’s email address

Past Transactions Object

Field	Type	Description
dateOfPurchase	int	Date of past transaction
currencyOfPurchase	string	Currency of past transaction
amountOfPurchase	float	Amount of past transaction
creditCardBin	int list	First 6 digits (BIN) of the credit card used for the transaction
creditCardLastFour	string list	Last 4 digits of the credit card used for the transaction
orderId	string list	Merchant-created unique value that references the cardholders purchase request
transactionId	string	Transaction id
transactionType	string	Sale or Refund
recurringTransaction	string	If recurring transactions, state frequency for recurring period, eg. month on 25th, every 4 weeks, annually on May15, etc.

Product Purchased Object

Field	Type	Description
productName	string	The product name
productModel	string	The product model
productSku	string	The product SKU (item ID)
productDescription	string	The product description – use as much detail as possible
productUrl	string	URL to product purchase site
productImageUrl	string	URL to product image
unitPriceCurrency	string	Unit price currency for the product
unitPriceAmount	float	Unit price amount of the product
quantity	int	Number of products purchased
notes	string	Any notes associated with the purchase
industryDetails	object	Industry Details Object

Custom Fields Object

Field	Type	Description
<name>	string	Custom field naming to present to Issuers. Up to 10. Max Length 500
<value>	string	Content associated with the custom field name provided. Up to 10. Max Length 500

Delivery Details Object

Field	Type	Description
physicalFulfillment	object list	Physical Fulfillment Object
digitalServiceDelivery	object list	Digital Service Delivery Object

Physical Fulfillment Object

Field	Type	Description
shippingCarrierUrl	string	Shipper’s URL
shippingCarrierPhone	string	Shipper’s phone number
trackingNumber	string	Shipper’s tracking number
dateOfShipment	int	Shipper’s date of shipment
dateOfDelivery	int	Shipper’s date of delivery
signatureConfirmation	string	Signature confirming shipment arrival
signedBy	string	Name of individual signing to confirm arrival of merchandise
exceptionNotes	string	Notes specific to any delivery fulfillment (Example: wrong email, wrong address, signature required, etc.)
notes	string	Delivery notes specific to customer interaction

Digital Service Delivery Object

Field	Type	Description
proofOfDelivery	string	Evidence the digital product/service is available to customer (Example: downloads, activation email, etc.)
proofOfUsage	string	Evidence the customer interacted with the product/service (Login, and time of use, etc.)
locationOfUsage	string	Location or IP address of device at the time of last usage
frequencyOfUsage	string	Number of times the service was accessed/used
notes	string	Any customer notes associated with digital goods/services

CRM Details Object

Field	Type	Description
dateOfInteraction	int	Date of customer contact
contactMethod	string	Email, mail, chat, phone
merchantAgentUser	string	Name of customer service agent interacting with the customer
contactName	string	Consumer Name
ipAddress	string	IP Address during contact
emailAddress	object	Email Address Object
phoneNumber	object	Phone Number Object
deviceName	string	Name of device used to make contact
deviceId	string	Device ID that was used during contact
deviceLocation	string	Location of device at the time pf contact
communicationInitator	string	Consumer or Merchant
communicationType	string	Order Confirmation, Shipping Confirmation, Notice of Renewal
communicationStatus	string	If email, was email bounced back, viewed, opened, etc
notes	string	Details of customer contact – this could include details like “customer called to check on status of order” or “customer submitted chat request with questions on accessing site” and include details of resolution by merchant. If no contact from customer then must include “customer has not contacted us at this time”

Industry Details Object

Field	Type	Description
flightDetails	object	Flight Details Object
hotelDetails	object	Hotel Details Object
flightNumber	string	Flight number
flightDate	int	Date of flight
manifest	string	Flight manifest information
memberRewardsNumber	string	Member rewards number
pointsRedeemed	boolen	Did consumer use reward points towards purchase

Flight Details Object

Field	Type	Description
flightNumber	string	Flight number
flightDate	int	Date of flight
manifest	string	Flight manifest information
memberRewardsNumber	string	Member rewards number
pointsRedeemed	boolen	Did consumer use reward points towards purchase

Hotel Details Object

Field	Type	Description
reservationNumber	string	Reservation number
reservationDate	int	Date reservation was made
checkInDate	int	Check in Date
checkOutDate	int	Check out Date
memberRewardsNumber	string	Member rewards number
pointsRedeemed	boolen	Did consumer use reward points towards purchase?

Attachments Object

Field	Type		Description
id	string		Merchant’s ID for the document
fileName	string	mandatory	Attachment file name
friendlyFileName	string		Friendly file name that will override file naming convention if entered
mimeType	string	mandatory	MIME Content Type
receivedDate	int		Date file was received by merchant
fileSource	string		Source of the file – uploaded by customer, generated by merchant, merchant contract
data	string	mandatory	File attachment content, BASE64 encoded

Compelling evidence API

CE provides merchants the ability to share transaction details with Visa and bank Issuer during chargeback pre disputing process. This information is then used by the Visa and Issuer to prevent friendly fraud.

CE Callback

Have a JSON encoded body and following headers:

Header		Description
X-Auth-Token	mandatory	Must be provided by Covery customer
X-Auth-Nonce	mandatory	Random unique string, used as salt in packet signature
X-Auth-Signature	mandatory	It is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (in case it was provided by Covery customer)

Callback fields

Field	Type		Description
requestId	long	mandatory	Internal Covery alert ID
date	long	mandatory	Unix timestamp in seconds, date when Covery received the request
insightId	string	mandatory
partnerId	int	mandatory
clientId	int
requestSource	string	mandatory
requestCardBin	int
requestCardLast4	string
requestCardBinBrand	string	mandatory
requestCardFingerprint	string
requestMerchantDescriptor	string	mandatory
requestMerchantContact	string	mandatory
requestTransactionDate	long	mandatory	Unix timestamp in seconds
requestAuthorizationAmount	float	mandatory
requestAuthorizationCurrency	string	mandatory
requestSettlementAmount	float
requestSettlementCurrency	string
requestArn	string
requestAuthCode	string
requestTerminalId	string
requestAcquirerBin	string
requestCardAcceptorId	string
requestMcsn	string
requestPurchaseId	string
requestTransactionId	string
requestTransactionType	string
requestCardExpirationDate	string
requestMcc	string
requestPosEntryModeCode	string
requestEci	string
requestTransactionRequestId	string	mandatory
requestLinkedInsightId	string
nodeType	string		Value of field nodeType that was used for matching CE request with transaction
nodeId	string		Value of field nodeId that was used for matching CE request with transaction
matchedTransactionId	string		Value of field transactionId for the envelope we have matched CE request

CE Notification

When Covery received CE Notification and matched it to the original CE request, we can send notification with the same header to the same endpoint as for CE Callback

Notification fields

Field	Type		Description
requestId	long	mandatory	Internal Covery alert ID
date	long	mandatory	Unix timestamp in seconds, date when Covery received the request
insightId	string	mandatory
requestLinkedInsightId	string
partnerId	int	mandatory
clientId	int
requestSource	string	mandatory
nodeType	string	mandatory	Value of field nodeType that was used for matching CE request with transaction
nodeId	string	mandatory	Value of field nodeId that was used for matching CE request with transaction
matchedTransactionId	string	mandatory	Value of field transactionId for the envelope we have matched CE request
notificationStatus	string	mandatory	Notification status can have next values: successful, disputed by bank, disputed by Visa, timeout, error
notificationDate	long	mandatory	Unix timestamp in seconds, date when Covery have received the notification