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":
  {
    "events": 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 merger
country string ISO ALPHA-3 format, e.g. usa
website_url string
traffic_source string
affiliate_id string

Optional device data can 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 event merger
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 data can 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 event merger
email string
phone string
email_confirmed bool
phone_confirmed bool

Optional device data can 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 event merger
login_failed bool
email string
phone string
gender string

Optional device data can be used.

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

Optional device data can be used.

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 merger
refund_amount float mandatory
refund_currency string mandatory
refund_amount_converted float If not sent, will be converted to base currency of your account
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

Optional device data can 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
sequence_id string(40) mandatory See event merger
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

Optional device data can be used.

Event merger

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

Device data

Each Event 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
device_id string Identifier of mobile device
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

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,
  "trustList": 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
trustList bool decision made using Trust List
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.