Payment Fraud Integration

Providing Historical Data

On this page:

As part of preventing payment fraud we will train a machine learning model which uniquely identifies the fraud you are experiencing. We will then use your model to evaluate your live traffic and return recommendations.

We recommend using live data to train your initial model. We typically need to collect live data for at least a month to train your initial custom model.

However, we can also use historical data to train your initial model. Using historical data can mean we’re able to train your model sooner without needing to wait for enough live data.

When To Send Historical Data

You should only consider sending historical data when:

  • You have enough historical data, and it contains the correct fields.
  • Your historical data is an accurate representation of your live data.
  • You are not receiving enough live data to train a model.
  • You have an urgent need to go live with your payment fraud integration as soon as possible.

Your integration manager will discuss with you whether providing historical data is necessary.

Sending Historical Data

If we decide providing historical data is necessary, we will set up a dedicated Ravelin account for you to send your historical data to. This will be different to the account which you will use for live data. This dedicated account will have its own API Key which you should use for sending requests containing your historical data.

  • You should send historical customer, payment method, order and transaction data to our Checkout Endpoint.

  • You should send historical disputes data to our Dispute Endpoint.

  • The more data you can send in these requests, the better our payment fraud recommendations will be.

  • Add the query parameter backfill=true to the URLs so that we know that the request contains historical data. For example, /v2/checkout?backfill=true.

  • Timestamps must be provided for all historical data. If a timestamp isn’t available, a timestamp from a related entity can be used. For example, if you don’t have registrationTime for a customer, the time of their first order could be used instead.

  • It is important that you send your historical data in the same order that the events took place.

  • The API rate limit for your historical data Ravelin account will be much higher than the rate limit on your live account, so if you’re sending historical data yourself, you don’t need to worry about being rate limited.

Alternatively, you can provide us with an export of your historical data in JSON or CSV format, and we will load your data into your Ravelin account for you.

Your integration manager will ensure you’re providing all the relevant data in the correct fields before you begin sending all your historical data.

Once we have received your historical data we will analyse it to determine if it can be used to generate your custom machine learning model.