Requesting Recommendations

This page explains how to request account takeover recommendations when a customer attempts to login and when a customer attempts to make a purchase. At login we will try and prevent an attacker from gaining access to an account, whereas at checkout we will try and prevent an attacker who has already gained access to an account from placing orders.

On this page:

To request an account takeover recommendation when a customer attempts to log in, send a request to our Login endpoint using the Login Checkpoint. To use the Login Checkpoint add score=login as a query parameter to the URL.

The login object should contain details about the login attempt.

An example request is shown below:

POST https://api.ravelin.com/v3/login?score=login HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "login": {
    "username": "jsmith123@example.com",
    "customerId": "abc-123-XYZ",
    "success": true,
    "authenticationMechanism": {
      "password": {
        "success": true,
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
      }
    },
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google"
  },
  "location": {
    "latitude": 51.503252,
    "longitude": -0.127899
  }
}

An example response is shown below:

{
  "status": 200,
  "success": "true",
  "timestamp": "2021-08-27T12:19:31Z",
  "data": {
    "customerId": "39f54f7c-8ed7-41f8-5260-09881f69f675",
    "action": "ALLOW",
    "score": 20,
    "source": "RAVELIN",
    "scoreId": "4fd50782-b9f7-48be-64e1-820c7cf6dd51",
    "ato": {
      "loginId": "cb8d1ac3-3b2e-440e-bcbd-06030c9da12e",
      "action": "ALLOW"
    }
  },
  "credentialStatus": {
    "passwordBreached": false,
    "usernameBreached": false
  }
}

The data.action field in the response contains our recommendation, you should use this to determine how you handle the login attempt. The table below explains the actions.

Action	What it means
`ALLOW`	We are confident the activity is from a genuine customer. Allow the customer to log in.
`SMS_2FA`	We suspect the activity is not from a genuine customer. We suggest verifying the activity by sending an SMS text message.
`PREVENT`	We are confident the activity is not from a genuine customer. We suggest blocking the login attempt, force resetting the password and notifying the genuine owner of the account .
`PERMIT`	This is a legacy action. Treat in the same way as `ALLOW`.
`BLOCK`	This is a legacy action. Treat in the same way as `PREVENT`.

You can also configure additional custom actions which suit your business. Please speak to our integration team to configure these.

The response also contains the credentialStatus field. This contains information about whether the credentials used in the login have been breached. You can read more about this in our breached credentials guide.

Recommendations at checkout

To request an account takeover recommendation when a customer attempts to place an order at checkout, send a request to our Checkout endpoint using the Checkout Pre-auth or Checkout Post-auth checkpoint.

If you are integrated with Payment Fraud you may already be sending a Checkout request. Our recommendation at checkout will take into account all the types of fraud you are integrated to prevent.

An example request is shown below:

POST https://api.ravelin.com/v2/checkout?score=checkoutPreAuth HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "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": "81.152.92.84"
  },
  "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"
    }
  ]
}

An example response is shown below:

{
  "status": 200,
  "timestamp": 1652103786,
  "success": "true",
  "data": {
    "customerId": "abc-123-ZYZ",
    "action": "ALLOW",
    "score": 2,
    "source": "RAVELIN",
    "scoreId": "8f7c4a67-c944-4ae7-7a76-d9a7a3942dd5"
  }
}

The data.action field in the response contains our recommendation, you should use this to determine how you handle the order. The table below explains the possible actions.

Action	What it means
`ALLOW`	We are confident the activity is from a genuine customer. Allow the order to proceed.
`REVIEW`	We suspect the activity is not from a genuine customer. Take extra verification steps for the order.
`3DS_AUTHENTICATE`	We suspect the activity is not from a genuine customer. We suggest verifying the customer using 3D Secure.
`MANUAL_REVIEW`	We suspect the activity is not from a genuine customer. We suggest verifying the customer by doing a manual review.
`PREVENT`	We are confident the activity is from a fraudster who has compromised the account. Prevent the order.

You can also configure additional custom actions which suit your business. Please speak to our integration team to configure these.

Next steps

Notify us when a customer reclaims their account

Test your account takeover integration

Feedback

Was this page helpful?

Requesting Recommendations

Recommendations at login

Recommendations at checkout

Next steps

Feedback