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.
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.
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. |
||
telephone
optional
|
object |
The telephone number associated with the identified fraud. |
||
ipAddress
optional
|
object |
The IP address associated with the identified fraud. |
||
paymentMethod
optional
|
object |
The payment method associated with the identified fraud. Only one of One of the following:
Show definition
|
||
chargebacks
optional
|
array | Show definition | ||
manualReviews
optional
|
array | Show definition | ||
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
}
]
}
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
}
]
}
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
}
]
}
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.
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.
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
}
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
}
}
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
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
.
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%40example.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
}
}
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
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%40example.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%40example.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.
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
}
]
}
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"
}
]
}