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

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

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 i.e.

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:

Parameter Type Description
timestamp integer The unix timestamp, in seconds, of when the event occurred

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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customer customer The customer performing the checkout. If the information about this customer was already sent to Ravelin previously, only filling the customerId field of this object will suffice.
customerId string If this is not a new customer performing the check-out, and the customer is already known with Ravelin, set the customerId field instead of the customer object (mutually exclusive).
order order The order under checkout.
paymentMethod payment method Payment method used for this checkout
paymentMethodId string If a payment method was already added for this user in a previous event, it can be referenced here. Mutually exclusive with the paymentMethod field.
transaction transaction (Attempted) transaction associated with this checkout
device device Information about the device used by this customer
voucherRedemption voucherRedemption Information about the voucher redeemed with this checkout

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
  }
}
Parameter Type Description
timestamp integer The unix timestamp, in seconds, of when the event occurred.
chargeback chargeback Details of the chargeback.

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.

Parameter Type Description
chargebackId string A unique identifier for this chargeback. Can be the same as the PSP ID. (required)
gateway string The name of the payment gateway. (required)
gatewayReference string Transaction Reference of the original transaction, not the chargeback. Provided by the payment gateway. (required unless providing transactionId)
transactionId string Transaction Id of the original transaction, not the chargeback. (required unless providing gatewayReference)
reason string The reason code from the chargeback
status string Status of the dispute, see the table below
amount integer The amount that is being disputed, in the lowest denomination of the currency.
currency string The ISO 4217 currency code.
disputeTime integer The time the dispute was opened, in unix time.
custom object If you have any data about this chargeback that does not fit in one of the above fields, please specify it in the custom object.

Valid chargeback status strings:

Status Description
OPEN No action has been taken yet.
ACCEPTED You have opted out of providing evidence for the chargeback or pre-arb.
DISPUTED You have submitted evidence against the claim and are waiting for the decision from the bank.
WON The bank has ruled in your favor, and the funds are scheduled to return to your account.
LOST The bank has not ruled in your favor, and the funds will remain with the cardholder.
EXPIRED The date to submit evidence has passed and you have forfeited your right to dispute the case.

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.

Parameter Type Description
timestamp integer The unix timestamp, in seconds, of when the event occurred.
customer customer The customer to create or update.
device device Information about the device used by this customer (optional).
deviceId string Previously submitted id for device used by this customer (exclusive with device).

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.

Parameter Type Description
customerId string The unique identifier of this customer in your system.
registrationTime integer When the customer registered, in unix time (seconds)
name string The full name of the customer.
givenName string The given name of the customer - often the first name of a customer.
familyName string The family name of the customer - often the last name of a customer.
email string The primary email of the customer.
emailVerifiedTime integer The unix timestamp when the customer's email was verified.
telephone string The telephone number of the customer, including international code.
telephoneVerifiedTime integer The unix timestamp when the customer's telephone was verified.
telephoneCountry string The country this phone number is registered in.
location location Where this customer was last seen
country country The home country for this customer; ISO 3166 (2- or 3-letter). This, together with the market and marketCity fields, makes up the full description of the market for the customer. See markets for more information.
market string The logical place in which this customer exists. The default market is the empty string. Must be lowercase and alphanumeric (i.e. must match ^[a-z0-9]*$). This, together with the country and marketCity fields, makes up the full description of the market for the customer. See markets for more information.
marketCity string Used in conjunction with market and country to fully describe the market for this customer. The default marketCity is the empty string. Must be lowercase and alphanumeric (i.e. must match ^[a-z0-9]*$). See markets for more information.
custom object If you have any data about this customer that does not fit in one of the above fields, please specify it in the custom object.

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.

Parameter Type Description
street1 string First line of the street address.
street2 string Second line of the street address.
neighbourhood string The neighbourhood of the location.
zone string The zone of the location.
city string The city/village/town of the location.
region string The state/county of the location.
country string The ISO 3166 country code (2- or 3-letter).
poBoxNumber string The PO box number, if applicable.
postalCode string The postal or zip code, if applicable.
latitude double The latitude of the location.
longitude double The longitude of the location.
custom object If you have any data about this location that does not fit in one of the above fields, please specify it in the custom object.

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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customerId string Customer performing this order
tempCustomerId string A session ID, if the customer has not logged in yet
order order The order to update.
device device Information about the device used by this customer (optional)
deviceId string If the device used by the customer was already sent in a previous event, its deviceId can be sent here instead of a full device object. Optional, and mutually exclusive with the device field.

Order

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

