Covery website uses cookies to deliver the best service to you.
If you continue to browse the website or close this message, you consent to the use of cookies

    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.

    For your convenience, we have also prepared a PHP Client.

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

    Level Permission
    event sendEvent, nodeName and cardId
    decision sendEvent, makeDecision, nodeName, cardId and clientManagement
    media mediaStorage
    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.

    Download Postman collection

    Detail Description
    Method POST
    Endpoint api/sendEvent
    Access level Event

    Install

    Download Postman Install

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Registration

    Download Postman Registration

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Confirmation

    Download Postman Confirmation

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be confirmation
    confirmation_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    email string 255
    phone string 255
    email_confirmed bool
    phone_confirmed bool
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    Login

    Download Postman Login

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Order item

    Download Postman Order Item

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Order submit

    Download Postman Order Submit

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Transaction

    Download Postman Transaction

    Request fields

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

    Implement device fingerprinting to investigate suspicious devices.

    Refund

    Download Postman Refund

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be refund
    refund_timestamp int mandatory Unix timestamp in seconds
    refund_id string 255 mandatory
    refund_amount float mandatory
    refund_currency string 255 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 255
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    email string 255
    phone string 255
    refund_method string 255
    refund_system string 255
    refund_mid string 255
    refund_source string 255
    refund_type string 255 E.g. full, partial
    refund_code string 255 Reason code why refund issued
    refund_reason string 255 Reason why refund issued
    agent_id string 255 Person who issued refund
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    Payout

    Download Postman Payout

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be payout
    payout_timestamp int mandatory Unix timestamp in seconds
    payout_id string 255 mandatory
    user_merchant_id string 255 mandatory
    payout_amount float mandatory
    payout_currency string 255 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 255 See event merge
    group_id string 255 See event merge
    payout_method string 255
    payout_system string 255
    payout_mid string 255
    payout_account_id string 255
    payout_card_id string 255 See card id generation
    firstname string 255
    lastname string 255
    country string 255 ISO ALPHA-3 format, e.g. usa
    email string 255
    phone string 255
    payout_card_bin int
    payout_card_last4 string 4
    payout_expiration_month int
    payout_expiration_year int
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    Transfer

    Download Postman Transfer

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be transfer
    event_id string 255 mandatory
    event_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory
    amount float mandatory
    currency string 255 mandatory ISO ALPHA-3 format, e.g. usd
    account_system string 255
    account_id string 255
    second_account_id string 255
    amount_converted float If not sent, will be converted to base currency of your account
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    operation string 255
    transfer_source string 255
    firstname string 255
    lastname string 255
    fullname string 512
    bic string 255 SWIFT code
    iban string 255
    email string 255
    phone string 255
    birth_date int Unix timestamp in seconds
    gender string 255
    country string 255 ISO ALPHA-3 format, e.g. usa
    state string 255
    city string 255
    address string 255
    zip string 255
    second_user_merchant_id string 255
    second_firstname string 255
    second_lastname string 255
    second_fullname string 512
    second_iban string 255
    second_email string 255
    second_phone string 255
    second_birth_date int Unix timestamp in seconds
    second_gender string 255
    second_country string 255 ISO ALPHA-3 format, e.g. usa
    second_state string 255
    second_city string 255
    second_address string 255
    second_zip string 255
    product_name string 255
    product_description string 1024
    product_quantity float
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    Profile update

    Download Postman Profile Update

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be profile_update
    event_id string 255 mandatory
    event_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    operation string 255 What exactly was changed. For example: password updated, limit updated
    account_id string 255
    currency string 255 ISO ALPHA-3 format, e.g. usd
    phone string 255
    phone_confirmed bool
    email string 255
    email_confirmed bool
    contact_email string 255
    contact_phone string 255
    2fa_allowed bool
    user_name string 255
    password string 255 Encrypted user password
    social_type string 255
    game_level string 255
    firstname string 255
    lastname string 255
    fullname string 512
    birth_date int Unix timestamp in seconds
    age int
    gender string 255
    marital_status string 255
    nationality string 255
    physique string 255
    height float decimal(5,2)
    weight float decimal(5,2)
    hair string 255
    eyes string 255
    education string 255
    employment_status string 255
    source_of_funds string 255
    industry string 255
    final_beneficiary bool
    wallet_type string 255
    website_url string 255
    description string 1024
    country string 255 ISO ALPHA-3 format, e.g. usa
    state string 255
    city string 255
    zip string 255
    address string 255
    address_confirmed bool
    second_country string 255 ISO ALPHA-3 format, e.g. usa
    second_state string 255
    second_city string 255
    second_zip string 255
    second_address string 255
    second_address_confirmed bool
    profile_id string 255
    profile_type string 255
    profile_sub_type string 255
    document_country string 255 ISO ALPHA-3 format, e.g. usa
    document_confirmed bool
    reg_date int Unix timestamp in seconds
    issue_date int Unix timestamp in seconds
    expiry_date int Unix timestamp in seconds
    reg_number string 255
    vat_number string 255
    purpose_to_open_account string 255
    one_operation_limit float decimal(14,4)
    daily_limit float decimal(14,4)
    weekly_limit float decimal(14,4)
    monthly_limit float decimal(14,4)
    annual_limit float decimal(14,4)
    active_features string list 1024
    promotions string list 1024
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    KYC procedure

    Download Postman KYC Procedure

    We provide an opportunity to work with many KYC providers through one universal API. User data can enter the Covery both directly from the provider and from the client. Procedure in a general view is as follows:

    1. You send a KYC start request, which describes the conditions for passing the KYC procedure, such as language, photo or video verification, the number of documents, etc.
    2. Covery analyzes the request and transfers it to the KYC provider
    3. Covery returns a response with the URL to which end user must be redirected or which will be displayed in an iframe
    4. End user follows the URL, and goes through the procedure or not. If end user has gone through the procedure to the end (successfully or not) he will be redirected to the URL specified in the KYC start request.
    5. If the procedure is interrupted at the user's initiative or as a result of a timeout, you can receive KYC start callback from Covery
    6. After the end user passes the procedure, a new KYC profile event is generated on Covery. This event contains all the information received from the KYC provider and passes all the prepared risks controls and AML checks. As a result you receive a decision callback for this event.
    7. The procedure is completed. To obtain photo / video proofs, use the KYC proof method

    For complex verification of a legal entity, when it is necessary to receive a KYC procedure for several beneficiaries (individuals and legal entities), can be used an additional type of KYC submit event

    KYC start

    Download Postman 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.

    Field Type Length Description
    type string 255 mandatory Value has to be kyc_start
    event_id string 255 mandatory
    event_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory string
    verification_mode string 255 mandatory Possible values: any, image, video
    verification_source string 255 mandatory Possible values: any, online, offline
    consent bool mandatory
    number_of_documents int Number of documents that should be checked in this procedure. Allowed values: 0, 1, 2. By default = 1
    allowed_document_format string list 255 This field can additionally allow to provide a documents in special formats. Allowed values: paper, laminated, photocopy.
    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 255 See event merge
    group_id string 255 See event merge
    country string 255 ISO ALPHA-3 format, e.g. usd
    kyc_language string 255 ISO ALPHA-2 format, e.g. en
    redirect_url string(256) 255
    email string 255
    firstname string 255
    lastname string 255
    profile_id string 255
    phone string 255
    birth_date int Unix timestamp in seconds
    reg_number string 255
    issue_date int Unix timestamp in seconds
    expiry_date int Unix timestamp in seconds

    Implement device fingerprinting to investigate suspicious devices.

    KYC start callback

    This method returns callbacks about KYC start session statuses.

    If it is configured, Covery will send callback for every KYC start session status changes to the defined by Covery customer URL.

    With the following headers:
    Method: POST
    Header Description
    X-Auth-Nonce Signature salt
    X-Auth-Signature Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.

    Response example

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

    Response fields

    Field Type Description
    requestId int kyc start requestId
    type string value: "kycStartCallback"
    createdAt int kyc start status change timestamp
    sequenceId string sequence_id from request
    merchantUserId string user_merchant_id from request
    status string possible values: timeout, cancelled, completed

    KYC profile

    Download Postman 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 Length Description
    type string 255 mandatory Value has to be kyc_profile
    event_id string 255 mandatory
    event_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    status string 255 Profile status
    code string 255
    reason string 255
    provider_id string 255 KYC provider event id
    provider_result string 255 Result from third-party provider
    provider_code string 255
    provider_reason string 255
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    profile_id string 255 Profile ID
    profile_type string 255 Profile type e.g. person, company or document
    profile_sub_type string 255 Profile subtype e.g. company or document type
    firstname string 255
    lastname string 255
    fullname string 512 Can be also used to send company name
    gender string 255
    industry string 255
    wallet_type string 255
    website_url string 255
    description string 1024 E.g. clarification of industry or document details
    employment_status string 255
    source_of_funds string 255
    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 255
    vat_number string 255
    email string 255
    email_confirmed bool
    phone string 255
    phone_confirmed bool
    contact_email string 255
    contact_phone string 255
    country string 255 ISO ALPHA-3 format, e.g. usa
    state string 255
    city string 255
    address string 255
    address_confirmed bool
    zip string 255
    nationality string 255
    second_country string 255 ISO ALPHA-3 format, e.g. usa
    second_state string 255
    second_city string 255
    second_address string 255
    second_address_confirmed bool
    second_zip string 255
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    KYC submit

    Download Postman KYC Submit

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

    Request fields

    Field Type Length Description
    type string 255 mandatory Value has to be kyc_submit
    event_id string 255 mandatory
    event_timestamp int mandatory Unix timestamp in seconds
    user_merchant_id string 255 mandatory
    sequence_id string 255 See event merge
    group_id string 255 See event merge
    status string 255 Profile status
    code string 255
    reason string 255
    provider_id string 255 KYC provider event id
    provider_result string 255 Result from third-party provider
    provider_code string 255
    provider_reason string 255
    links_to_documents string list 2048 List of links to the documents saved outside Covery
    profile_id string 255 Profile ID
    profile_type string 255 Profile type e.g. person, company or document
    profile_sub_type string 255 Profile subtype e.g. company or document type
    firstname string 255
    lastname string 255
    fullname string 512 Can be also used to send company name
    gender string 255
    industry string 255
    wallet_type string 255
    website_url string 255
    description string 1024 E.g. clarification of industry or document details
    employment_status string 255
    source_of_funds string 255
    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 255
    vat_number string 255
    email string 255
    email_confirmed bool
    phone string 255
    phone_confirmed bool
    contact_email string 255
    contact_phone string 255
    country string 255 ISO ALPHA-3 format, e.g. usa
    state string 255
    city string 255
    address string 255
    address_confirmed bool
    zip string 255
    nationality string 255
    second_country string 255 ISO ALPHA-3 format, e.g. usa
    second_state string 255
    second_city string 255
    second_address string 255
    second_address_confirmed bool
    second_zip string 255
    media_id int list

    Implement device fingerprinting to investigate suspicious devices.

    KYC proof

    Download Postman KYC proof

    This method allows you to receive a link to photo / video proofs collected during KYC procedure.

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

    Detail Description
    Method POST
    Endpoint api/kycProof
    Access level Event or Decision

    Request fields

    Field Type Length Description
    kyc_start_id int mandatory kyc start requestId

    Response example

    {
  "requestId":7896010,
  "type":"kycProof",
  "createdAt":1449049571.123,
  "verificationVideo":"https://covery.ai/comics",
  "faceProof":"https://covery.ai/comics",
  "documentProof":"https://covery.ai/comics",
  "documentTwoProof":"https://covery.ai/comics",
  "consentProof":"https://covery.ai/comics"
}

    Response fields

    Field name Type Description
    requestId int ID of inserted data
    type string value: kycProof
    createdAt int timestamp
    verificationVideo string link on a document
    faceProof string link on a document
    documentProof string link on a document
    documentTwoProof string link on a document
    consentProof string link on a document

    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,
  "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",
  "agentId": 12345,
  "note": "Customer verified manually",
  "checkedInCategory": ["person terror, person sanctions list, company sanctions list"],
  "verificationUrl": "https://covery.ai/comics",
  "notSavedFields": ["lastname, phone"]
}

    Response fields

    Field Type Description
    requestId int Internal event identifier in the Covery
    type string type from request
    createdAt float Unix timestamp in seconds
    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
    agentId int An identifier of user, that made a manual decision on a Covery portal
    note string Any comments, that were left during manual decision on a Covery portal
    checkedInCategory string list Returns watchlists, against which event was checked. Relevant only in case AML screening service is used
    verificationUrl string The link, to which the user should be transferred after decision. For event KYC Start only
    notSavedFields string list If event was send with correct mandatory fields, but not valid by length or type optional fields, Covery will save and analyze such event without those fields. For your attention we will return list of not saved fields here

    If manual: true - you are able to make one more final decision inside my.covery.ai portal. In this case one more callback will be sent on chosen URL (please provide it to Covery team). Callback will have the same the format of the body as first synchronous response, with next header:

    Header Description
    X-Auth-Signature mandatory Manual decision callback signature must be calculated as sha256 checksum from provided by you secret + event request id

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

    Response fields

    Field Type
    requestId int

    Card ID API

    This method allows to generate unique sustainable ID of the card. Card ID would be generated only for valid card number. If you do not have proper PCI DSS certification - you are prohibited to save card number from request in any, even temporary log, storage.

    Detail Description
    Method POST
    Endpoint api/cardId
    Access level Event and Decision

    Download Postman Card Id

    Request fields

    Field Type Length Description
    card_number sting 20 mandatory Full number of card

    Response example

    {
  "requestId": 7896010,
  "createdAt": 1449049571,
  "cardId": "5aaaa194f3baaaaade427"
}

    Response fields

    Field Type Description
    requestId int ID of inserted data
    createdAt float timestamp
    cardId string use as card_id or as payout_card_id

    Media API

    Use Media storage to upload media files and connect them to end user events.Inside the Covery portal you will be able to review uploaded data and get more information extracted from it. We are able to use AI and Computer vision to get not only metadata of a file, but to detect some information on the documents and images.

    Media storage

    This method will allowed to upload your media files to the Covery storage. As a result of request you will receive a temporary URL by which you can store the file.

    Download Postman Media storage.

    Detail Description
    Method POST
    Endpoint api/mediaStorage
    Access level Media
    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. Is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

    Request fields

    Field Type Length Description
    content_type sting 255 mandatory Possible values: image/jpeg, image/png, image/gif
    content_description sting 255 mandatory Possible values: personal_photo, linked_document, general_document
    file_name sting 255 In case value is present - filename will be replaced with value from this field
    ocr bool false by default

    Response fields

    Field Type Description
    uploadUrl string URL can be used for uploading the file duaring 10 minutes
    mediaId int ID of inserted media file
    createdAt float Unix timestamp in seconds

    Media storage callback

    This method returns callbacks about Media uploading status change. If it is configured, Covery will send callback for every upload session status changes to the defined by Covery customer URL.
    Method: POST
    Header Description
    X-Auth-Nonce Signature salt
    X-Auth-Signature Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.

    Response fields

    Field Type Description
    status string Possible values: success, error
    errorReason string Error reason description
    errorCode int Error reason code
    mediaId int ID of inserted media file
    createdAt float Unix timestamp in seconds

    Media connection

    With this method yo are able to bind media file that was sent to our storage with envelop sent before. You can bind more than one media file with one envelope. Also one media file can be bind to multiple envelopes.

    Download Postman Media connection.

    Detail Description
    Method PUT/DELETE
    Endpoint api/mediaСonnection
    Access level Media
    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. Is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

    Request fields

    Field Type Length Description
    request_id int mandatory Internal event identifier in the Covery
    media_id int list mandatory Internal media identifier in the Covery

    Client management API

    Use Client management API to create user profile and establish its ongoing monitoring on needed regular basis.

    Detail Description
    Method PUT and DELETE
    Endpoint api/clientManagement
    Access level Decision

    Request fields

    Field Type Length Description
    type string 255 mandatory value has to be user_profile
    sequence_id string 255 mandatory
    client_type string 255 mandatory for PUT only
    ongoing_monitoring bool false by default
    ongoing_monitoring_frequency int 3 value in days starting from 1

    Ongoing monitoring API

    When ongoing monitoring is set up for an end user you will start to receive our callbacks each time it has been done. Please, provide for those needs your callback URL to the Covery team.

    Header Description
    X-Auth-Nonce Signature salt
    X-Auth-Signature Callback signature, is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was received from you.
    Method POST

    Response fields

    Field Type Description
    requestId int internal Covery ID
    type string ongoing monitoring
    createdAt float timestamp
    sequenceId string sequence_id from request
    merchantUserId string user_merchant_id from request
    monitoringResult string possible values: Safety, Alert, Warning
    reason string list of rules with decision true, from decisive scenario
    assessmentResult string possible values: Safety, Alert, Warning. Will be present in a second webhook, in case of manual decision
    agentId int ID of the user who performed assessment in the portal. Will be present in a second webhook, in case of manual decision
    note string comment supplied during assessment, length 1024. Will be present in a second webhook, in case of manual decision.
    checkedInCategory string list Returns watchlists, against which event was checked. Relevant only in case AML screening service is used

    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, including 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.

    Use method device fingerprint to get your own device fingerprint pixel js. We recommend to update the pixel at least once a day, so you will be sure that you have our latest version

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

    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. Use method Device fingerprint to get your own device fingerprint pixel js

    2. Put received on first step device fingerprint pixel JS on your conversion page. For example: <script async src=“https://your_storage_domain/file_name.js“></script>

    3. Send the device fingerprint in the field device_fingerprint, in subsequent user event

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

    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",
  "authCode": "ab1234",
  "chargebackAmount": 0,
  "chargebackCurrency": "",
  "chargebackReasonCode": "",
  "merchantDescriptor": "EXAMPLE",
  "transactionId": "ABS123456789",
  "nodeType": "companyId",
  "nodeId": 123123
}
    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
    authCode string Authorization code
    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)
    transactionId string Transaction_id of matched event
    nodeType string Node type of matched
    nodeId int Node name of matched event

    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