Merchants > API Reference > Endpoints > Registration

Registration

This endpoint is used to request a recommendation when a customer or supplier attempts to register for a new account. Ravelin will recommend whether you should allow the user to register. This endpoint is also used to notify Ravelin about the outcome of registration attempts.

See our Account Registration Abuse guide for how to integrate with this endpoint.

To request a recommendation at this endpoint use the Account Registration checkpoint.

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 /v2/registration

Show all

timestamp integer required

Time at which the user requested the registration. A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

registration object required

The details of the user who is registering. If a customer is registering provide additional details in the customer field. If a supplier is registering provide additional details in the supplier field.

Show definition

success boolean optional

If the registration attempt was successful and the account was created.

username string optional

The username of the customer. This is the unique string that ties this particular customer to the registration mechanism used. Typically this is the email address.

app object important

Details of the mobile or web app used to make this registration attempt.

Show definition

name string optional

The name or brand of the app, used to segment logins. Use the name that customer sees when installing and using the app, or the website title. Shouldn't repeat the platform or domain.

platform string optional

Where this app runs.

One of: ios, android, web, or mobile-web.

domain string optional

The domain from the URL of the web app, using the characters a-z0-9-..

Pattern: ^[a-z0-9-\.]+$

registrationMechanism object optional

At least one registration mechanism must be provided. More than one may be provided. For example a password and a oneTimeCode may be used to authenticate.

Any of the following:

Show definition

password object optional

Provided if the user is using a password to register.

When sending a password registration mechanism, we encourage you to also send hashed versions of the password in the passwordHashed, emailPasswordSHA256, and passwordSHA1SHA256 fields. We use these fields to check our breached credentials database.

Our breached credentials database contains data from various sources which is hashed in different ways. Sending hashedPassword, emailPasswordSHA256, and passwordSHA1SHA256 allows us to check the data from all our sources.

Show definition

passwordHashed string optional

The SHA256 hashed form of the password. This is used to check the password against our ever updating list of breached credentials. This hash is not stored by Ravelin. It is used to check our breached credential database and then discarded.

emailPasswordSHA256 string optional

The SHA256 hash of the email and password concatenated.

For example: SHA256(email + password) or SHA256("user@example.compassword123").

This is used to check the user's credentials against our breached credentials database and then discarded. This hash is not stored by Ravelin.

passwordSHA1SHA256 string optional

The SHA256 hash of the SHA1 hash of the password.

For example: SHA256(SHA1(password)).

This is used to check the user's credentials against our breached credentials database and then discarded. This hash is not stored by Ravelin.

success boolean optional

If the registration was successful.

failureReason string optional

This is required if success is set to false.

One of the following:

EMAIL_ALREADY_PRESENT - The registration failed because the email is already associated with an existing account.
PASSWORD_TOO_SIMPLE - The password doesn't fill the security requirement of your website.

social object optional

Provided if the user registers via a social login provider.

oneTimeCode object optional

Provided if a one time code such as those used by Google Auth is used.

Show definition

success boolean optional

If the registration was successful

failureReason string optional

This is required if success is set to false.

One of the following:

INVALID_CODE - The one time code was incorrect.
CODE_TIMEOUT - The one time code verification timed out.
INTERNAL_ERROR - An error occurred during the one time code verification process.
RATE_LIMIT - The rate limit was exceeded.
BANNED_USER - The user is banned from using this one time code verification.

captcha object optional

Provided if reCAPTCHA was performed.

Show definition

success boolean optional

If the registration was successful.

failureReason string optional

This is required if success is set to false.

One of the following:

TIMEOUT - The CAPTCHA has timeout during the registration.
INTERNAL_ERROR - An internal error has occurred.
FAILED_TEST - The CAPTCHA provided was incorrect.

bioMetric object optional

Provided if biometric registration is used.

Show definition

success boolean optional

If the authentication was successful.

failureReason string optional

This is required if success is set to false.

One of the following:

TIMEOUT - The biometric verification has timed out.
INTERNAL_ERROR - An internal error occurred during the biometric verification.
BANNED_USER - The user is banned from using this biometric verification.

guestAccount boolean optional

If the registration attempt was made after the customer had checked out as a guest. Only relevant for customer registrations. Will be ignored for supplier registrations.

marketingEmailsEnabled boolean optional

If the user accepted to receive marketing emails when they registered.

customer object optional

The customer trying to register.

Show definition

customerId string optional

The unique identifier of the customer. If your system allows anonymous checkout then we recommend making this the customer's email address. You only need to send the customer ID if the registration was successful.

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 user. 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 user. This must be base64 encoded.

password string optional

The plaintext password for the user. 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.

registrationTime integer optional

The time that the customer registered. If the registrationTime is not provided Ravelin will use the request timestamp value.

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

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.

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.

supplier object optional

The supplier trying to register.

