Lookup API Reference

Ravelin Lookup is a shared fraud database for merchants. As a merchant, you can use Ravelin Lookup’s API to share identifiers (email, phone, IP address, payment method) associated with fraud, and check whether any of those identifiers have already been flagged by other merchants. For each identifier you add to Ravelin Lookup you will need to describe the source of fraud - either a chargeback or manual review.

Connection

Events are sent to Ravelin as JSON objects to a POST endpoint over HTTPS. Ravelin Lookup’s API lives at https://api.ravelin.com/v2/lookup.

All API endpoints require an Authorization header with your API key.

Ravelin uses API keys to allow access to the API. You can register a new Ravelin API key by contacting your account manager. Ravelin expects the API key to be included in the authorization header for all API requests, i.e.:

# Using curl, pass the authentication header with each request
curl "https://api.ravelin.com/v2/auth/checktoken" \
  -H "Authorization: token sk_live_XXXXXXXX"

Make sure to replace sk_live_XXXXXXXX with your API key.

When submitting a JSON request, make sure to include the JSON mime-type in the Content-Type HTTP header:

Content-Type: application/json; charset=utf-8

Recording Fraud

To add an identifier to Ravelin Lookup you will need to send Ravelin the identifier (who is fraudulent - identified by IP address, telephone number, and/or email), and the source of fraud (why they are considered fraudulent - chargebacks and/or manual review by one of your analysts). For each chargeback or manual review, you can either add an email address, telephone number and IP address all at once, or independently at different times.

Examples follow.

POST /v2/lookup

The full JSON Schema by which this endpoint is validated is available at https://api.ravelin.com/v2/lookup/schema.json. Additionally, authenticated POST requests can be made to https://api.ravelin.com/v2/lookup/validate which will return a 400 if the request does not validate, with explanations.

Name Type Description Example
timestamp
required
 integer

The unix time in seconds that the event happened

 1479231064
email
optional
 object

The email address associated with the identified fraud.

Show definition
telephone
optional
 object

The telephone number associated with the identified fraud.

Show definition
ipAddress
optional
 object

The IP address associated with the identified fraud.

Show definition
paymentMethod
optional
 object

The payment method associated with the identified fraud. Only one of instrumentId, payerId or bankId can be provided.

One of the following:
Show definition
chargebacks
optional
 array Show definition
manualReviews
optional
 array Show definition

Adding a Chargeback

To add a chargeback, the request looks like this:

POST /v2/lookup HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "timestamp": 1486387634000,
    "email": {
      "address": "chargeback@example.com",
      "timestamp": 1486387634000
    },
    "telephone": {
      "number": "+442222222222",
      "countryCode": "GBR",
      "timestamp": 1486387634000
    },
    "ipAddress": {
      "address": "22.22.22.22",
      "timestamp": 1486387634000
    },
    "chargebacks": [
      {
        "chargebackId": "dp_15RsQX2eZvKYlo2C0MFNUWJC",
        "gateway": "worldpay",
        "gatewayReference": "ch_15RsQR2eZvKYlo2CA8IfzCX0",
        "customerId": "your-customer-id",
        "reason": "general",
        "status": "lost",
        "amount": 195,
        "currency": "USD",
        "disputeTime": 1422915137
      }
    ]
  }

Adding a Manual Review

To add a manual review, the request looks like this:

POST /v2/lookup HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "timestamp": 1486387634000,
    "email": {
      "address": "review@example.com",
      "timestamp": 1486387634000
    },
    "telephone": {
      "number": "+443333333333",
      "countryCode": "GBR",
      "timestamp": 1486387634000
    },
    "ipAddress": {
      "address": "33.33.33.33",
      "timestamp": 1486387634000
    },
    "manualReviews": [
      {
        "reviewId": "12345678",
        "label": "FRAUDSTER",
        "comment": "Confirmed to be a fraudulent order.",
        "customerId": "your-customer-id",
        "reviewer": {
          "name": "Bilbo Baggins",
          "email": "bilbo.b@shiremail.com"
        },
        "timestamp": 1486387634000
      }
    ]
  }

