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

Level	Allow event	Allow decision	Allow administration
event	yes	no	no
decision	yes	yes	no
utility	no	no	read only
management	no	no	yes

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.

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

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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	See event merge
age	int
country	string		ISO ALPHA-3 format, e.g. usa
email	string
firstname	string
lastname	string
gender	string
phone	string
social_type	string
user_name	string
website_url	string
traffic_source	string
affiliate_id	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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	See event merge
login_failed	bool
email	string
phone	string
gender	string
traffic_source	string
affiliate_id	string

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
transaction_id	string	mandatory
transaction_timestamp	int	mandatory
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	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
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
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

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
refund_id	string	mandatory
sequence_id	string(40)	mandatory	See event merge
refund_amount	float	mandatory
refund_currency	string	mandatory
refund_amount_converted	float		If not sent, will be converted to base currency of your account
user_merchant_id	string
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
payout_id	string	mandatory
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	See event merge
payout_amount	float	mandatory
payout_currency	string	mandatory
payout_amount_converted	float		If not sent, will be converted to base currency of your account
payout_method	string
payout_system	string
payout_mid	string
payout_account_id	string
payout_card_id	string
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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	See event merge
account_system	string	mandatory
account_id	string	mandatory
second_account_id	string	mandatory
amount	float	mandatory
currency	string	mandatory
amount_converted	float		If not sent, will be converted to base currency of your account
operation	string
source	string
firstname	string
lastname	string
fullname	string
email	string
phone	string
birth_date	int
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_email	string
second_phone	string
second_birth_date	int
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 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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	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
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
industry	string
website_url	string
description	string		E.g. clarification of industry or document details
birth_date	int
reg_date	int
reg_number	string
vat_number	string
email	string
email_confirmed	bool
phone	string
phone_confirmed	bool
country	string		ISO ALPHA-3 format, e.g. usa
state	string
city	string
address	string
zip	string
second_country	string		ISO ALPHA-3 format, e.g. usa
second_state	string
second_city	string
second_address	string
second_zip	string
related_profiles	string list		List of profile_id for related profiles

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
user_merchant_id	string	mandatory
sequence_id	string(40)	mandatory	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 a mandatory 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.

Device fingerprinting

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
cookie_enabled	bool
cpu_class	string
device_fingerprint	string
device_id	string		Identifier of mobile device
do_not_track	bool
ip	string
real_ip	string
local_ip_list	string list
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
screen_resolution	string
screen_orientation	string
client_resolution	string
timezone_offset	int		offset in minutes
user_agent	string
plugins	string list
referer_url	string
origin_url	string

Response

Response example

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

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

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"
}

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

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 transaction data after transaction 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

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.