Parameter Type Description
orderId string A unique identifier for the order.
email string A contact email for the customer placing this order.
price integer The price of the purchase in the lowest denomination of the currency.
currency string The ISO 4217 currency code.
sellerId string The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. an ID of a driver when a customer is ordering a car, or the ID of a restaurant when a customer is ordering food.
from location The "start" location of the order
to location The "end" location of the order
country country The country for the order; ISO 3166 (2- or 3-letter). This, together with the market and marketCity fields, makes up the full description of the market for the order. See markets for more information.
market string The logical place in which this order occurs. The default market is the empty string. Must be lowercase and alphanumeric (i.e. must match ^[a-z0-9]*$). This, together with the country and marketCity fields, makes up the full description of the market for the order. See markets for more information.
marketCity string Used in conjunction with market and country to fully describe the market for this order. The default marketCity is the empty string. Must be lowercase and alphanumeric (i.e. must match ^[a-z0-9]*$). See markets for more information.
creationTime integer The unix timestamp, in seconds, of when the order was created.
executionTime integer The unix timestamp, in seconds, of when the order was executed. Specifically; when this order was to be used or obtained by the customer. For example; with taxis, you may prebook - this is the time the prebook is for. With tickets, this may be the time of the event.
note string Descriptive text relating to the contents or nature of the order being completed. Limited to 4000 characters.
items [item] Items registered with this order. Set to the empty array to empty the cart, do not specify at all if no information is available.
status status The most recent status of the order.
custom object If you have any data about this order that does not fit in one of the above fields, please specify it in the custom object.
Order Status

Order statuses specify the current status of the order.

Parameter Type Description
stage string The most recent status of the order. Valid values: pending, accepted, failed, cancelled, fulfilled, refunded.
reason string Status reason provides context to the order status. Valid values depend on the stage and are given in the table below.
actor string Status actor is the entity that caused the latest order status. You can use this string to provide additional information to your Ravelin dashboard users e.g. customerId123, order-cancelling-service, customerservice@company.com

Valid reasons for different order status stages:

stage Valid reason values
pending None – omit reason field.
accepted None – omit reason field.
failed payment_declined, seller_rejected, system_error
cancelled buyer, seller, merchant, ravelin
fulfilled None – omit reason field.
refunded returned, complaint
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.

Parameter Type Description
sku string A merchant specific identifier for an item or a service.
name string The name of the product that is being purchased.
price integer The price of the single item, if many bought, in the lowest denomination of the currency: e.g. cents for US dollars, pence for GB pound.
currency string The ISO 4217 currency code.
brand string The name of the brand that the item is from.
upc string The name of the Universal Item Code.
category string The highest level category that this item is sold in.
quantity integer The number of times this item is represented in the basket. 0 to remove.
eventTicket eventTicket If the item being purchased is a ticket for an event, associate the ticket and event information here..
custom object If you have any data about this item that does not fit in one of the above fields, please specify it in the custom object.
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.

Parameter Type Description
ticket ticket The ticket information for this event.
event event The event the ticket is granting access to. This could be a access to an event, an attraction, or any other activity the customer is purchasing a ticket to attend.
guest guest The individual who will be attending the event.

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.

Parameter Type Description
ticketId string A unique identifier for this ticket.
ticketType string A short human-readable description of the type of ticket.
validFromTime integer Timestamp at which this ticket is valid from (unix time).
validUntilTime integer Timestamp at which this ticket is valid until (unix time).
refundable boolean Whether 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.

Parameter Type Description
eventId string A unique identifier for this event.
name string The name of the event.
description string A short description of the event.
startTime integer Timestamp at which event is scheduled to start (unix time). If the event is ongoing/recurring, you can use the ticket time here.
endTime integer Timestamp at which event is scheduled to end (unix time). If the event is ongoing/recurring, you can use the ticket time here.
category string The category that best described the type of event. One of: adventure attraction conference convention culinary business family festival health live show music party social sport other
venue venue The location the event will take place.
Venue

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

Parameter Type Description
name string Name of the venue.
location location Location of the venue.
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.

Parameter Type Description
givenName string The named guest's given name.
familyName string The named guest's family name.
name string The named guest's full name.
purchaser boolean Whether this guest is the individual who is purchasing the tickets.

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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customerId string customer this payment method belongs to
tempCustomerId string a session ID, if the customer has not logged in yet
paymentMethod payment method The payment method to create/update
device device Information about the device used by this customer (optional)
deviceId string If the device used by the user was already sent in a previous event, its deviceId can be sent here instead of a full device object. Optional, and mutually exclusive with the device field.

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.

