Core V2 API Reference

Welcome to the Ravelin API. Our mission for the API is to make it predictable, easy to understand and painless to integrate with. If there is anything you feel we can do to improve our API, make it easier to understand, or if you encounter any bugs or unexpected behaviour, please email api@ravelin.com and a Ravelin developer will get back to you as soon as possible.

There are 3 key parts to a Ravelin integration:

• Events - sending data to Ravelin in real time
• Backfill - sending Ravelin historical data in order to tailor our system to your business
• Scoring - acting on the recommendations that Ravelin provides

We highly recommend completing all three parts to get the best from Ravelin.

Connection

Events are sent to Ravelin as JSON objects to a POST endpoint over HTTPS:

https://api.ravelin.com/v2/...

Ravelin uses API keys to allow access to the API. The API key can be found under the Settings menu in the dashboard. You can register a new Ravelin API key by contacting your account manager. Ravelin expects the API key to be included in the authorization header for all API requests:

# Using curl, pass the authentication header with each request
curl "https://api.ravelin.com/v2/auth/checktoken" \
  -H "Authorization: token sk_live_XXXXXXXX"

Make sure to replace sk_live_XXXXXXXX with your API key.

When submitting a JSON request, make sure to include the JSON mime-type:

Content-Type: application/json; charset=utf-8

Events

To create or update entities on Ravelin, send a POST request with a JSON body to one of the endpoints described below.

Event Metadata

These fields are present the top-level of every event:

POST /v2/checkout (All-in-One)

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

{
  "timestamp": 1429029735,

  "customer": {
    "customerId": "61283761287361",
    "familyName": "Twain",
    "givenName": "Mark",
    "email": "marktwain@gmail.com",
    "registrationTime": 1429029731
  },

  "order": {
    "orderId": "hXyUc5ef2zhOrdqmRiC",
    "price": 4675,
    "currency": "GBP",
    "creationTime": 1429029735,
    "items": [
      {
        "sku": "3726-8",
        "name": "Women's Arch Sweater M 55",
        "price": 1990,
        "currency": "GBP",
        "quantity": 2
      },
      {
        "sku": "3731-4",
        "name": "Women's Yellow Tee M 54",
        "price": 695,
        "currency": "GBP",
        "quantity": 1
      }
    ],
    "status": {
    	"stage": "fulfilled"
    }
  },

  "paymentMethod": {
    "paymentMethodId": "783917",
    "instrumentId": "card_16nWlGHD2LFseSsHaUp9kIW2",
    "registrationTime": 1429029735,
    "nickName": "MasterCard **** 4242",
    "methodType": "card",
    "cardBin": "123456",
    "cardLastFour": "4242",
    "cardType": "mastercard",
    "expiryMonth": 6,
    "expiryYear": 2019,
    "lastVerified": 1444166299,
    "successfulRegistration": true,
    "prepaidCard": false,
    "countryIssued": "GBR"
  },

  "transaction": {
    "transactionId": "f61f8594e06459fa046707c36159bb35",
    "email": "james.tate@gmail.com",
    "amount": 4675,
    "currency": "GBP",
    "type": "capture"
  }
}

The simplest, most reliable way to integrate Ravelin into your checkout flow is using our checkout event endpoint. A single v2/checkout submission contains all customer, order, payment method and transaction information for a single payment attempt, and should be sent to Ravelin at the exact moment your customer attempts to complete their purchase. Having access to all of this information at once is not always possible in some systems, so we also support sending these entities individually using our other endpoints, but use of the checkout endpoint decreases the likelihood of pesky race-conditions and of overlooking parts of the payment journey.

For information about the individual fields required for each of these entities, please refer to the documentation for their individual endpoints; their contents are identical.

POST /v2/chargeback

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

{
  "timestamp": 1429031911,

  "chargeback": {
    "chargebackId": "dp_15RsQX2eZvKYlo2C0MFNUWJC",
    "gateway": "stripe",
    "gatewayReference": "ch_15RsQR2eZvKYlo2CA8IfzCX0",
    "reason": "general",
    "status": "lost",
    "amount": 195,
    "currency": "USD",
    "disputeTime": 1422915137,
    "liabilityShifted": true,
    "nonFraud": false
  }
}