Full Example

POST /v2/lookup HTTP/1.1
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "timestamp": 1479231064,
  "email": {
    "address": "review@example.com",
    "verified": true,
    "timestamp": 1479231064
  },
  "telephone": {
    "number": "+442222222222",
    "countryCode": "GB",
    "verified": true,
    "timestamp": 1479231064
  },
  "ipAddress": {
    "address": "33.33.33.33",
    "timestamp": 1479231064
  },
  "paymentMethod": {
    "instrumentId": "ljkvel433-34t3g5-4334g3g",
    "timestamp": 1479231064
  },
  "chargebacks": [
    {
      "chargebackId": "dp_15RsQX2eZvKYlo2C0MFNUWJC",
      "gateway": "stripe",
      "gatewayReference": "tx_abc123",
      "customerId": "9307355",
      "reason": "general",
      "status": "lost",
      "amount": 195,
      "currency": "USD",
      "disputeTime": 1422915137
    }
  ],
  "manualReviews": [
    {
      "reviewId": "12345678",
      "comment": "Definitely a fraudster.",
      "customerId": "9307355",
      "reviewer": {
        "name": "tom@mycompany.com",
        "email": "Tom"
      },
      "timestamp": 1486387634000
    }
  ]
}

Batch Upload

The same API is available under the path /v2/backfill/lookup to be used for batch upload. This API has a higher, separate rate limit to /v2/lookup so that you do not interrupt your production system’s use of Ravelin Lookup. The additions are processed asynchronously to the request.

Checking for Fraud

To check if a email address, phone number, IP address or payment method has been associated with fraud on Ravelin Lookup, send a GET request to /v2/lookup using the query parameters described below. Query parameters need to be URL encoded. The request should have an Authorization header.

Checking Emails

In this example, we use the email query parameter to check for the email chargeback@example.com. The request looks like the following:

GET /v2/lookup?email=chargeback%40example.com

If you receive a match associated with a chargeback, the response will look like the following:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": false,
  "email": {
    "address": "chargeback@example.com",
    "hasChargebacks": true,
    "reviewedAsFraudster": false
  }
}

If you receive a match associated with a manual review, the response will look like the following:

{
  "hasChargebacks": false,
  "reviewedAsFraudster": true,
  "email": {
    "address": "chargeback@example.com",
    "hasChargebacks": false,
    "reviewedAsFraudster": true
  }
}

And if you receive a match associated with both, the response will look like the following:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": true,
  "email": {
    "address": "chargeback@example.com",
    "hasChargebacks": true,
    "reviewedAsFraudster": true
  }
}

But if you do not receive a match we will return only the parameters for which we searched:

{
  "hasChargebacks": false,
  "reviewedAsFraudster": false
}

Checking Phone Numbers

In this example, we use the phone query parameter to check for the phone number ‘+442222222222’. The phone number should be in E.164 format. The request looks like this:

GET /v2/lookup?telephone=%2B442222222222

If you receive a match, the response will look like the following:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": true,
  "telephone": {
    "number": "+442222222222",
    "hasChargebacks": true,
    "reviewedAsFraudster": true
  }
}

Checking IP Addresses

In this example, we use the ipAddress query parameter to check for the IP address 92.233.138.154. The request looks like this:

GET /v2/lookup?ipAddress=22.22.22.22

If you receive a hit, the response will look like the following:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": true,
  "ipAddress": {
    "address": "22.22.22.22",
    "hasChargebacks": true,
    "reviewedAsFraudster": true
  }
}

When fetching by IP address only IP addresses in the last 30 days will be searched. You can override this search window using the ipFromTime and ipToTime query parameters. These values must be valid unix timestamps (UTC) and their range cannot exceed a 30 day window.