Parameter Type Description
paymentMethodId string A unique identifier for this payment method. (required)
methodType string The type of payment method. Valid values: card, voucher, bitcoin, cash, transfer, paypal, credit, fromTransaction. (required)
billingAddress location The billing address for this card
registrationTime integer When the payment method was added by the customer, in unix time (seconds). Note: this is not the same as the card start date.
custom object If you have any data about this payment method that does not fit in one of the above fields, please specify it in the custom object. Especially any data received from the PSP is welcome here.
Credit (& Debit) Cards

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

Parameter Type Description
instrumentId string Unique identifier for this card, consistent across users (e.g. Stripe's fingerprint, or Braintree's unique_number_identifier)
nameOnCard string Name to which the card is registered (as printed on the card)
cardBin string The BIN (leading six digits) of the card. Not always available, but strongly recommended when it is.
cardLastFour string The last four digits of the card (required)
cardType string The scheme of the card: visa, amex, etc.
expiryMonth integer The expiry month as MM. (required)
expiryYear integer The expiry year as YYYY. (required)
successfulRegistration boolean Whether the payment method was successfully registered with the PSP (e.g. passed verification)
issuer string The issuer of the payment method: e.g. barclaycard
countryIssued string The ISO 3166 country code (2- or 3-letter).
eWallet string The e-Wallet to which the customer associated the card. Valid values: applepay, googlepay, samsungpay

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.

Parameter Type Description
email string PayPal account ID (required)

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.

Parameter Type Description
transactionId string The ID of the transaction to save the payment method from.
gateway string The gateway of the transaction to save the payment method from.
gatewayReference string The gatewayReference transaction to save the payment method from.

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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customerId string customer performing the transaction
tempCustomerId string a session ID, if the customer has not logged in yet
paymentMethod payment method Payment method used for this transaction
paymentMethodId string If a payment method was already added for this user in a previous event, it can be referenced here. Mutually exclusive with the paymentMethod field.
orderId string order this transaction is (partially) resolving
transaction pretransaction The transaction that is about to be committed.
device device Information about the device used by this customer (optional)
deviceId string If the device used by the user was already sent in a previous event, its deviceId can be sent here instead of a full device object. Optional, and mutually exclusive with the device field.

Pre-Transaction

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

Parameter Type Description
transactionId string A unique identifier for the transaction.
3ds 3ds Information about any 3D Secure flow the customer was put through.
currency string The ISO 4217 currency code. (required)
debit integer The debit amount (money coming from the payment method, i.e. normal charge) of the transaction in the lowest denomination of the currency. (deprecated, see amount)
credit integer The credit amount (money going to the payment method, i.e. a refund) of the transaction in the lowest denomination of the currency. (deprecated, see amount)
amount integer The value of the transaction in the lowest denomination of the currency. (required)
gateway string The name of the payment gateway. (required)
type transaction type The type of transaction. See the transaction type table for reference.
time integer When this transaction is authed, captured, or otherwise actioned (depending on the type)
custom object If you have any data about this transaction that does not fit in one of the above fields, please specify it in the custom object. Especially any data received from the PSP is welcome here.

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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customerId string customer performing the transaction
tempCustomerId string a session ID, if the customer has not logged in yet
paymentMethod payment method Payment method used for this transaction
paymentMethodId string If a payment method was already added for this user in a previous event, it can be referenced here. Mutually exclusive with the paymentMethod field.
orderId string order this transaction is (partially) resolving
transaction transaction The transaction which was committed to the PSP, including the response from the PSP.
device device Information about the device used by this customer (optional)
deviceId string If the device used by the user was already sent in a previous event, its deviceId can be sent here instead of a full device object. Optional, and mutually exclusive with the device field.

Transaction

Parameter Type Description
transactionId string A unique identifier for the transaction.
success boolean Whether the transaction successfully completed with no error. (required)
3ds 3ds Information about any 3D Secure flow the customer was put through.
currency string The ISO 4217 currency code. (required)
debit integer The debit amount (money coming from the payment method, i.e. normal charge) of the transaction in the lowest denomination of the currency. (deprecated, see amount)
credit integer The credit amount (money going to the payment method, i.e. a refund) of the transaction in the lowest denomination of the currency. (deprecated, see amount)
amount integer The value of the transaction in the lowest denomination of the currency. (required)
authCode string A code returned from the payment gateway after an attempt to charge, if applicable.
declineCode string The decline code from the payment gateway, if applicable
gateway string The name of the payment gateway. (required)
gatewayReference string Transaction Reference provided by the payment gateway. (required)
avsResultCode avsresult The result code from address verification for both street and postal code verification
cvvResultCode string The result code from a CVV verification (M, N, ...)
type transaction type The type of transaction. See the transaction type table for reference.
time integer When this transaction is authed, captured, or otherwise actioned (depending on the type)
custom object If you have any data about this transaction that does not fit in one of the above fields, please specify it in the custom object. Especially any data received from the PSP is welcome here.
3D Secure

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