Show definition

type string required

The role of the supplier in order fulfilment.

One of:

driver - A taxi driver, private hire driver, chauffeur or other type of person that drives people in a passenger motor vehicle.
courier - A courier, bike courier or delivery driver.
restaurant - A restaurant or cafe that sells prepared food. May also provide delivery.
shop - A shop which sells goods other than prepared food. May also provide delivery.
seller - An individual who sells goods or services and which is not covered by any of the other supplier types.
contentCreator - A supplier that is creating content, for example, music, podcasts or video. The type of content creator should be set in the category field.
promoter - A supplier that promotes music concerts, festivals, sporting events or other events or experiences, or a supplier that promotes products or services, for example an affiliate partner.
other - Any other type of supplier which is not covered by the other types.

supplierId string optional

The unique identifier of the supplier.

groupId string important

The unique identifier of the supplier's parent organisation.

groupName string important

The name of the supplier's parent organisation.

registrationTime integer important

The time that the supplier 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 supplier 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 supplier.

emailVerifiedTime integer optional

The time at which the supplier 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 supplier.

telephone string important

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

telephoneVerifiedTime integer optional

The time at which the supplier 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

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

homeLocation object optional

Show definition

country string important

A 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.

taxAddress object optional

Store tax address information at the time of payout to compare it to suppliers’ other addresses. Tax info maps to each payout object and is immutable. This could be different in any subsequent payouts.

Show definition

country string important

A 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.

market string optional

The logical region in which this supplier exists.

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

marketCountry string optional

The logical country for this supplier. Doesn't change when the supplier is briefly abroad.

marketCity string optional

The logical city in which this supplier exists.

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

level string optional

The name of the current level of the supplier.

employmentType string optional

This describes how the supplier is employed by your organisation, e.g. "selfEmployed", or "partTime".

transportType string optional

The type of transport this supplier uses.

category string optional

The highest level category that applies to this supplier.

accountType string optional

The type of supplier account.

One of:

INDIVIDUAL - To be used when the supplier account is an individual account, for example an individual person selling goods or an individual person creating content under their own name.
BUSINESS - To be used when the supplier account is a business account, for example when there is a business or organisation or company associated to the supplier account, a shop selling goods, a restaurant selling food, or a business creating content.

accountPlatform string optional

The platform where the supplier account was created.

identityVerified boolean optional

This field would be used to indicate the status of the supplier's identity verification process, which is usually conducted to ensure compliance with anti-money laundering and other regulations.

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.

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.

device object optional

The device used by the customer to trigger this update.

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

A 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

POST https://api.ravelin.com/v2/registration HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "timestamp": 1512828988826,
    "registration": {
        "app": {
            "name": "Our App Lite",
            "platform": "web",
            "domain": "us.brand.com"
        },
        "username": "test1@ravelin.com",
        "registrationMechanism": {
            "password": {
                "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f",
                "success": false,
                "failureReason": "PASSWORD_TOO_SIMPLE"
            }
        },
        "guestAccount": false,
        "marketingEmailsEnabled": false,
        "success": false
    },
    "supplier": {
        "supplierId": "abc-123-ZYZ",
        "name": "John Smith",
        "groupId": "abc-123",
        "groupName": "Burger Chain",
        "email": "jsmith123@example.com",
        "emailVerifiedTime": 1512828988826,
        "telephone": "+16045555555",
        "telephoneVerifiedTime": 1512828988826,
        "telephoneCountry": "GBR",
        "type": "driver",
        "level": "gold",
        "employmentType": "selfEmployed",
        "transportType": "car",
        "category": "private-hire",
        "tags": {
            "foo": true,
            "bar": false
        }
    },
    "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, 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:

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.

supplierId string

If the request contained a successful supplier registration, the ID of the supplier which was created.

customerId string

If the request contained a successful customer registration, the ID of the customer which was created.

registrationId string

An ID generated by Ravelin in order to identify the registration to which this recommendation applies.

rules object

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

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

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.

description string

A human-readable explanation of why the rule triggered.

action string

The action which the rule produced.

credentialStatus object

Contains details about whether the credentials have been found in our breached credentials database.

Show definition

passwordBreached boolean

Whether the password was found in our breached credentials database.

usernameBreached boolean

Whether the username was found in our breached credentials database.

{
  "status": 200,
  "timestamp": 1512828998826,
  "data": {
    "action": "PREVENT",
    "source": "RULE",
    "supplierId": "abc-123-ZYZ",
    "registrationId": "ewq-234-dfg",
    "rules": {
      "passiveAction": "PREVENT",
      "triggered": [
        {
          "ruleId": 123,
          "ruleVersion": 1,
          "state": "active",
          "action": "PREVENT",
          "description": "Registration email is from a disposable email provider is equal to true."
        }
      ]
    }
  }
}

Feedback

Was this page helpful?