Chargeback

A chargeback happens when a customer disputes a payment on their credit card account. Communicate this event to Ravelin using the chargeback endpoint. This is a mandatory component of all integrations; our ability to predict fraud comes from our understanding of previous examples of fraudulent behaviour.

Most PSPs will associate two IDs with every chargeback: a unique identifier for the chargeback itself, and the identifier for the original transaction that is being disputed. It is the latter that must be sent in the gatewayReference field, and it must correspond to a previously sent transaction.

For PSPs that associate chargebacks via the Merchant transaction ID, such as Computop, the transactionId can be specified in lieu of the gatewayReference.

If no transaction with a matching gatewayReference or transactionId is found, this chargeback is ignored.

Valid chargeback status strings:

If your system lends itself more to sending individual entities as they become available, you can use the individual entity endpoints detailed below.

POST /v2/customer

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

{
  "timestamp": 1429029735,

  "customer": {
    "customerId": "61283761287361",
    "registrationTime": 1429029731,
    "familyName": "Twain",
    "givenName": "Mark",
    "email": "marktwain@gmail.com",
    "location": {
      "street1": "James St",
      "city": "Darwen",
      "region": "Blackburn with Darwen",
      "postalCode": "BB3 1AS",
      "country": "GBR",
      "latitude": 53.697471,
      "longitude": -2.470891
    },
    "custom": {
      "newsletter": false,
      "invitedBy": "7198737117"
    }
  }
}

When a customer registers, or changes their profile, send their info to the customer endpoint. Creating a new customer and updating an existing customer is the same operation; a POST to this endpoint is an upsert.

All customer data, except the customerId, is optional.

Customer

Customers are your users, the central entity that all Ravelin fraud detection revolves around.

All fields except customerId are optional, but the more information, the better. If you send the customerId field it will be considered an update. Therefore a new property will overwrite any previously received property for this customer.

Data in the custom field is not initially mapped to our internal properties, but we do periodically check if there are any fraud signals that we can use to improve the scoring. If so, we retroactively extract the data from all previous events that specified it, without requiring you to send it again.

Use the custom field for anything you might want to tell us about a customer which you think could contribute to determining whether or not it’s a fraudulent account. If you are in any doubt as whether to send a field to Ravelin, you should send it.

Location

Locations are time-series data: every time you attach a location to a customer, we will record it separately, instead of overwriting the previous location.

You can send Ravelin data with street addresses, and we will reverse geocode to obtain the latitude and longitude, or vice versa. If you have both, then that’s fab.

POST /v2/order

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

{
  "timestamp": 1429029735,

  "customerId": "61283761287361",

  "order": {
    "orderId": "hXyUc5ef2zhOrdqmRiC",
    "price": 4675,
    "currency": "GBP",
    "market": "europe",
    "country": "GBR",
    "marketCity": "london",
    "items": [
      {
        "sku": "3726-8",
        "name": "Women's Arch Sweater M 55",
        "price": 1990,
        "currency": "GBP",
        "quantity": 2
      },
      {
        "sku": "3731-4",
        "name": "Women's Yellow Tee M 54",
        "price": 695,
        "currency": "GBP",
        "quantity": 1
      }
    ],
    "from": {
      "street1": "19 Gosport Walk",
      "postalCode": "N17 9QD",
      "region": "London",
      "country": "GBR"
    },
    "to": {
      "street1": "73 Braganza St",
      "postalCode": "SE17 3RD",
      "region": "London",
      "country": "GBR"
    },
    "creationTime": 1429029730,
    "executionTime": 1429029732,
    "status": {
      "stage": "pending",
      "actor": "buyer"
    }
  }
}

When an order is started, or new information becomes available (e.g. the price changes), send an order event.

Order

An order is an intent to purchase a good or service from your business by a customer.

Order Status

Order statuses specify the current status of the order.

Valid reasons for different order status stages:

Item

Items describe the elements that make up an order, like the different items in a shopping basket, or a single taxi ride. An item is always unique across orders, even if it represents the same underlying thing you can buy. That is inferred through equal SKU’s.

This means two orders can have an item with the same SKU, but different prices or names, without any problems.