Parameter Type Description
attempted boolean Whether the customer was put through the 3DS payment flow.
success boolean Whether the customer 3DS authentication was successful.
startTime integer Unix timestamp indicating when the customer was redirected to the 3DS payment flow (seconds or milliseconds).
endtime integer Unix timestamp indicating when the customer returned from the 3DS payment flow (seconds or milliseconds).
timedOut boolean Whether you believe the customer to have abandoned your checkout flow during 3DS authentication.
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:

Parameter Type Description
postalCode string The result code from a postal code verification (M, N, ...)
street string The result code from a street name verification (M, N, ...)
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.

Type Description
auth An auth transaction only reserves the funds on the customer's account without deducting them from their account. Useful to verify if the customer has sufficient funds on their account without actually deducting the money, or to reserve a limit amount when the final order price is not known when the customer clicks "order" (e.g. a taxi ride with a pick-up location, but without destination). Sometimes called preauth.
capture A capture transaction deducts funds from the customer's account using auth. The maximum amount that can be captured is what was previously reserved in the auth, but anything lower is OK.
auth_capture A combination of both auth and capture in one transaction. For when there is no need to reserve money without also deducting it from the account. E.g. a straight-forward "buy now" button for a service that is immediately delivered, like food delivery.
void Used for voiding an auth.
refund Credit a customer's account. Will typically with have a new transactionId but the same gateway reference.

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",
    "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.

Parameter Type Value
timestamp integer The unix timestamp, in seconds, of when the event occurred
customerId string customer logging in
tempCustomerId string a session ID that was previously sent with anonymous events belonging to this user (optional)
device device Information about the device used by this customer (optional)
deviceId string If the device used by the user was already sent in a previous event, its deviceId can be sent here instead of a full device object. Optional, and mutually exclusive with the device field.

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.

Parameter Type Description
deviceId string A unique identifier for the device - e.g. UDID.
type string The type of device. e.g. computer, phone, tablet
manufacturer string The device manufacturer. e.g. apple, samsung.
model string The model/identifier name of the device. e.g. iPhone8,1, iPad5,4 (for Apple devices), or bullhead, herolte (for Android devices).
os string The operating system that the device is running. e.g. ios, android.
ipAddress string The IP address that this device is connecting from.
browser string The name of the web browser being used, if applicable. E.g. `Chrome 42`
userAgent string The full `User-Agent` header of the device

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
  }
}
Parameter Type Description
timestamp integer The unix timestamp, in seconds, of when the event occurred (required)
customer customer The customer performing the checkout. If the information about this customer was already sent to Ravelin previously, only filling the customerId field of this object will suffice. (required)
voucherRedemption voucherRedemption The voucher information and details of it's use (required)

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.

Parameter Type Description
paymentMethodId string A unique identifier for this payment method. (required)
voucherCode string The string customers actually see in their app (required)
redemptionTime integer The timestamp of the redemption attempt (required)
success boolean Bool indicating the success or failure of the redemption attempt (required)
value string The value of the voucher (required)
currency string The ISO 4217 currency code
voucherType string The type of voucher. One of: REFERRAL REACTIVATION GENERAL
expiry integer The timestamp after which the voucher can no longer be redeemed
failureReason string Optional reason why the attempt was not successful. One of: EXPIRED NOT_NEW_CUSTOMER ALREADY_USED ABUSER SYSTEM_FAILURE MAX_ALLOWED_TIMES
failureSource string the source of why the voucher failed. One of: RAVELIN CLIENT
referrerId string The customerId of the customer who created this voucher
referralValue integer The amount the owner of the voucher gets when the voucher is used
custom object If you have any data about this chargeback that does not fit in one of the above fields, please specify it in the custom object.

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

