Customer

POST api.ravelin.com/v2/customer

timestamp integer

required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

customer object

required

The customer registering or updating their account.

Show definition

customerId string

required

The unique identifier of the customer. If your system allows anonymous checkout then we recommend making this the customer's email address.

registrationTime integer

important

The time that the customer registered. If this value is unknown, you can set it to 'now' - Ravelin will retain the earliest value you have sent for this customer ID.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

email string

important

The email address of the customer.

emailVerifiedTime integer

optional

The time at which the customer verified their email, usually by following a link back to your website from an email you sent to their address.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

name string

important

The full name of the customer. If you have the name split into parts, consider familyName and givenName instead.

familyName string

important

The surname/last name of the customer. If you do not have the name split into parts, consider name instead.

givenName string

important

The first/given names of the customer. If you do not have the name split into parts, consider name instead.

telephone string

important

The telephone number of the customer. Best in E.164 format with an international dialing code.

telephoneVerifiedTime integer

optional

The time at which the customer verified their telephone number, usually by confirming a code from an SMS you sent to the number.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

telephoneCountry string

optional

The country the telephone number directs to. Note that the country is not an adequate replacement for the international dialing code in the Dominican Republic or Puerto Rico where multiple dialing codes are used.

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

passwordBcrypted string

optional

The bcypted form of the password for this customer. By its nature, the bcrypt operation is slow. Consider using passwordHashed if this is too slow for you.

passwordHashed string

optional

The SHA256 form of the password for this customer. This must be base64 encoded.

password string

optional

The plaintext password for the customer. We never store the raw password but for security we recommend using one of the hashing options instead of the plaintext option.

passwordChanged boolean

optional

Set to true on events where the password has been changed, false or omit otherwise.

tags object

optional

The tags to set or unset. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.

location object

optional

Show definition

custom object

optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

username string

deprecated

The username the customer would log in with.

gender string

deprecated

The gender of the customer.

balance object

deprecated

The wallet contents of the customer, in the form of an object whose keys are currencies and values the amount held in that currency, in the currency's basic units.

banned boolean

deprecated

Whether the customer is banned in your systems.

country string

deprecated

The home country for this customer. Doesn't change when the customer is briefly abroad.

market string

deprecated

The logical region in which this customer exists.

Pattern: ^[0-9a-z-]*$

marketCity string

deprecated

The logical city in which this customer exists.

Pattern: ^[0-9a-z-]*$

eventType string

optional

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

device object

optional

The device that the customer is using. Mutually exclusive with the deviceId.

Show definition

deviceId string

required

The ID of the device used by the customer to trigger this update.

ipAddress string

important

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

language string

optional

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

userAgent string

important

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent.

model string

important

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

os string

important

The operating system that the device is running.

type string

optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string

optional

The maker of the device.

location object

optional

The geolocated position of the device.

Show definition

custom object

optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

browser string

deprecated

The name of the web browser being used, if applicable. Prefer userAgent.

javascriptEnabled boolean

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean

deprecated

Whether cookies are enabled on the web browser.

screenResolution string

deprecated

The resolution of the screen on the device in the format XxY

deviceId string

optional

The ID of the device that the customer is using. Mutually exclusive with the device.

POST /v2/customer HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "tags": {
      "foo": true,
      "bar": false
    },
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Response

status integer

The HTTP response status code.

timestamp integer

A unix timestamp indicating when we finished handling the request.

message string

If an error has occurred, a description of the error.

data object

Contains our recommendations and related details.

Show definition

action string

Our payment fraud recommendation.

Use this to determine how you should handle the order.

One of: ALLOW, REVIEW, or PREVENT.

score integer

The fraud score produced by the machine learning model. A value between 0 and 100. The higher the number the more fraudulently the model scored the customer.

This may not be the source of the final recommendation, see source.

source string

The source of the action recommendation.

Do not implement any logic based upon this field, we may add new values in the future without warning.

One of: CHARGEBACK, LOOKUP, MANUAL_REVIEW, NETWORK, RATE_LIMIT, RAVELIN, or RULE.

customerId string

The ID of the customer to which this recommendation applies.

scoreId string

A unique ID for this score.

transactionOptimisation object

If transaction optimisation is enabled, and a transaction optimisation recommendation was requested, this will contain the recommendation and related details.

Show definition

warnings array

Warnings when the data you are sending may negatively impact fraud detection.

Show definition

cachedScore boolean

In order to provide resiliency, on the rare occasion that Ravelin isn’t able to calculate a fraud score, a cached score is used to determine the action. If a cached score was used, this field will be true.

effectiveTime string

Response Version 1

Specifies the time the score was originally calculated. Uses the format 2020-01-01T00:00:00.00000000Z.

comment string

Response Version 1

If the customer was manually reviewed, the comment left by the reviewer.

rules object

Response Version 2

Contains details about the rules which were triggered by this customer.

Show definition

connect object

Response Version 2

Contains details about the network the customer is connected to.

Show definition

lookup object

Response Version 2

Contains details about the Lookup results for the customer.

Show definition

market object

Response Version 2

Contains details about the market for the customer.

Show definition

thresholds object

Response Version 2

Contains details about the machine learning fraud score thresholds.

Show definition

orderId string

Response Version 3

The ID of the order used to calculate the recommendation, typically the customer's latest order.

transactionId string

Response Version 3

The ID of the transaction used to calculate the recommendation, typically the customer's latest transaction.

{
  "status": 200,
  "timestamp": 1512828988826,
  "data": {
    "action": "ALLOW",
    "score": 12,
    "source": "RAVELIN",
    "customerId": "abc-123-ZYZ",
    "scoreId": "2bf39d-d1299-31",
    "transactionOptimisation": {
      "transactionId": "123-abc-XYZ",
      "action": "AUTHENTICATE",
      "exemption": "TRANSACTION_RISK_ANALYSIS",
      "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
      "actionSource": "CLIENT_RULE",
      "rules": {
        "triggered": [
          {
            "ruleId": 1,
            "ruleVersion": 1,
            "action": "AUTHENTICATE",
            "exemption": "TRANSACTION_RISK_ANALYSIS",
            "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
            "triggered": true,
            "state": "active"
          }
        ]
      }
    },
    "warnings": [
      {
        "class": "customer-not-found",
        "help": "https://developer.ravelin.com/api/warnings/#customer-not-found",
        "msg": "Customer \"abc-123-ZYZ\" not found."
      }
    ]
  }
}

Feedback

Was this page helpful?