Item arrays are atomic blocks: to update one item in the basket, the entire basket must be resubmitted.

To add a new item: send the entire new items array with the extra item. To remove an item from a basket: resend the new items array, without that item.

Event Ticket

An Event Ticket is an object that can be used to add addition item information for ticketed events such as sporting events, tourist attractions, music concerts or guided tours.

Ticket

A ticket refer to the access that has been purchased to attend an event. It includes information about the type of ticket that was sold, the dates the ticket is valid between and whether or not this ticket is refundable or not.

Event

An event contains the information about a paid customer experience, such as a one off event like a music concert or tech conference, or it might refer to access to a recurring event such as a theme park or tourist attraction.

Venue

A venue is a location at which an event is set to occur at.

Guest

A guest contains information for an individual who may not necessarily be the customer. In a scenario a ticket has been purchased on behalf of another individual, or when a ticket requires the names of those who will be in attendance to be specified, you can use the guest property to send this information to Ravelin.

POST /v2/paymentmethod

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

{
  "timestamp": 1429029735,
  "customerId": "61283761287361",

  "paymentMethod": {
    "paymentMethodId": "783917",
    "instrumentId": "card_16nWlGHD2LFseSsHaUp9kIW2",
    "registrationTime": 1429029735,
    "methodType": "card",
    "cardBin": "123456",
    "cardLastFour": "4242",
    "cardType": "mastercard",
    "expiryMonth": 6,
    "expiryYear": 2019,
    "lastVerified": 1444166299,
    "successfulRegistration": true,
    "countryIssued": "GBR",
    "billingAddress":{
      "street1": "73 Braganza St",
      "postalCode": "SE17 3RD",
      "region": "London",
      "country": "GBR"
    }
  }
}

A customer registers a payment method. Whether successful or not, this information is important.

Most of this information is provided by payment service providers after tokenization of a card.

Note for Stripe customers: after tokenization, Stripe does not provide the BIN number (first six digits). This number contains important information about the bank (not the account), so if there is a way to obtain this directly from the user input, before tokenizing the card, please send it along with the rest of the post-tokenization Stripe response.

PCI certification is not required for handling of the BIN number or the last four digits of a payment card.

Payment Method

A payment method is a way that a customer has registered or used to pay your business. It could appear in multiple forms: card, cash, bitcoin, voucher, etc.

Please do not send the the CVV code on the card. The first six digits (the BIN) and the last four are fine. If you wish to send us raw card numbers please use Client-side Card Encryption.

Credit (& Debit) Cards

These fields exist on the payment method entity only when the methodType is card.

Most of this information is provided by payment service providers after tokenization of a card.

Note for Stripe customers: after tokenization, Stripe does not provide the BIN number (first six digits). This number contains important information about the bank (not the account), so if there is a way to obtain this directly from the user input, before tokenizing the card, please send it along with the rest of the post-tokenization Stripe response.

PCI certification is not required for handling of the BIN number or the last four digits of a payment card.

PayPal

These fields exist on the payment method entity only when the methodType is paypal.

Saving Payment Methods after Checkout

When the paymentMethodId of the payment method you have sent to Ravelin is unknown to your system – perhaps because you omitted the paymentMethodId when using Client-Side Encryption, then you may opt to refer back to a payment method via a transaction which used it.

For example, if a customer has successfully gone through the fraud check:

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

{
  "timestamp": 1536577389238679409,
  "customerId": "cust-123",
  "order": {"orderId": "ord-123"},
  "transaction": {
  	"transactionId": "tx-123",
  	"amount": 123
  },
  "paymentMethod": {
    "methodType": "paymentMethodCipher",
    "cardCiphertext": "...",
    "aesKeyCiphertext": "...",
    "algorithm": "RSA_WITH_AES_256_GCM",
    "ravelinjsVersion": "0.0.9"
  }
}

… and completed their order successfully:

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

{
  "timestamp": 1536577500948371039,
  "customerId": "cust-123",
  "order": {"orderId": "ord-123", "status": {"stage": "fulfilled"}},
  "transaction": {
    "transactionId": "tx-123",
    "success": true,
    "amount": 123
  }
}

