Ravelin Lookup is a shared fraud database for merchants. As a merchant, you can use the Lookup Endpoint 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.
To add a chargeback, the request looks like this:
POST https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/v2/lookup HTTP/1.1
Authorization: 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 Lookup Endpoint End 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 https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/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 https://api.ravelin.com/v2/lookup?email=chargeback%40example.com
DELETE https://api.ravelin.com/v2/lookup?telephone=%2B442222222222
DELETE https://api.ravelin.com/v2/lookup?ipAddress=22.22.22.22
Note that you can combine these requests into one:
DELETE https://api.ravelin.com/v2/lookup?email=chargeback%40example.com&telephone=%2B442222222222&ipAddress=22.22.22.22
Removing your own identifiers does not remove them for other clients.
If the decision of a manual review is reversed, the label can be updated:
POST https://api.ravelin.com/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 https://api.ravelin.com/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"
}
]
}
Was this page helpful?