Basics

    Welcome to Covery API documentation

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

    If you have any questions or need an assistance, please contact us.

    API endpoint

    https://api.covery.ai

    Encoding

    API uses UTF-8 character encoding.

    Access tokens

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

    Type Example
    Access token 21a3358f36e5af968b75357590b75c28
    Token secret eNfrVfsXQtI+yCIQ9XmuKYP5yBjK0ip7

    Token levels

    There are four customer token levels:

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

    Requests

    Request must have a JSON encoded body and following headers:

    Header Description
    X-Auth-Token mandatory Access token, received from Covery administrators
    X-Auth-Nonce mandatory Random unique string, used as salt in packet signature
    X-Auth-Signature mandatory Packet signature
    X-Identities List of identity nodes in format name1=id1&name2=id2&…, used only in Event and Decision APIs
    hash('sha256', $nonce . $request->getContent() . $secret)
    

    X-Auth-Signature is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (received from Covery administrators).

    Responses

    HTTP/1.1 200 OK
    Content-Type: application/json
    X-Maxwell-Status: OK
    
    HTTP/1.1 404 Not Found
    Content-Type: application/json
    X-Maxwell-Status: Exception
    X-Maxwell-Error-Type: Maxwell\Exception\NoRouteException
    X-Maxwell-Error-Message: Unable to found route for POST /api/wrong/endpoint
    

    API response body can be empty or JSON encoded object or array.

    API response status is reported using the appropriate HTTP status code. Additional details are provided by headers.

    Name Description
    Content-Type mandatory application/json for most cases, but can be text/plain for errors
    X-Maxwell-Status mandatory OK for success, Exception for errors
    X-Maxwell-Error-Type optional Exception class name in common
    X-Maxwell-Error-Message optional Exception text in common
    X-Maxwell-Error-Context optional May contain additional information about error, such as id when trying to insert entry, that already exists

    Status codes

    Code Description
    200 OK
    204 OK, but no content to respond
    401 One of mandatory auth headers missing, or invalid auth token, or invalid auth signature
    403 Token access level not sufficient to access requested API
    404 No API method for URL or wrong HTTP method
    406 Wrong/malformed incoming request data
    409 Entry already exist, inspect X-Maxwell-Error-Context header for id
    410 Entry not found
    429 Too many requests with same sequence_id
    500 Internal error
    503 API method presents but misconfigured in dependency injection. Please contact us ASAP
    509 Too many requests
    510 Failed to build application using dependency injection config. Please contact us ASAP

    Health check API

    Response example

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

    Covery API status can be checked by sending ping request:

    Detail Description
    Method POST
    Endpoint api/ping
    Access level Any

    Returns JSON with the information about granted access level for the used token.

    If any issues are noticed, please check the system status and contact us ASAP.

    Event API

    Use Event API to send user actions in your product for further analysis of events sent to Decision API.

    Detail Description
    Method POST
    Endpoint api/sendEvent
    Access level Event

    Install

    Request fields

    Field Type Description
    type string mandatory Value has to be install
    install_timestamp int mandatory
    user_merchant_id string
    sequence_id string(40) See event merger
    country string ISO ALPHA-3 format, e.g. usa
    website_url string
    traffic_source string
    affiliate_id string

    Optional device data can be used.

    Registration

    Request fields

    Field Type Description
    type string mandatory Value has to be registration
    registration_timestamp int mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    age int
    country string ISO ALPHA-3 format, e.g. usa
    email string
    firstname string
    lastname string
    gender string
    phone string
    social_type string
    user_name string
    website_url string
    traffic_source string
    affiliate_id string

    Optional device data can be used.

    Confirmation

    Request fields

    Field Type Description
    type string mandatory Value has to be confirmation
    confirmation_timestamp int mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    email string
    phone string
    email_confirmed bool
    phone_confirmed bool

    Optional device data can be used.

    Login

    Request fields

    Field Type Description
    type string mandatory Value has to be login
    login_timestamp int mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    login_failed bool
    email string
    phone string
    gender string
    traffic_source string
    affiliate_id string

    Optional device data can be used.

    Transaction

    Request fields

    Field Type Description
    type string mandatory Value has to be transaction
    transaction_amount float mandatory
    transaction_currency string mandatory
    transaction_id string mandatory
    transaction_timestamp int mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    payment_method string
    payment_system string
    payment_mid string
    transaction_mode string
    transaction_type string
    payment_account_id string
    card_id string
    card_bin int
    card_last4 string
    expiration_month int
    expiration_year int
    age int
    billing_address string
    billing_city string
    billing_country string ISO ALPHA-3 format, e.g. usa
    billing_fullname string If not sent, will consist of billing first and last names
    billing_firstname string
    billing_lastname string
    billing_state string
    billing_zip string
    country string ISO ALPHA-3 format, e.g. usa
    email string
    firstname string
    lastname string
    gender string
    merchant_ip string
    phone string
    product_description string
    product_name string
    product_quantity float
    transaction_amount_converted float If not sent, will be converted to base currency of your account
    user_name string
    website_url string
    transaction_source string
    affiliate_id string

    Optional device data can be used.

    Refund

    Request fields

    Field Type Description
    type string mandatory Value has to be refund
    refund_timestamp int mandatory
    refund_id string mandatory
    sequence_id string(40) mandatory See event merger
    refund_amount float mandatory
    refund_currency string mandatory
    refund_amount_converted float If not sent, will be converted to base currency of your account
    refund_method string
    refund_system string
    refund_mid string
    refund_source string
    refund_type string E.g. full, partial
    refund_code string Reason code why refund issued
    refund_reason string Reason why refund issued
    agent_id string Person who issued refund

    Optional device data can be used.

    Payout

    Request fields

    Field Type Description
    type string mandatory Value has to be payout
    payout_timestamp int mandatory
    payout_id string mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    payout_amount float mandatory
    payout_currency string mandatory
    payout_amount_converted float If not sent, will be converted to base currency of your account
    payout_method string
    payout_system string
    payout_mid string
    payout_account_id string
    payout_card_id string
    firstname string
    lastname string
    country string ISO ALPHA-3 format, e.g. usa
    email string
    phone string
    payout_card_bin int
    payout_card_last4 string
    payout_expiration_month int
    payout_expiration_year int

    Optional device data can be used.

    Transfer

    Request fields

    Field Type Description
    event_type string mandatory Value has to be transfer
    event_id string mandatory
    event_timestamp int mandatory
    user_merchant_id string mandatory
    sequence_id string(40) mandatory See event merger
    account_system string mandatory
    account_id string mandatory
    second_account_id string mandatory
    amount float mandatory
    currency string mandatory
    amount_converted float If not sent, will be converted to base currency of your account
    operation string
    source string
    firstname string
    lastname string
    fullname string
    email string
    phone string
    birth_date int
    gender string
    country string ISO ALPHA-3 format, e.g. usa
    state string
    city string
    address string
    zip string
    second_firstname string
    second_lastname string
    second_fullname string
    second_email string
    second_phone string
    second_birth_date int
    second_gender string
    second_country string ISO ALPHA-3 format, e.g. usa
    second_state string
    second_city string
    second_address string
    second_zip string
    product_name string
    product_description string
    product_quantity float

    Optional device data can be used.

    Event merger

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

    Device data

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

    Request fields

    Field Type Description
    ajax_validation bool
    cookie_enabled bool
    cpu_class string
    device_fingerprint string
    device_id string Identifier of mobile device
    do_not_track bool
    ip string
    language string user’s browser language
    languages string user’s preferred languages
    language_browser string user’s operating system language
    language_user string user’s locale operating system language
    language_system string default operating system language
    os string
    real_ip string
    screen_resolution string
    screen_orientation string
    timezone_offset int offset in minutes
    user_agent string

    Response

    Response example

    {
      "requestId": 7896010,
      "type": "transaction",
      "createdAt": 1449049571.123,
      "sequenceId": "3f3c5e978f90f2a9495bce7492467a65f61333be",
      "merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b"
    }
    
    Field Type Description
    requestId int ID of inserted data
    type string type from request
    createdAt float timestamp
    sequenceId string sequence_id from request
    merchantUserId string user_merchant_id from request

    Decision API

    Use Decision API to get a risk assessment of user actions in your product. Events which are used only for analysis of other actions should be sent to Event API.

    Detail Description
    Method POST
    Endpoint api/makeDecision
    Access level Decision

    Response example

    {
      "requestId": 7896010,
      "type": "transaction",
      "createdAt": 1449049571.123,
      "sequenceId": "3f3c5e978f90f2a9495bce7492467a65f61333be",
      "merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b",
      "score": 80,
      "accept": false,
      "reject": true,
      "manual": false,
      "reason": "User 5 cards 1 day, Disposable email domain, Anonymous proxy",
      "action": "Additional verification"
    }
    

    Response fields

    Field Type Description
    requestId int ID of inserted data
    type string type from request
    createdAt float timestamp
    sequenceId string sequence_id from request
    merchantUserId string user_merchant_id from request
    score int calculated risk score
    accept bool event accepted
    reject bool event rejected
    manual bool event sent to manual review
    reason string explanation of made decision
    action string business flow for made decision

    Postback API

    Request example when request_id is known

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

    Request example when only transaction_id is known

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

    Response example

    {
      "requestId": 123456
    }
    

    This API is used to supply additional transaction data after transaction processing.

    Detail Description
    Method POST
    Endpoint api/postback
    Access level Event

    Request fields

    Field Type Description
    request_id int mandatory if no transaction_id present
    transaction_id string mandatory if no request_id present
    transaction_status string
    code string
    reason string
    secure3d string
    avs_result string
    cvv_result string
    psp_code string
    psp_reason string
    arn string

    Response fields

    Field Type
    requestId int

    Fraud alert API

    This subset of APIs is dedicated for fraud alert handling.

    Fraud alert fields

    Fraud alert example

    {
      "id": 8464503,
      "source": "ethoca",
      "externalId": "5SNLJ1WOKODEUPLY396439RT4",
      "type": "issuer_alert",
      "state": "none",
      "cardBin": "502006",
      "cardLast4": "7616",
      "alertTimestamp": 1459521191,
      "transactionTimestamp": 1459521191,
      "transactionAmount": 28.55,
      "transactionCurrency": "USD",
      "is3dSecure": null,
      "arn": "43792622030200003292612",
      "chargebackAmount": 0,
      "chargebackCurrency": "",
      "chargebackReasonCode": "",
      "merchantDescriptor": "EXAMPLE"
    }
    
    Field Type Description
    id int Fraud alert identifier
    source string Fraud alert source
    externalId string External fraud alert identifier
    type string Fraud alert type
    state string Current fraud alert state
    cardBin string First 6 numbers of user’s credit card number
    cardLast4 string Last 4 numbers of user’s credit card number
    arn string Acquirer reference number
    merchantDescriptor string Merchant descriptor
    is3dSecure boolean or null Was transaction under 3D secure or not (true, false, null for unknown)
    alertTimestamp int Alert time (Unix timestamp)
    transactionAmount float Original transaction amount
    transactionCurrency string Original transaction currency
    transactionTimestamp int Original transaction time (Unix timestamp)
    chargebackAmount float Chargeback amount
    chargebackCurrency string Chargeback currency
    chargebackTimestamp int Chargeback time (Unix timestamp)

    List of values for type field

    Value Description
    empty string
    issuer_alert Confirmed fraud
    fraudreporter_alert Confirmed fraud
    customerdispute_alert Customer dispute

    Confirmed fraud states

    Value Description
    none Fraud alert just received
    stopped
    partially_stopped
    previously_cancelled
    missed
    notfound
    account_suspended
    in_progress
    shipper_contacted
    other

    Customer dispute states

    Value Description
    none Fraud alert just received
    resolved
    previously_refunded
    unresolved_dispute
    notfound
    other

    Latest alerts

    Use this API to receive all latest fraud alerts available for your account.

    Detail Description
    Method POST
    Endpoint api/manage/fraud/latest
    Access level Decision, Management

    Request fields

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

    Response

    List of fraud alerts with the fields listed above.

    Alert by ID

    Use this API to receive details for particular fraud alert using its ID.

    Detail Description
    Method POST
    Endpoint api/manage/fraud/find
    Access level Decision, Management

    Request fields

    Field Type Description
    id int Identifier of fraud alert

    Response

    Single fraud alert with the fields listed before.

    Alert confirmation

    Use this API to confirm retrieval of fraud alerts.

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

    Request fields

    Field Type Description
    id int Identifier of fraud alert

    Response

    Empty response.

    Alert feedback

    Use this API to process received fraud alerts.

    Detail Description
    Method POST
    Endpoint api/manage/fraud/feedback
    Access level Management

    Request fields

    Field Type Description
    id int Identifier of fraud alert
    result string See Confirmed fraud and Customer dispute states
    refunded string none, refunded, not_refunded, not_settled

    Response

    Empty response.

    Alert callback

    If it is configured, Covery will send callback for every incoming fraud alert to the defined URL.

    Callback contains fraud alert details (same as get fraud alert by ID) with the following headers:

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

    Callback signature is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was sent to you during the configuration process.

    If you have any questions or need an assistance, please contact us.