If the customer thens opts to save the payment method to their account, you can let Ravelin know its identifier in your system so that you can refer back to it in future using only, for example, "paymentMethodId": "pm-123" by:

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

{
  "timestamp": 1536578369411033583,
  "customerId": "cust-123",
  "paymentMethod": {
    "paymentMethodId": "pm-123",
    "methodType": "fromTransaction",
    "transactionId": "tx-123"
  }
}

These fields exist on the payment method entity only when the methodType is fromTransaction. Either transactionId or both gateway and gatewayReference are required.

POST /v2/pretransaction

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

{
  "timestamp": 1429029735,
  "customerId": "61283761287361",
  "paymentMethodId": "783917",
  "orderId": "n1QSYK0ceGNZqU28ien3",

  "transaction": {
    "transactionId": "f61f8594e06459fa046707c36159bb35",
    "amount": 4675,
    "currency": "GBP",
    "type": "auth_capture",
    "gateway": "stripe",

    "3ds": {
      "attempted": true,
      "startTime": 1429029735
    }
  }
}

Transactions transfer money from the customer to the vendor, to fulfil an order. One transaction usually fulfils an order, but not always (e.g. outstanding credit, or split payments).

If a transaction event call is intended to get a fraud indication before the transaction is placed with the PSP, some of the transaction properties won’t be available. In that case, send us a preTransaction event instead. This event carries all the information you have available just as a user clicked the “buy” button, but before you’ve passed it through to the PSP.

Pre-Transaction

Pre-transactions are transactions before they have been submitted to a PSP for processing.

POST /v2/transaction

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

{
  "timestamp": 1429029735,
  "customerId": "61283761287361",
  "paymentMethodId": "783917",
  "orderId": "n1QSYK0ceGNZqU28ien3",

  "transaction": {
    "transactionId": "f61f8594e06459fa046707c36159bb35",
    "amount": 4675,
    "currency": "GBP",

    "success": true,
    "authCode": "1000",
    "gateway": "stripe",
    "gatewayReference": "tr_16oaY72eZvKYlo2CE5ZDq9Vh",
    "avsResultCode": {
      "street": "A",
      "postalCode": "M"
    },
    "cvvResultCode": "M",
    "type": "auth_capture",

    "3ds": {
      "attempted": true,
      "success": true,
      "startTime": 1429029705,
      "endTime": 1429029734
    }
  }
}

Once the transaction has been placed with the PSP, send the results to Ravelin, regardless of success or failure status.

If this transaction was already submitted as a preTransaction event, make sure to use the same transactionId.

Transaction

3D Secure

If the customer is being through a 3D Secure payment flow, send 3DS properties on the resulting transactions.

Verification Result Code

CVV, ZIP code and street name verification is handled in similar fashion by most PSPs: a single letter (or short string) per check indicating the result of that specific check. Ravelin accepts strings as supplied by Braintree, Stripe and similar PSPs; please ensure you set the correct value in the transaction.gateway field so we can properly interpret the result code value.

The result code can be one of: M, N, U, I, A, pass, fail, unavailable, or unchecked.

AVS Result Code

Address verification is a compound check: both the street name and ZIP code are independently verified, and both get an independent result code from your PSP:

Transaction Type

Card transactions come in various flavours, the most common being auth and capture. Ravelin supports this model by accepting multiple separate transactions for each step of the payment, as it happens on your system.

Refund Transaction Payment Methods

When sending a refund transaction it can be useful to refer back to the payment method by the transaction which originally debited the card. For example, if a customer has successfully gone through the fraud check:

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

{
  "timestamp": 1536577389238679409,
  "customer": {"customerId": "cust-123"},
  "order": {"orderId": "ord-123"},
  "transaction": {"transactionId": "tx-123", "amount": 123},
  "paymentMethod": {
    "methodType": "paymentMethodCipher",
    "cardCiphertext": "...",
    "aesKeyCiphertext": "...",
    "algorithm": "RSA_WITH_AES_256_GCM",
    "ravelinjsVersion": "0.0.9"
  }
}

… and completed their order successfully:

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

