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.

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 customer token levels:

Level	Permission
event	sendEvent and nodeName
decision	sendEvent, makeDecision and nodeName
management	covery portal
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 auth headers missing, or invalid auth token, or invalid auth signature
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
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

Health check API

Response example

{
  "customerId": 1,
  "access":
  {
    "event": true,
    "decision": false,
    "management": false,
    "utility": false
  }
}

Covery API status can be checked by sending ping request:

Detail	Description
Method	POST
Endpoint	api/ping
Access level	Any

Returns JSON with the information about granted access level for the used token.

If any issues are noticed, please check the system status and contact us ASAP.

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

Event API

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

Detail	Description
Method	POST
Endpoint	api/sendEvent
Access level	Event

Install

Request fields

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

Implement device fingerprinting to investigate suspicious devices.

Registration

Request fields

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

Implement device fingerprinting to investigate suspicious devices.

Confirmation

Request fields

Field	Type		Description
type	string	mandatory	Value has to be confirmation
confirmation_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory
sequence_id	string(40)		See event merge
email	string
phone	string
email_confirmed	bool
phone_confirmed	bool

Implement device fingerprinting to investigate suspicious devices.

Login

Request fields

Field	Type		Description
type	string	mandatory	Value has to be login
login_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory
sequence_id	string(40)		See event merge
login_failed	bool
email	string
password	string		Encrypted user password
phone	string
gender	string
traffic_source	string
affiliate_id	string
campaign	string

Implement device fingerprinting to investigate suspicious devices.

Order item

Request fields

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

Implement device fingerprinting to investigate suspicious devices.

Order submit

Request fields

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

Implement device fingerprinting to investigate suspicious devices.

Transaction

Request fields

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

Implement device fingerprinting to investigate suspicious devices.

Refund

Request fields

Field	Type		Description
type	string	mandatory	Value has to be refund
refund_timestamp	int	mandatory	Unix timestamp in seconds
refund_id	string	mandatory
refund_amount	float	mandatory
refund_currency	string	mandatory	ISO ALPHA-3 format, e.g. usd
refund_amount_converted	float		If not sent, will be converted to base currency of your account
user_merchant_id	string
sequence_id	string(40)		See event merge
email	string
phone	string
refund_method	string
refund_system	string
refund_mid	string
refund_source	string
refund_type	string		E.g. full, partial
refund_code	string		Reason code why refund issued
refund_reason	string		Reason why refund issued
agent_id	string		Person who issued refund

Implement device fingerprinting to investigate suspicious devices.

Payout

Request fields

Field	Type		Description
type	string	mandatory	Value has to be payout
payout_timestamp	int	mandatory	Unix timestamp in seconds
payout_id	string	mandatory
user_merchant_id	string	mandatory
payout_amount	float	mandatory
payout_currency	string	mandatory	ISO ALPHA-3 format, e.g. usd
payout_amount_converted	float		If not sent, will be converted to base currency of your account
sequence_id	string(40)		See event merge
payout_method	string
payout_system	string
payout_mid	string
payout_account_id	string
payout_card_id	string		See card id generation
firstname	string
lastname	string
country	string		ISO ALPHA-3 format, e.g. usa
email	string
phone	string
payout_card_bin	int
payout_card_last4	string
payout_expiration_month	int
payout_expiration_year	int

Implement device fingerprinting to investigate suspicious devices.

Transfer

Request fields

Field	Type		Description
event_type	string	mandatory	Value has to be transfer
event_id	string	mandatory
event_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory
account_system	string	mandatory
account_id	string	mandatory
second_account_id	string	mandatory
amount	float	mandatory
currency	string	mandatory	ISO ALPHA-3 format, e.g. usd
amount_converted	float		If not sent, will be converted to base currency of your account
sequence_id	string(40)		See event merge
operation	string
transfer_source	string
firstname	string
lastname	string
fullname	string
bic	string		SWIFT code
iban	string
email	string
phone	string
birth_date	int		Unix timestamp in seconds
gender	string
country	string		ISO ALPHA-3 format, e.g. usa
state	string
city	string
address	string
zip	string
second_firstname	string
second_lastname	string
second_fullname	string
second_iban	string
second_email	string
second_phone	string
second_birth_date	int		Unix timestamp in seconds
second_gender	string
second_country	string		ISO ALPHA-3 format, e.g. usa
second_state	string
second_city	string
second_address	string
second_zip	string
product_name	string
product_description	string
product_quantity	float