Parameter Type Description
instrumentId string Unique identifier for this card, consistent across users (e.g. Stripe's `fingerprint`, or Braintree's `unique_number_identifier`). Please use your PSP's unique identifier here, and not the Ravelin Card token from the Vault. If your PSP does not support this feature, Ravelin will create one for you to use in the graph.
nameOnCard string Name to which the card is registered (as printed on the card)
pan string The full, raw card number (only on the Vault!)
cardType string The scheme of the card: visa, amex, etc.
expiryMonth integer The expiry month as MM.
expiryYear integer The expiry year as YYYY.
successfulRegistration boolean Whether the payment method was successfully registered with the PSP (e.g. passed verification)
issuer string The issuer of the payment method: e.g. barclaycard
countryIssued string The ISO 3166 country code (2- or 3-letter).

<![CDATA[participant Your App participant Your Server participant vault.ravelin.com participant api.ravelin.com Your App–>Your Server: raw card PAN Your Server->vault.ravelin.com: event\n(+ raw card PAN) Note right of Your Server: POST /v2/transaction\n(secret key) vault.ravelin.com–>api.ravelin.com: event\n(+ ravelin token) api.ravelin.com–>vault.ravelin.com: response vault.ravelin.com->Your Server: response]]>Created with Raphaël 2.1.2Your AppYour AppYour ServerYour Servervault.ravelin.comvault.ravelin.comapi.ravelin.comapi.ravelin.comraw card PANevent(+ raw card PAN)POST /v2/transaction(secret key)event(+ ravelin token)responseresponse

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.

<![CDATA[participant vault.ravelin.com participant Your App participant Your Server participant api.ravelin.com Your App->vault.ravelin.com: raw card PAN Note left of Your App: POST /v2/card\n(publishable key) vault.ravelin.com->Your App: ravelin token Your App–>Your Server: ravelin token Your Server->api.ravelin.com: event\n(+ ravelin token) Note right of Your Server: POST /v2/transaction\n(secret key) api.ravelin.com->Your Server: response]]>Created with Raphaël 2.1.2vault.ravelin.comvault.ravelin.comYour AppYour AppYour ServerYour Serverapi.ravelin.comapi.ravelin.comraw card PANPOST /v2/card(publishable key)ravelin tokenravelin tokenevent(+ ravelin token)POST /v2/transaction(secret key)response

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": ""
    }
}

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 both cases, the score payload is a JSON object with the same schema:

Parameter Type Description
customerId string Identifier for this customer, as supplied by the client
action string Action to take for this customer, according to Ravelin. One of ALLOW, REVIEW, PREVENT
score int Ravelin score for this customer as an integer. Debugging purposes only
source string Source of the score, e.g. RAVELIN or MANUAL_REVIEW
scoreId string Unique identifier for this score
comment string In the case of manual review, this is the comment left by the reviewer on this particular review action. E.g.: "Definitely not a fraudster, I know him personally", or "I know this person from another account, infamous fraudster"

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:

on this action In your system
ALLOW Allow this order to proceed
REVIEW Take extra validation steps for this order (e.g. put the customer through 3D Secure)
PREVENT Prevent this order

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.

Parameter Type Description
customerId string The unique identifier of this customer in your system.
label string The label for this customer. Must be one of: UNREVIEWED, GENUINE, FRAUDSTER
comment string The reason for this label.
reviewer reviewer The individual creating this label

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.

Parameter Type Description
name string The name of the person doing the review
email string The email of the person doing the review

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.

Parameter Type Description
customerId string The ID the customer which you would like to set the tags for.
tagNames [string] An array containing the names of the tags to add to the customer.

GET /v2/tag/customer?customerId=[id]

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=[id]&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.

Backfill Endpoint Primary Endpoint Recommended Usage
/v2/backfill/customer /v2/customer Send only if you have registrationTime.
See Timestamps on Backfill Data.
/v2/backfill/paymentmethod /v2/paymentmethod Send only if you have registrationTime and paymentMethodId and, either the instrumentId or the cardBin and cardLastFour.
/v2/backfill/transaction /v2/transaction Send only if you have sent payment methods and have the transaction's paymentMethodId. Make sure you send all transactions, including successful, disputed and failed.
/v2/backfill/order /v2/order Send only if you have sent transactions, and you have the order's transactionId.
/v2/backfill/chargeback /v2/chargeback Send only if you have sent orders, and you have the chargeback's orderId.

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.

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"
}
HTTP Code Meaning
200 OK -- Everything worked as expected.
400 Bad Request -- Often missing a required parameter, e.g. customerId.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- Often you are not POSTing a request.
406 Not Acceptable -- You requested a format that isn't JSON.
429 Too Many Requests -- We're rate limiting your usage of the API.
500 Internal Server Error -- We had a problem with our server. Please try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
504 Service timeout -- We are temporarily offline or over capacity. Please try again later.

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