Lookup

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.

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.

Adding a Chargeback

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
      }
    ]
  }

Adding a Manual Review

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
      }
    ]
  }

Full Example

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
    }
  ]
}

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 Lookup Endpoint End 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 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
}

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 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
    }
}

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

Checking PaymentMethod

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.

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 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
    }
}

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 https://api.ravelin.com/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 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.

Reversing Manual Reviews

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
      }
    ]
  }

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 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"
      }
    ]
  }

Feedback

© Ravelin Technology Ltd. All rights reserved