Implement device fingerprinting to investigate suspicious devices.

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.

Request fields

Feature name	Type		Description
type	string	mandatory	Value has to be kyc_start
event_id	string	mandatory
event_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory	string
verification_mode	string	mandatory	Possible values: any, image, video
verification_source	string	mandatory	Possible values: any, online, offline
consent	bool	mandatory
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(40)		See event merge
group_id	string(40)		See event merge
country	string		ISO ALPHA-3 format, e.g. usd
kyc_language	string		ISO ALPHA-2 format, e.g. en
redirect_url	string(256)
email	string
firstname	string
lastname	string
profile_id	string
phone	string
birth_date	int		Unix timestamp in seconds
reg_number	string
issue_date	int		Unix timestamp in seconds
expiry_date	int		Unix timestamp in seconds

Implement device fingerprinting to investigate suspicious devices.

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		Description
event_type	string	mandatory	Value has to be kyc_profile
event_id	string	mandatory
event_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory
sequence_id	string(40)		See event merge
group_id	string(40)		See event merge
status	string		Profile status
code	string
reason	string
provider_id	string		KYC provider event id
provider_result	string		Result from third-party provider
provider_code	string
provider_reason	string
profile_id	string		Profile ID
profile_type	string		Profile type e.g. person, company or document
profile_sub_type	string		Profile subtype e.g. company or document type
firstname	string
lastname	string
fullname	string		Can be also used to send company name
gender	string
industry	string
wallet_type	string
website_url	string
description	string		E.g. clarification of industry or document details
final_beneficiary	bool
employment_status	string
source_of_funds	string
birth_date	int		Unix timestamp in seconds
reg_date	int		Unix timestamp in seconds
issue_date	int		Unix timestamp in seconds
expiry_date	int		Unix timestamp in seconds
reg_number	string
vat_number	string
email	string
email_confirmed	bool
phone	string
phone_confirmed	bool
contact_email	string
contact_phone	string
country	string		ISO ALPHA-3 format, e.g. usa
state	string
city	string
address	string
zip	string
nationality	string
second_country	string		ISO ALPHA-3 format, e.g. usa
second_state	string
second_city	string
second_address	string
second_zip	string

Implement device fingerprinting to investigate suspicious devices.

KYC submit

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

Request fields

Field	Type		Description
event_type	string	mandatory	Value has to be kyc_submit
event_id	string	mandatory
event_timestamp	int	mandatory	Unix timestamp in seconds
user_merchant_id	string	mandatory
sequence_id	string(40)		See event merge
group_id	string(40)		See event merge
status	string		Profile status
code	string
reason	string
provider_result	string		Result from third-party provider
provider_code	string
provider_reason	string

Implement device fingerprinting to investigate suspicious devices.

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.123,
  "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",
  "note": "Customer verified manually",
  "verificationUrl": "https://covery.ai/comics"
}

Response fields

Field	Type	Description
requestId	int	ID of inserted data
type	string	type from request
createdAt	float	timestamp
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
note	string	for manual decision only
verificationUrl	string	for KYC Start only

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	Description
request_id	int	mandatory if no transaction_id present
transaction_id	string	mandatory if no request_id present
transaction_status	string
code	string
reason	string
secure3d	string
avs_result	string
cvv_result	string
psp_code	string
psp_reason	string
arn	string

Response fields

Field	Type
requestId	int

Card ID API