{
  "timestamp": 1536577500948371039,
  "customerId": "cust-123",
  "order": {"orderId": "ord-123", "status": {"stage": "fulfilled"}},
  "transaction": {"transactionId": "tx-123", "success": true, "amount": 123}
}

We can then create a refund transaction without then knowing the payment method by instead knowing that the refund was for transaction tx-123:

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

{
  "timestamp": 1536578369411033583,
  "customerId": "cust-123",
  "orderId": "ord-123",
  "transaction": {
    "transactionId": "refund-123",
    "type": "refund",
    "gateway": "my-psp",
    "gatewayReference": "gw-ref-123",
    "success": true,
    "amount": 1000,
    "currency": "GBP"
  },
  "paymentMethod": {
    "methodType": "fromTransaction",
    "transactionId": "tx-123"
  }
}

POST /v2/login

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

{
  "timestamp": 1429029750,
  "customerId": "61283761287361",
  "tempCustomerId": "89QsaT/H17wnB4vuyRdd",

  "device": {
    "deviceId": "2b6f0cc904d137be2e1730235f5664094b831186",
    "type": "phone",
    "manufacturer": "apple",
    "model": "iPhone8,1",
    "os": "iOS 8",
    "ipAddress": "22.231.113.64"
  }
}

If previous events for this customer were sent as anonymous events (with a tempCustomerId instead of a customerId), set the tempCustomerId field here to tie those together.

Optionally, if there is device information available, send Ravelin information about the device the customer is using in this event.

Device

A device is a physical object that a customer uses to interact with your application. Examples include a mobile phone, tablet or laptop.

The deviceId can come directly from the device, or it can be a unique ID your business defines.

POST /v2/paymentmethod/voucher

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

{
  "timestamp": 1429031911,
  "customerId": "cust-123",
  "voucherRedemption": {
    "paymentMethodId": "cust-123-order-abc-TUBE",
    "voucherType": "GENERAL",
    "voucherCode": "TUBE",
    "redemptionTime": 1429031855,
    "value": 1000,
    "currency": "GBP",
    "success": true
  }
}

Voucher Redemption

If part an order is being paid for through use of a voucher or of credit associated to a user’s account, you can communicate that to Ravelin with a paymentmethod/voucher event. For these redemptions, you can either provide the voucher details alongside its redemption details, or you can specify a previously registered voucher via the paymentMethodId.

Markets

The market for a customer can be specified using the market, country & marketCity on customer and order events. If any of these three fields is non-empty on the customer, then the effective market for the customer is specified by the values on the customer. If all three fields are empty on the customer, then the effective market for the customer is specified by the fields on their latest order. The inability to ‘forget’ a market on a customer, regardless if any order market information is sent, has lead to confusion in the past: thus we have deprecated them. We recommend you set values for these fields only on order events.

The effective market for a customer is used in reporting, risk thresholds, for model features, and for segmenting customers in the dashboard.

We recommend you use market, country & marketCity in a hierarchical manner, with market specifying the region (e.g. europe, emea, apac, etc).

Anonymous activity

Events can occur before a customer ID is known. For example: adding items to a shopping cart, and only being shown a “login or register now” form at check-out time; the cart events will not have an associated customerId.

For these events, there is the tempCustomerId field: it can occur at the top-level of most events which accept a customerId. This field should contain a session ID (or otherwise consistent value that will be used to later tie the events to a real customer, at log in time).

When a customer logs in (or registers), send a “log in event” (see above) to tie all previous tempCustomerId events to a real customer.

Except for the log in event, the tempCustomerId and customerId fields are mutually exclusive.

Vault

[DEPRECATION NOTICE] The Ravelin Vault is DEPRECATED. Support will continue to be offered, but for those wishing to securely send card information through to Ravelin, please consult our Client-side Card Encryption documention instead.

The Vault must be used whenever sending raw card numbers to Ravelin.

By sending full card numbers to Ravelin we are able to match cards across our entire network and catch more fraudsters before a transaction takes place. Please note the different sub-domain: https://vault.ravelin.com.

There are two ways to send the raw card number (the “PAN”) to the Ravelin Vault: directly from the client, or through your server. Which method is right for you depends on whether or not you already send the raw PAN to your own servers, or if you don’t (e.g. using a “hosted checkout page”).

