Merchants > API Reference > Endpoints > Customer

Customer

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance where that data is relevant for your business.

Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

Jump to Response

POST api.ravelin.com/v2/customer

Show all

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 guest checkouts then we recommend making this the customer's lower-cased email address.

registrationTime integer important

The time that the customer registered. If this value is unknown, you can set it to the time the request is sent. 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 important

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 important

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.

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

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

country string important

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

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

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.

geohash string optional

deprecated

The geohash of the location.

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.

accountType string important

The type of account which the customer currently has.

See also order.accountType.

One of:

GUEST - The customer has not yet registered for an account, but may have placed an order.
REGISTERED - The customer has registered for an account.

username string optional

deprecated

The username the customer would log in with.

gender string optional

deprecated

The gender of the customer.

balance object optional

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 optional

deprecated

Whether the customer is banned in your systems.

country string optional

deprecated

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

market string optional

deprecated

The logical region in which this customer exists.

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

marketCity string optional

deprecated

The logical city in which this customer exists.

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

passwordBcrypted string optional

deprecated

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

deprecated

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

password string optional

deprecated

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

deprecated

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

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 important

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 optional

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 optional

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

country string important

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

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

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.

geohash string optional

deprecated

The geohash of the location.

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 optional

deprecated

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

javascriptEnabled boolean optional

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean optional

deprecated

Whether cookies are enabled on the web browser.

screenResolution string optional

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 https://api.ravelin.com/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"
    },
    "accountType": "REGISTERED"
  },
  "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

Show all

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 recommended action.

Use this to determine how you should handle the order.

See source for the reason for this recommendation.

One of: ALLOW, REVIEW, or PREVENT.

source string

The reason for our recommended action.

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

Options:

CHARGEBACK - The action was based the customer having at least one unforgiven dispute.
LOOKUP - The action was based on finding the customer in our Lookup fraud database.
MANUAL_REVIEW - The action was based on a manual review.
NETWORK - The action was based on how the customer was connected in our Connect graph network.
RATE_LIMIT - This request was rate-limited. The action was based on the default action for rate-limited requests.
RAVELIN - The action was based on the payment fraud score and your thresholds. See score.
RULE - The action was based on a rule.

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.

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

transactionId string

The identifier for the transaction, as provided in the request.

action string

Our transaction optimisation recommendation for whether the transaction should be authenticated or sent straight to authorisation.

One of: AUTHENTICATE, or AUTHORISE.

exemption string

The SCA exemption type to request for the transaction.

One of: TRANSACTION_RISK_ANALYSIS, or LOW_VALUE.

threeDSChallengePreference string

The preference for whether or not a 3DS challenge should be performed. This field is only present if action is AUTHENTICATE.

One of: NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED, or CHALLENGE_REQUESTED_AS_MANDATE.

actionSource string

The source of the given recommendation.

One of: ML, CLIENT_RULE, COMPLIANCE, or NO_ACTION_SOURCE.

compliance object

Indicates the effect that PSD2 compliance had on the recommendation.

Show definition

type string

Only: PSD2.

optimisable boolean

Indicates if we were able to optimise this transaction.

description string

Indicates why a transaction is non-optimisable. Will only be present if optimisable is false.

excludedRecommendations array

Show definition

recommendation object

Indicates a recommendation which was unavailable for the transaction for compliance reasons.

Show definition

route string

One of: AUTHENTICATE, or AUTHORISE.

exemption string

One of: LOW_VALUE, or TRANSACTION_RISK_ANALYSIS.

description string

Indicates why this recommendation was unavailable for the transaction.

rules object

Indicates which rules were triggered to cause the given recommendation.

Show definition

triggered array

An array containing the details of the rules which were triggered.

Show definition

ruleName string

The name of the rule which triggered to produce the action.

ruleId integer

The ID of the rule which triggered to produce the action.

ruleVersion integer

The version number of the rule which triggered to produce the action.

action string

The action which the rule produced.

One of: NONE, AUTHENTICATE, or AUTHORISE.

exemption string

The exemption which the rule produced.

One of: TRANSACTION_RISK_ANALYSIS, or LOW_VALUE.

threeDSChallengePreference string

The 3DS challenge preference which the rule produced.

One of: NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED, or CHALLENGE_REQUESTED_AS_MANDATE.

triggered boolean

Whether the rule triggered.

state string

The state of the rule when it executed. An active rule is live, whereas a passive rule is in test mode.

One of: active, or passive.

excluded boolean

Whether the recommendation from the rule is excluded for compliance reasons.

threeDS object

Contains an enriched AReq that can be passed on to your 3DS provider. Please see the 3DS Data Enrichment guide for more details.

Show definition

areq object

Contains AReq fields that can be passed on to your 3DS provider.

Show definition

acctInfo object

Information about the cardholder's account.

Show definition

chAccAgeInd string

Length of time that the cardholder has had the account.

One of the following:

01 - No account (guest check-out)
02 - Changed during this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days

chAccDate string

Date that the cardholder opened the account.

nbPurchaseAccount string

Number of purchases by this cardholder account during the last six months.

paymentAccAge string

Date that the payment method was added to the cardholder’s account.

paymentAccInd string

Indicates the length of time since the payment method was added to the cardholder’s account.

One of the following:

01 - No account (guest check-out)
02 - During this transaction
03 - Less than 30 days
04 - 30−60 days
05 - More than 60 days

txnActivityDay string

Number of transactions (successful and abandoned) by this cardholder account across all payment methods in the last 24 hours.

txnActivityYear string

Number of transactions (successful and abandoned) by this cardholder account across all payment methods in the last year.

suspiciousAccActivity string

Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.

One of the following:

01 - No suspicious activity has been observed
02 - Suspicious activity has been observed

