NAV


Welcome to Covery REST API documentation.

Covery is your personal adviser to solve fraud. Powered by Maxpay.

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

Introduction

Base API Endpoint

https://covery.maxpay.com

Encoding

API uses UTF-8 character encoding.

Authorization

Access tokens

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

Example
Access token 21a3358f36e5af968b75357590b75c28
Secret eNfrVfsXQtI+yCIQ9XmuKYP5yBjK0ip7

Token levels

There are four customer token levels:

Level Allow events Allow decision Allow administration
events 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 Events 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

HTTP response 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. Contact admins ASAP
509 Too many requests
510 Failed to build Covery application using dependency injection config. Antifraud not operational, contact admins ASAP.

Health check API

Example response:

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

Covery API status can be checked by sending ping request.

Method POST
Endpoint api/ping
Access level any

Returns JSON with information about access level, granted to access token.

Events API

Use Events API to record user actions on your site.

Method POST
Endpoint api/sendEvent
Access level Events

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 merge of events
country string ISO ALPHA-3 format, e.g. usa
website_url string
traffic_source string
affiliate_id string

Optional device info fields may be used.

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 merge of events
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

Optional device info fields may be used.

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 merge of events
email string
phone string
email_confirmed bool
phone_confirmed bool

Optional device info fields may be used.

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 merge of events
email string
login_failed bool
phone string

Optional device info fields may be used.

Transaction

Request fields

Field Type Description
type string mandatory Value has to be transaction
card_bin int mandatory
card_id string mandatory
card_last4 string mandatory
expiration_month int mandatory
expiration_year int mandatory
transaction_amount float mandatory
transaction_currency string mandatory
transaction_id string mandatory
transaction_mode string mandatory
transaction_timestamp int mandatory
transaction_type string mandatory
user_merchant_id string mandatory
sequence_id string(40) mandatory see merge of events
age int
billing_address string
billing_city string
billing_country string ISO ALPHA-3 format, e.g. usa
billing_fullname string
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
payment_method string
payment_mid string
payment_system string
phone string
product_description string
product_name string
product_quantity float
transaction_amount_converted float
user_name string
website_url string
transaction_source string

Optional device info fields may be used.

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
payout_card_id string mandatory
payout_amount float mandatory
payout_currency string mandatory
sequence_id string(40) mandatory see merge of events
payout_method string
payout_system string
payout_mid string
payout_amount_converted float
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

Optional device info fields may be used.

Merge of events

sequence_id is a mandatory field in all events. It is used to associate consecutive user actions on your site for more precise decisions. Use the same user identifier as in user_merchant_id. If there is a business need to split user actions on different sites, use sha256 hash, calculated using concatenation of user_merchant_id and a site identifier.

Device info fields

Each Events API request contains optional fields listed below. Provide maximum available fields for more precise decisions.

Request fields

Field Type Description
ajax_validation bool
cookie_enabled bool
cpu_class string
device_fingerprint string
do_not_track bool
ip string
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
real_ip string
screen_resolution string
screen_orientation string
timezone_offset int offset in minutes
user_agent string

Response fields

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 fraud assessment for a particular event.

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,
  "secure3d": false,
  "trustList": false,
  "reason": "User 5 cards 1 day, Disposable email domain, Anonymous proxy"
}

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
secure3d bool transaction sent to 3D Secure
trustList bool decision made using Trust List
reason string explanation of made decision

Postback API

Request example for cases, when request_id known:

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

Request example for cases, when only transaction_id 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 used to supply additional transaction data after transaction processing

Method POST
Endpoint api/postback
Access level Events

Request fields

Field Type
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 API dedicated for fraud alert notification handling

All fraud alerts are delivered using an object with following fields:

Fraud alert information

Structure example

{
  "id": 8464503,
  "source": "ethoca",
  "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
id int Fraud alert identifier
source string Fraud alert source
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 common values for type field

Fraud alert states

Value Description
none Fraud alert just received
resolved Marked as resolved
previously_refunded Marked as previously refunded
unresolved_dispute Marked as unresolved dispute
notfound Marked as not found
other

Latest alerts retrieval

Use this API request to read all latest fraud alerts, available for your account

Method POST
Endpoint api/manage/fraud/latest
Access level Decision or Management

Request fields

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

Response

List of fraud alerts

Get fraud alert by id

Method POST
Endpoint api/manage/fraud/find
Access level Decision or Management

Request fields

Field Type
id int Identifier of fraud alert

Response

Single fraud alert

Alert retrieval confirmation

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

Request fields

Field Type
id int Identifier of fraud alert

Response

Empty response

Alert feedback

Method POST
Endpoint api/manage/fraud/confirm
Access level Management

Request fields

Field Type
id int Identifier of fraud alert
id result Fraud alert result (same as state)

Response

Empty response

Fraud alert realtime callback

If configured, Covery will send callback for every incoming fraud alert event to customer’s URL

Callback will contain fraud alert information (same as get fraud alert by id) with following headers:

Header Description
X-Auth-Nonce Signature salt
X-Auth-Signature Callback signature
$signature = $hash = hash('sha256', $nonce . $body . $secret);

Signature for callback calculated as sha256 checksum from concatenated salt(X-Auth-Nonce), request body and secret (which was sent to you during configuration process)