Raw card on your server

{
  "timestamp": 1429029735,
  "customerId": "61283761287361",

  "paymentMethod": {
    "paymentMethodId": "783917",
    "instrumentId": "card_16nWlGHD2LFseSsHaUp9kIW2",
    "registrationTime": 1429029735,
    "methodType": "card",
    "cardBin": "123456",
    "cardLastFour": "4242",
    "cardType": "mastercard",
    "expiryMonth": 6,
    "expiryYear": 2019,
    "lastVerified": 1444166299,
    "successfulRegistration": true,
    "countryIssued": "GBR",
    "pan": "1234567891234567"
  }
}

If you already have the PAN available on your own servers (even without storing it), you can send it directly to Ravelin in any event that would normally accept a paymentMethod field.

The API for these endpoints are very similar to the regular API, with only a few differences:

• no cardBin and no cardLastFour on the paymentMethod entity,
• a pan field on the paymentMethod entity,
• the hostname is not api.ravelin.com but vault.ravelin.com

The full schema for a paymentMethod entity on the Vault:

Raw card NOT on your server

# Tokenization Request

curl -H 'Authorization: token pk_live_XXXXXXXXX' \
     -H 'Content-Type: application/json' \
     -d '{"pan":"5105105105105100", "expiryMonth":12, "expiryYear":2020}' \
     https://vault.ravelin.com/v2/card

# Tokenization Response

{
    "cardToken":"tk-8c46447a-fdce-4e48-88aa-234a3c014330",
    "cardBin":"510510",
    "cardLastFour":"5100",
    "expiryMonth":12,
    "expiryYear":2020
}

If you never send the full card number from the client (browser or app) to your own servers (e.g. by using a hosted payment page), you will need to use the public tokenization API for the Ravelin Vault.

This is a three-step process:

1. The client sends the full PAN to the Ravelin Vault, and gets a token
2. The client sends this token back to the server
3. The server sends a regular Ravelin event to the regular, non-vault Ravelin API, but using the Vault token to identify the card.

Using your secret key for the Vault will not work. Otherwise, your users would be able to read them, and use them to get full access to the entire Ravelin API. The publishable key only allows write access to the Vault, no read access.

The Vault token you receive from the Ravelin Vault is not under PCI scope, so you don’t need to worry about having credit card numbers on your servers.

Scoring

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "123456789",
        "action": "PREVENT",
        "score": 77,
        "source": "RAVELIN",
        "scoreId": "2bf39d-d1299-31",
        "comment": "",
        "warnings": [{
            "class": "order-absent-currency",
            "help": "https://developer.ravelin.com/apis/warnings/#order-absent-currency",
            "msg": "Order \"example-order-1\" does not have a currency."
        }]
    }
}

Using the information supplied to Ravelin through the event endpoints, individual customers are categorized in one of three buckets:

• ALLOW
• REVIEW
• PREVENT

This information is sent:

• in the response body to scored POST requests (with ?score=true), and
• as a HTTP callback.

In both cases, the score payload is a JSON object with the same schema:

Requesting a score

Events sent to Ravelin using POST requests get an empty response body by default. The information is stored in our system and no further action is taken during the request.

To force an immediate rescoring based on the information received up to and including an event: add the ?score=true query parameter. For example, the /v2/order endpoint becomes:

POST /v2/order?score=true

This will do two things:

1. Process the event payload (as usual, see events)
2. Force immediate recalculation of the score and return it

The score will be calculated based on the information in this event, and in all events previously received and met with a 200 OK status.

Suggested handling

The ?score=true query parameter is available on every event endpoint. Specify it when you want to make a decision during an order flow about where to go, based on the fraud score: allow regular check-out, or send down an extra validation path?

The most important field in the payload is action:

Other fields are provided for analytic and debugging purposes.

Callbacks

[DEPRECATION NOTICE] Callbacks are deprecated. You can still review our old callbacks documentation if you use them.

Label

The Label API allows you to change the status of a customer. This can be used to tie your own customer management tools into Ravelin.

Sending this label is the same as pressing the Genuine or Fraudster button in the Ravelin Dashboard.

POST /v2/label/customer

