Payment Fraud Integration

Getting Started

This guide explains the basics of how to request a payment fraud recommendation and view the result in the Ravelin dashboard.

On this page:

Access your sandbox account

You should perform all integration testing with your sandbox account.

Follow these steps to access your sandbox account:

  1. Log in to the Ravelin dashboard. If you do not have a Ravelin account please ask your account admin to grant you access. Instructions can be found in our Help Centre.

  2. Click your company name in the top right corner to open the account menu and click the Sandbox mode toggle button to switch to your sandbox account. The page will reload to open your sandbox account.

  3. Click your company name in the top right corner to open the account menu and select Developer.

  4. Switch to the API Keys tab and click Show secret key to reveal your sandbox secret API Key.

Request a payment fraud recommendation

You should request payment fraud recommendations when customers try to place orders. To do this, you should send a request to our Checkout Endpoint.

The Checkout request should contain details about the following:

  • the customer
  • the customer’s device
  • the payment method being used to pay for the order
  • the order, including order items and delivery details
  • the transaction, even if it hasn’t been completed yet

An curl command which will send an example request to our Checkout Endpoint is shown below.

$ curl --location --request POST '' \
--header 'Authorization: token secret_key_test_XXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
 "timestamp": 1512828988826,
 "customer": {
   "customerId": "abc-123-ZYZ",
   "registrationTime": 1512828988826,
   "email": "",
   "name": "John Smith",
   "telephone": "+447000000001",
   "telephoneCountry": "GBR"
 "device": {
   "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
   "type": "phone",
   "manufacturer": "google",
   "model": "Pixel XL",
   "os": "android",
   "language": "en-US",
   "ipAddress": ""
 "order": {
   "orderId": "abcde12345-ZXY",
   "creationTime": 1512828988826,
   "price": 1500,
   "currency": "GBP",
   "market": "emea",
   "country": "GBR",
   "marketCity": "london",
   "items": [
       "sku": "0001",
       "name": "Margherita Pizza",
       "quantity": 1,
       "price": 1500
   "status": {
     "stage": "pending",
     "actor": "merchant"
 "paymentMethods": [
     "paymentMethodId": "pm-abc123",
     "instrumentId": "fp_abc123",
     "methodType": "card",
     "scheme": "visa",
     "cardBin": "535522",
     "cardLastFour": "0001",
     "expiryMonth": 7,
     "expiryYear": 2020,
     "nameOnCard": "John Smith",
     "billingAddress": {
       "addresseeName": "John Smith",
       "street1": "123 High Street",
       "city": "London",
       "country": "GBR",
       "postalCode": "E1 1AA"
 "transactions": [
     "transactionId": "123-abc-XYZ",
     "paymentMethodId": "pm-abc123",
     "time": 1512828988826,
     "amount": 1000,
     "currency": "GBP",
     "type": "auth",
     "gateway": "example-gateway"
  • Replace the Authorization header Bearer token “secret_key_test_XXXXXXXX” with your sandbox secret API key.

  • Run the command from a terminal window to send the request.

The response should look similar to the response shown below:

   "status": 200,
   "timestamp": 1650983692,
   "data": {
       "customerId": "abc-123-ZYZ",
       "action": "ALLOW",
       "score": 2,
       "source": "RAVELIN",
       "scoreId": "d62297ae-d159-4072-6cc3-b4bd88738729"

The data.action field contains our payment fraud recommendation. The request which you sent is not particularly suspicious and so it is likely the action will be "ALLOW", as shown in the example response above, this means you should allow the customer to place the order.

View the customer in the Ravelin dashboard

To ensure the request was handled correctly and investigate how we produced the recommendation, you can view the customer’s details in the Ravelin dashboard.

Ensure you’re logged into the Ravelin dashboard with you sandbox account.

  • Click Explore in the left hand menu.

  • You should see the customer “John Smith” in the list, for which you just sent a request. For more details about using Explore visit our Help Centre.

  • Click the customer’s name to view the customer profile. This will show you all the details of the customer and the recommendation.

  • Switch to the different tabs to view the order, payment method, device and locations which were also part of the request. From the Orders tab you can view the transaction associated with the order. For more details about the Customer Profile visit our Help Centre.

You have now successfully requested a payment fraud recommendation and investigated the response! You can now begin gathering all the customer and order information in your back-end so you can send a request every time a customer attempts to place an order.

Next steps

Learn how we will work with you throughout the integration process

Learn about the different payment flows

Learn the details of requesting payment fraud recommendations