GET /v2/lookup?ipAddress=22.22.22.22&ipFromTime=1492557479&ipToTime=1492589879

Checking PaymentMethod

In this example, we use the instrumentId query parameter to check for the instrument ID sfhfwfeoefjklhsfkljhsdfkjshkl. The request looks like this:

GET /v2/lookup?instrumentId=sfhfwfeoefjklhsfkljhsdfkjshkl

If you receive a hit, the response will look like the following:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": true,
  "paymentMethod": {
    "instrumentId": "sfhfwfeoefjklhsfkljhsdfkjshkl",
    "hasChargebacks": true,
    "reviewedAsFraudster": true
  }
}

Only a single payment method can be checked at a time and the query parameters are: instrumentId, bankAccountId or payerId.

Checking Multiple

These query parameters can be combined, and the top-level hasChargebacks and reviewedAsFraudster will indicate whether any of the identifiers were found. For example:

GET /v2/lookup?ipAddress=22.22.22.22&email=chargeback@example.com&payerId=WDJJHEBZ4X2LY

Might return the following if the IP address has been associated with a chargeback:

{
  "hasChargebacks": true,
  "reviewedAsFraudster": false,
  "ipAddress": {
    "address": "22.22.22.22",
    "hasChargebacks": true,
    "reviewedAsFraudster": false
  },
  "email": {
    "address": "chargeback@example.com",
    "hasChargebacks": false,
    "reviewedAsFraudster": false
  },
  "paymentMethod": {
    "payerId": "WDJJHEBZ4X2LY",
    "hasChargebacks": false,
    "reviewedAsFraudster": true
  }
}

Checking Only in Your Industry

To limit your check to data from merchants in your industry, use the limitIndustry=true query parameter. The request might now look like:

GET /v2/lookup?telephone=%2B442222222222&limitIndustry=true

Removing Identifiers of Fraud

To remove fraudulent identifiers from Ravelin Lookup, DELETE requests to https://api.ravelin.com/v2/lookup can be performed using the appropriate query parameters:

DELETE /v2/lookup?email=chargeback@example.com
DELETE /v2/lookup?telephone=%2B442222222222
DELETE /v2/lookup?ipAddress=22.22.22.22

Note that you can combine these requests into one:

DELETE /v2/lookup?email=chargeback@example.com&telephone=%2B442222222222&ipAddress=22.22.22.22

Removing your own identifiers does not remove them for other clients.

This will remove all sources of fraud for the given identifiers. If you want to undo a chargeback or manual review you should set their status or label according to the below.

Reversing Manual Reviews

If the decision of a manual review is reversed, the label can be updated:

POST /v2/lookup HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "timestamp": 1486387634002,
    "email": {
      "address": "review@example.com"
    },
    "telephone": {
      "number": "+443333333333"
    },
    "ipAddress": {
      "address": "33.33.33.33",
      "timestamp": 1486387634000
    },
    "manualReviews": [
      {
        "reviewId": "12345678",
        "label": "GENUINE",
        "timestamp": 1486387634000
      }
    ]
  }

Reversing Chargebacks

A chargeback may also occur for service-related reasons or as a result of ‘friendly’ fraud (also known as first party fraud). If you successfully dispute a chargeback, set the status of the chargeback to “WON” to remove the association with fraud:

POST /v2/lookup HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "timestamp": 1486387634000,
    "email": {
      "address": "chargeback@example.com"
    },
    "telephone": {
      "number": "+442222222222"
    },
    "ipAddress": {
      "address": "22.22.22.22",
      "timestamp": 1486387634000
    },
    "chargebacks": [
      {
        "chargebackId": "dp_15RsQX2eZvKYlo2C0MFNUWJC",
        "gatewayReference": "ch_15RsQR2eZvKYlo2CA8IfzCX0",
        "status": "WON"
      }
    ]
  }