{
    "customerId": "customer1",
    "label": "GENUINE",
    "comment": "This customer called up and we have determined he is not a fraudster",
    "reviewer": {
      "name": "Bilbo Baggins",
      "email": "bilbo.b@shiremail.com"
    }
}

This is an optional API integration. You may manage these labels completely within the Ravelin Dashboard. This is simply a helper API so you can integrate labelling in your own tools.

Reviewer

The reviewer is the person who is doing the review. Their details will appear in the audit log on the dashboard so you are able to see who did this review and why.

Tag

The Tags API allows you to change the tags attached to a customer. This can be used to tie your own customer management tools into Ravelin. When a tag is attached to a customer it will apply the label (GENUINE, FRAUDSTER) associated with that tag to that customer as well.

Calling this api is the same as setting a tag in the Ravelin Dashboard.

POST /v2/tag/customer

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

{
    "timestamp": 1429029735,

    "customerId": "61283761287361",
    "tagNames": ["staff", "vip"]
}

Example response:

{
    "tagNames": ["staff", "vip", "highroller"],
    "label":    "GENUINE"
}

Attaching a tag to a customer is done by posting to this endpoint with the body filled with customerId and an array of tagNames. This will attach the tag and respond with the full list of attached tags and the label for that customer.

GET /v2/tag/customer/:customerId

This returns all the tags for a specific customer as well as the label for the customer. This returns the same body as the POST tag endpoint.

DELETE /v2/tag/customer?customerId=[customerId]&tagName=[tag1,tag2]

To remove a tag, make a DELETE http request on the tag customer endpoint. This will remove the tag from the customer. The tagName field may be a single tag or, to remove multiple tags, a comma separated list of tags. This returns the same body as the POST tag endpoint.

Backfill

Backfill is the process of sending your historical data to Ravelin. We will use the backfill data to train a model which uniquely identifies the fraud you are experiencing. This model will then be used to evaluate your live data.

However, it is only worth doing backfill if your historical data is representative of your live data. If not, the model which is trained won’t accurately detect fraud in your live data.

If your backfill data is not representative of your live data, or if you don’t have a enough backfill data, and you are receiving enough enough traffic through your platform, it may be preferable to just collect live data and use that to train a model instead. Please speak to our integrations team about whether this is an option for you.

If you choose to proceed with backfill we recommend that you start sending us live data before performing the backfill, but don’t request scoring. This means you will avoid a gap in data during the period between completing your backfill and when we finish preparing your fraud model.

If performing backfill these are the steps you should follow:

1. Start sending us all live events with scoring set to score=false.
2. Perform the backfill and wait for us to confirm your fraud model has been generated.
3. Switch your live events to use score=true for those you wish to score.

Requesting a score only works for known customers, which is why we recommend you complete backfill before enabling scoring.

Backfill Endpoints

In order to perform the backfill you should send data to our backfill API endpoints. Every one of our primary API endpoints has an equivalent backfill endpoint. These endpoints receive data in exactly the same format as our primary API endpoints. Fields which are required by the primary API are also required by the backfill API. For details about the format see the documentation for each of the primary API endpoints.

Timestamps on Backfill Data

Timestamps should be provided for all backfill data. If a timestamp isn’t available for an entity, a timestamp from a related entity can be used instead. For example, if you don’t have the registration time for a customer the time of their first order could be used instead. Regardless of their source, make sure all timestamps for backfill data are in the past so that they don’t conflict with live events.

Rate Limiting During Backfill

The rate limits for the backfill endpoints are much higher than the rate limits for the primary endpoints so you needn’t worry about being rate limited during backfill.

Warnings

Ravelin will avoid rejecting requests with bad data in some cases, with the understanding that our best effort is usually still preferable to nothing at all. Our machine-learning scoring may be impacted by a missing order price, but we can still see when a credit card has sent you chargebacks before.

Errors

Ravelin uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided request and codes in the 5xx range indicate an error with Ravelin’s system.

# Typical Error Response
{
  status: 403,
  message: "Invalid Request: API Key Incorrect. Please check your credentials and try again"
}

For our recommendations on how to best respond to these error codes, please consult our Error Handling documentation or contact a Ravelin engineer.