This method allows to generate unique sustainable ID of the card for customers who are not PCI DSS compliant. The service is provided in cooperation with our partner Maxpay that is PCI DSS level 1 compliant. Card ID would be generated only for valid card number.

API endpoint: https://gateway.maxpay.com/api/cc

Request fields

Field	Type		Description
api_version	int	mandatory	Value has to be 1
merchant_account	string	mandatory	Provided by Covery specialist
merchant_password	string	mandatory	Provided by Covery specialist
transaction_type	string	mandatory	Value has to be CARD_HASH
card_number	string	mandatory	Full number of card

Response

Response example

{
  "requestId": 7896010,
  "type": "transaction",
  "createdAt": 1449049571.123,
  "secureStorageId": "5aaaa194f3baaaaade427",
  "merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b"
}

Field	Type	Description
requestId	int	ID of inserted data
type	string	type from request
createdAt	float	timestamp
secureStorageId	string	use as card_id or as payout_card_id
merchantUserId	string	user_merchant_id from request

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	int	ID of inserted data
createdAt	int	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	int
reputationСhangeDate	int

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	int
reputationСhangeDate	int

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	int	ID of inserted data
createdAt	int	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, inluding 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.

In order to use device fingerprint pixel, you must provide the URL, on which it will be placed, or use the method of dynamic pixel generation. Dynamic pixel will be valid for a seconds and can be placed on any page without URL whitelisting from Covery side.

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

Response will contains one time valid js script.

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. Include <script async src=“https://api.covery.ai/resources/covery.js“></script> on the destination page

2. Define function handleCoveryFpKey and covery.js will call it with the device fingerprint as argument

3. Send the device fingerprint in the device_fingerprint field

Device fields

Field	Type		Description
ajax_validation	bool		presence of AJAX - Asynchronous JavaScript And XML
cookie_enabled	bool		cookie option in a web browser
cpu_class	string		central processing unit (CPU) of the device
device_fingerprint	string		unique device identifier, the "key" from js responce
device_id	string		mobile device identifier assigned inside the mobile application
do_not_track	bool		incognito mode in a web browser
ip	string
real_ip	string		IP behind the proxy server
local_ip_list	string list		list of local IP addresses connected to the device
language	string		user's browser language
languages	string		user's preferred languages
language_browser	string		user's operating system language
language_user	string		user's locale operating system language
language_system	string		default operating system language
os	string		operating system of the device
screen_resolution	string		resolution of the device screen
screen_orientation	string		orientation of the device screen
client_resolution	string		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		string of user agent
plugins	string list		list of installed plugins on web browser
referer_url	string
origin_url	string

Device screening API

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",
  "chargebackAmount": 0,
  "chargebackCurrency": "",
  "chargebackReasonCode": "",
  "merchantDescriptor": "EXAMPLE"
}

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
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)

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.

VMPI API

OI provides merchants the ability to share transaction details with the Issuer for charges that questioned by the cardholder. This information is then used by the issuer in their communication with the cardholder in an attempt to resolve the customer’s needs without initiating a chargeback.

Requests

Request must have a JSON encoded body and following headers:

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

Request fields

Field	Type		Description
requestId	int	mandatory	internal Covery alert ID
sellerID	string	mandatory
arn	string		Acquirer Reference Number associated with settled transactions
settlementAmount	double		settlement amount of the transaction
settlementCurrency	string		settlement currency for the transaction
settlementDate	int		settlement date of the transaction, unix timestamp
creditCardBin	int		first 6 digits (BIN) of the credit card used for the transaction
creditCard4	string		last 4 digits of the credit card used for the transactio
authorizationAmount	double		authorization amount of the transaction
authorizationCurrency	string		authorization currency for the transaction
authorizationDate	int		authorization date of the transaction, unix timestamp
authorizationCode	string		authorization code for the transaction
orderId	string		merchant-created unique value that references the cardholders purchase request
transactionId	string
nodeType	string
nodeId	string

Response

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

Custome 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