threeDSRequestorChallengeInd string

Indicates whether a challenge is requested for this transaction.

One of the following:

01 - No preference
02 - No challenge requested
03 - Challenge requested (3DS Requestor preference)
04 - Challenge requested (mandate, e.g. required for PSD2 compliance)
05 - No challenge requested (transactional risk analysis is already performed)
10 - No challenge requested (utilise low value exemption)

merchantName string

Merchant name assigned by the acquirer.

mcc string

Merchant category code. A card scheme specific code describing the merchant’s type of business, product or service.

addrMatch string

Indicates whether the billing address and shipping address are the same.

One of the following:

Y - Billing address matches shipping address
N - Billing address does not match shipping address

billAddrLine1 string

First line of the billing address associated with the card used for this purchase.

billAddrLine2 string

Second line of the billing address associated with the card used for this purchase.

billAddrCity string

The city of the billing address associated with the card used for this purchase.

billAddrState string

ISO 3166-2 country subdivision code for the state or province of the billing address associated with the card used for this purchase.

billAddrPostCode string

ZIP or other postal code of the billing address associated with the card used for this purchase.

billAddrCountry string

The numeric country code of the billing address associated with the card used for this purchase.

shipAddrLine1 string

First line of the shipping address requested by the cardholder.

shipAddrLine2 string

Second line of the shipping address requested by the cardholder.

shipAddrCity string

City of the shipping address requested by the cardholder.

shipAddrState string

ISO 3166-2 country subdivision code for the state or province of the shipping address requested by the cardholder.

shipAddrPostCode string

The ZIP or other postal code of the shipping address requested by the cardholder.

shipAddrCountry string

Numeric country of the shipping address requested by the cardholder.

warnings array

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

Show definition

class string

Identifier for this warning. Format is [a-z-]+ so you can safely record it in your metrics system.

help string

A link to more information about this class of warning and the impact of not resolving.

msg string

A description indicating why this warning has been issued.

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

passiveAction string

The action which would have been returned if all test rules were live.

triggered array

An array containing the details of the rules which were triggered.

Show definition

ruleName string

The name of the rule which triggered to produce the action.

triggered boolean

Whether the rule triggered.

state string

The state of the rule. If the rule is live mode, the state will be active. If the rule is in test mode, the state will be passive.

One of: active, or passive.

ruleId integer

The ID of the rule which triggered to produce the action.

ruleVersion integer

The version number of the rule which triggered to produce the action.

collections array

The collections the rule belongs to.

category string

The category of the rule which triggered to produce the action, as set in the dashboard when the rule was created.

Options:

payment - Rules created to reduce payment fraud or implement payment-related business logic.
ato - Rules created to prevent account takeover.
txOptimisation - Rules created to optimise transaction routing and manage strong customer authentication exemptions.
refundAbuse - Rules created to prevent refund abuse.
psp - Rules created to optimise payment service providers performance.
supplier - Rules created to prevent supplier fraud.

description string

A human-readable explanation of why the rule triggered.

action string

The action which the rule produced.

connect object

Response Version 2

Contains details about the network the customer is connected to.

Show definition

fraudulent boolean

Indicates that the customer was within a certain distance to fraud in the network. The customer will have received a REVIEW or PREVENT payment fraud recommendation depending on their distance to fraud. See their customer profile in the Ravelin dashboard for more details about their distance to fraud.

lookup object

Response Version 2

Contains details about the Lookup results for the customer.

Show definition

lookupAction string

The payment fraud recommendation which was produced from the Lookup result. May not be the final recommendation.

One of: REVIEW, or PREVENT.

lookupResult object

Contains details about the Lookup results for the customer.

Show definition

industry string

If you have configured Lookup to only search a specific industry, this is the industry which was searched.

hasChargebacks boolean

Indicates whether the customer has disputes in any of the Lookup results.

reviewedAsFraudster boolean

Indicates whether the customer has been reviewed as a fraudster in any of the Lookup results.

email object

Contains details about the Lookup result found using the customer's email address.

Show definition

address string

The email address found in Lookup.

hasChargebacks boolean

Indicates the customer has disputes.

reviewedAsFraudster boolean

Indicates the customer has been reviewed as a fraudster.

telephone object

Contains details about the Lookup result found using the customer's telephone number.

Show definition

number string

The telephone number found in Lookup.

hasChargebacks boolean

Indicates the customer has disputes.

reviewedAsFraudster boolean

Indicates the customer has been reviewed as a fraudster.

ipAddress object

Contains details about the Lookup result found using the customer's IP address.

Show definition

address string

The IP address found in Lookup.

hasChargebacks boolean

Indicates whether the customer has disputes.

reviewedAsFraudster boolean

Indicates whether the customer has been reviewed as a fraudster.

market object

Response Version 2

Contains details about the market for the customer.

Show definition

city string

The city that the customer belongs to, based on their latest order. Used for reporting and risk bucketing.

This is populated from the order.marketCity field from the customer's latest order.

country string

The country the customer is from, based on their latest order. Used for reporting and risk bucketing.

This is populated from the order.country field from the customer's latest order.

region string

The country-group market the customer belongs to. E.g. 'southamerica', 'europe', 'emea'. Used for reporting and risk bucketing.

This is populated from the order.market field from the customer's latest order.

thresholds object

Response Version 2

Contains details about the machine learning fraud score thresholds.

Show definition

review integer

The review fraud score threshold. If the fraud score is used to produce the recommendation, a score above this threshold, but below the prevent threshold will produce a REVIEW recommendation.

prevent integer

The prevent fraud score threshold. If the fraud score is used to produce the recommendation, a score above this threshold will produce a PREVENT recommendation.

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?