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