Travel API Reference

Welcome to the Ravelin Travel 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/...

All API endpoints require an Authorization header with the API key.

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

The endpoints are defined below are how you send data to the Ravelin system. To create or update entities in Ravelin, send a POST request with the defined JSON body to one of the endpoints described below.

We strive to represent everything relevant to the travel domain but if you think you have domain data that is relevant to fraud but not represented in our models then you may send this data via the custom field. You will find this field on all of our properties. 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.

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

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.

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1479302798391,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 14793027980391,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1479302798401,
    "telephoneCountry": "GBR",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    },
    "balance": {
      "GBP": 100
    }
  },
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1479122053,
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "generalItems": [
      {
        "sku": "123-abc-XYZ",
        "name": "Travel Insurance Gold",
        "price": 10000,
        "currency": "GBP",
        "brand": "snowpass",
        "upc": "123456789123",
        "category": "insurance",
        "subcategory": "travel",
        "quantity": 1,
        "executionTime": 1480098379,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580071,
            "validUntilTime": 1480340580008
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum",
            "description": "Fitzwilliam Museum, Exhibition of Old Things.",
            "startTime": 1480340580401,
            "endTime": 1480340589390,
            "venue": {
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234",
                "custom": {
                  "foo": "bar",
                  "biz": "baz",
                  "one": 1
                },
                "addresseeName": "John Smith"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        },
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "hotelRooms": [
      {
        "price": 10000,
        "currency": "GBP",
        "quantity": 1,
        "guest": {
          "familyName": "Smith",
          "givenName": "John",
          "name": "John Smith"
        },
        "freeCancellationUntilTime": 1480340580291,
        "paymentDueBeforeTime": 1480340580910,
        "hotel": {
          "name": "The Overlook Hotel",
          "location": {
            "country": "GBR",
            "postalCode": "E1 1AA",
            "latitude": 51.503252,
            "longitude": -0.127899,
            "street1": "123 fake st.",
            "street2": "floor 4, flat 48",
            "neighbourhood": "Hackney",
            "zone": "1",
            "city": "London",
            "region": "California",
            "poBoxNumber": "1234",
            "custom": {
              "foo": "bar",
              "biz": "baz",
              "one": 1
            },
            "addresseeName": "John Smith"
          }
        },
        "room": {
          "name": "Grand Deluxe Double King Suite"
        },
        "custom": {
          "hotel": {
            "non-smoking": "true",
            "concierge": "true",
            "pets": "false"
          },
          "room": {
            "wifi": "true",
            "refrigerator": "true",
            "ironingFacilities": "false"
          }
        }
      }
    ],
    "tickets": [
      {
        "ticketId": "tk_123",
        "description": "Standard Advanced Single - Adult - Full Fare",
        "currency": "GBP",
        "quantity": 1,
        "routes": [
          {
            "direction": "outward",
            "journeyId": "xyz-123-ABC",
            "legs": [
              {
                "legId": "leg-a1B2c3D4e5F6g7H",
                "departurePortCode": "LHR",
                "departurePort": {
                  "country": "GBR",
                  "postalCode": "E1 1AA",
                  "latitude": 51.503252,
                  "longitude": -0.127899,
                  "street1": "123 fake st.",
                  "street2": "floor 4, flat 48",
                  "neighbourhood": "Hackney",
                  "zone": "1",
                  "city": "London",
                  "region": "California",
                  "poBoxNumber": "1234",
                  "custom": {
                    "foo": "bar",
                    "biz": "baz",
                    "one": 1
                  },
                  "addresseeName": "John Smith"
                },
                "departureCity": "London",
                "departureCountryCode": "GBR",
                "departureTime": 1478883331000,
                "arrivalPortCode": "SFO",
                "arrivalPort": {
                  "country": "GBR",
                  "postalCode": "E1 1AA",
                  "latitude": 51.503252,
                  "longitude": -0.127899,
                  "street1": "123 fake st.",
                  "street2": "floor 4, flat 48",
                  "neighbourhood": "Hackney",
                  "zone": "1",
                  "city": "London",
                  "region": "California",
                  "poBoxNumber": "1234",
                  "custom": {
                    "foo": "bar",
                    "biz": "baz",
                    "one": 1
                  },
                  "addresseeName": "John Smith"
                },
                "arrivalCity": "London",
                "arrivalCountryCode": "GBR",
                "arrivalTime": 1478883331000,
                "carrierName": "air canada",
                "carrierCode": "AC",
                "seatReservation": false,
                "custom": {
                  "foo": "bar",
                  "biz": "baz",
                  "one": 1
                }
              }
            ],
            "custom": {
              "foo": "bar",
              "biz": "baz",
              "one": 1
            }
          }
        ],
        "travelInsurance": true,
        "ticketClass": "first",
        "ticketType": "openreturn",
        "fulfilmentMethod": "email",
        "loyaltyCardId": "abc-123-loyalty-xyz",
        "discountCardId": "abc-123-loyalty-xyz",
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "passengers": [
      {
        "familyName": "Smith",
        "givenName": "John",
        "name": "John Smith",
        "dateOfBirth": "1980-11-21",
        "email": "jsmith@example.com",
        "telephone": "+447546186424",
        "telephoneCountry": "GBR",
        "documentType": "passport",
        "documentNumber": "1234-abcd",
        "documentIssuingCountry": "GBR",
        "documentIssueTime": 1479122053910,
        "documentExpiryTime": 1479122053910,
        "nationality": "GBR",
        "passengerType": "adult",
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "email": "jsmith@example.com",
    "terminated": false,
    "sellerId": "abcde12345-ZXY",
    "customerLocation": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "currency": "GBP",
    "type": "auth_capture",
    "payment": {
      "card": {
        "paymentMethodId": "123-abc-XYZ",
        "lastVerified": 1480340580,
        "registrationTime": 1480340580,
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        },
        "instrumentId": "123-abc-XYZ",
        "cardBin": "123456",
        "cardLastFour": "1234",
        "expiryMonth": 4,
        "expiryYear": 2020,
        "nameOnCard": "John Smith",
        "successfulRegistration": true,
        "billingAddress": {
          "country": "GBR",
          "postalCode": "E1 1AA",
          "latitude": 51.503252,
          "longitude": -0.127899,
          "street1": "123 fake st.",
          "street2": "floor 4, flat 48",
          "neighbourhood": "Hackney",
          "zone": "1",
          "city": "London",
          "region": "California",
          "poBoxNumber": "1234",
          "custom": {
            "foo": "bar",
            "biz": "baz",
            "one": 1
          },
          "addresseeName": "John Smith"
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John"
      }
    },
    "gateway": "braintree",
    "gatewayReference": "123-abc-XYZ",
    "success": true,
    "3ds": {
      "attempted": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false
    },
    "declineCode": "1234",
    "authCode": "1234",
    "avsResultCode": {
      "street": "M",
      "postalCode": "M"
    },
    "cvvResultCode": "M",
    "mccCode": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
customerId
optional
 string

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

 "abc-123-ZYZ"
customer
optional
 object

The customer navigating through the checkout process. Sending the customer identity in full during checkout is recommended to ensure Ravelin has all data. (See customers.)

Show definition
order
optional
 object

The order describing the goods or services the customer wants to buy. (See orders.)

Show definition
transaction
optional

The payment that the customer is attempting to make, or has just attempted. (See transactions.)

You are highly encouraged to mint an identifier for this customer's payment attempt and use that to track the transaction before and after talking to your PSP. Doing so enables the highest-resolution of reporting Ravelin offers.

Show definition
device
optional
 object

The device that the customer is using when navigating through the checkout flow. (See devices.)

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

POST /v2/travel/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.

The PSP 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.

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

{
  "timestamp": 1512828988826,
  "chargeback": {
    "chargebackId": "abc-123-XYZ",
    "gateway": "braintree",
    "gatewayReference": "abc-123-XYZ",
    "transactionId": "abc-123-XYZ",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "reason": "fraud",
    "status": "lost",
    "liabilityShifted": true,
    "nonFraud": false,
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "customerId": "abc-123-ZYZ"
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
chargeback
required
 object

The chargeback coming from a fraudulent claim filed with the cardholder's issuer. (See chargebacks.)

Hide definition
Name Type Description Example
chargebackId
required
 string

A unique identifier for the chargeback.

 "abc-123-XYZ"
gateway
important
 string

The gateway that the originating transaction was processed by.

 "braintree"
gatewayReference
important
 string

A reference to the transaction being disputed. Should match the gateway and reference fields supplied on the transaction object. Not required if you supply transactionId.

 "abc-123-XYZ"
transactionId
important
 string

A reference to the transaction being disputed. Should match the transactionId supplied on the transaction object. Not required if you supply a gatewayReference.

 "abc-123-XYZ"
amount
important
 integer

The amount that is being disputed plus any chargeback penalties, in the currency's basic units.

 15212
currency
important
 string

The currency of the amount of this chargeback, as an ISO 4217 currency code.

 "GBP"
disputeTime
important
 integer

The time that the dispute was opened which lead to this chargeback.

 1479302798
reason
optional
 string

The reason code from the chargeback. All chargebacks received by Ravelin will be treated as fraudulent.

 "fraud"
status
optional
 string

The status of the dispute. E.g. open, won, lost.

 "lost"
liabilityShifted
optional
 boolean

Whether liability for this chargeback has been shifted to a third-party.

 true
nonFraud
optional
 boolean

Whether this chargeback was claimed for reasons other than fraud.

 false
custom
optional
 object

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

The ID of the order the chargeback originated from. When provided instead of gatewayReference and transactionId, Ravelin will set the gatewayReference and transactionId to that of the first successful transaction of the order.
customerId
deprecated
 string

The ID of the customer this chargeback originated from. Ravelin will look this up from the transaction this chargeback originated from.

 "abc-123-ZYZ"

Valid chargeback status strings:

status Description
OPEN The chargeback, retrieval, or pre-arb has been issued and 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 should return to your bank account within 2-3 business days.
LOST The bank has not ruled in your favor, and the funds will remain with the cardholder.
EXPIRED The reply-by date to submit evidence has passed and you have forfeited your right to dispute the case.

POST /v2/travel/customer

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.

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. We keep all mutations so we will know the history of a customer but we use the most up-to-date data to build the current customer profile.

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

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
customer
required
 object

The customer registering or updating their account profile.

Hide definition
Name Type Description Example
customerId
required
 string

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

 "abc-123-ZYZ"
registrationTime
important
 integer

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

A unix timestamp as an integer count of milliseconds or nanoseconds since 1970-01-01T00:00 UTC.

 1479302798391
email
important
 string

The email address of the customer.

 "jsmith123@example.com"
emailVerifiedTime
optional
 integer

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

A unix timestamp as an integer count of milliseconds or nanoseconds since 1970-01-01T00:00 UTC.

 14793027980391
name
important
 string

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

 "John Smith"
familyName
important
 string

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

 "Smith"
givenName
important
 string

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

 "John"
telephone
important
 string

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

 "+16045555555"
telephoneVerifiedTime
optional
 integer

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

A unix timestamp as an integer count of milliseconds or nanoseconds since 1970-01-01T00:00 UTC.

 1479302798401
telephoneCountry
optional
 string

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

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

 "GBR"
vendorId
optional
 string

The unique identifier of the merchant who processed this order.
passwordBcrypted
optional
 string

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

The SHA256 form of the password for this user. This must be base64 encoded.
password
optional
 string

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

Set to true on events where the password has been changed, false or omit otherwise
location
optional
 object Show definition
custom
optional
 object

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

Whether the customer is banned in your systems.
username
deprecated
 string

The username the customer would log in with.
dateOfBirth
deprecated
 string

The date of birth of the customer in the format 'YYYY-MM-DD'.
gender
deprecated
 string

The gender of the customer.
market
deprecated
 string

Deprecated in favour of order.country. The country-group market the customer belongs to. E.g. 'south-america', 'europe', 'emea'. See markets.
country
deprecated
 string

Deprecated in favour of order.country. The country the customer belongs to. See markets.
marketCity
deprecated
 string

Deprecated in favour of order.marketCity. The city that the customer belongs to. See markets.
balance
deprecated
 object

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

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

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

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/travel/order

When an order is started, or new information becomes available (e.g. the price changes), send an order event. An order is an intent to purchase a good or service from your business by a customer.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1479122053,
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "generalItems": [
      {
        "sku": "123-abc-XYZ",
        "name": "Travel Insurance Gold",
        "price": 10000,
        "currency": "GBP",
        "brand": "snowpass",
        "upc": "123456789123",
        "category": "insurance",
        "subcategory": "travel",
        "quantity": 1,
        "executionTime": 1480098379,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580071,
            "validUntilTime": 1480340580008
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum",
            "description": "Fitzwilliam Museum, Exhibition of Old Things.",
            "startTime": 1480340580401,
            "endTime": 1480340589390,
            "venue": {
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234",
                "custom": {
                  "foo": "bar",
                  "biz": "baz",
                  "one": 1
                },
                "addresseeName": "John Smith"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        },
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "hotelRooms": [
      {
        "price": 10000,
        "currency": "GBP",
        "quantity": 1,
        "guest": {
          "familyName": "Smith",
          "givenName": "John",
          "name": "John Smith"
        },
        "freeCancellationUntilTime": 1480340580291,
        "paymentDueBeforeTime": 1480340580910,
        "hotel": {
          "name": "The Overlook Hotel",
          "location": {
            "country": "GBR",
            "postalCode": "E1 1AA",
            "latitude": 51.503252,
            "longitude": -0.127899,
            "street1": "123 fake st.",
            "street2": "floor 4, flat 48",
            "neighbourhood": "Hackney",
            "zone": "1",
            "city": "London",
            "region": "California",
            "poBoxNumber": "1234",
            "custom": {
              "foo": "bar",
              "biz": "baz",
              "one": 1
            },
            "addresseeName": "John Smith"
          }
        },
        "room": {
          "name": "Grand Deluxe Double King Suite"
        },
        "custom": {
          "hotel": {
            "non-smoking": "true",
            "concierge": "true",
            "pets": "false"
          },
          "room": {
            "wifi": "true",
            "refrigerator": "true",
            "ironingFacilities": "false"
          }
        }
      }
    ],
    "tickets": [
      {
        "ticketId": "tk_123",
        "description": "Standard Advanced Single - Adult - Full Fare",
        "currency": "GBP",
        "quantity": 1,
        "routes": [
          {
            "direction": "outward",
            "journeyId": "xyz-123-ABC",
            "legs": [
              {
                "legId": "leg-a1B2c3D4e5F6g7H",
                "departurePortCode": "LHR",
                "departurePort": {
                  "country": "GBR",
                  "postalCode": "E1 1AA",
                  "latitude": 51.503252,
                  "longitude": -0.127899,
                  "street1": "123 fake st.",
                  "street2": "floor 4, flat 48",
                  "neighbourhood": "Hackney",
                  "zone": "1",
                  "city": "London",
                  "region": "California",
                  "poBoxNumber": "1234",
                  "custom": {
                    "foo": "bar",
                    "biz": "baz",
                    "one": 1
                  },
                  "addresseeName": "John Smith"
                },
                "departureCity": "London",
                "departureCountryCode": "GBR",
                "departureTime": 1478883331000,
                "arrivalPortCode": "SFO",
                "arrivalPort": {
                  "country": "GBR",
                  "postalCode": "E1 1AA",
                  "latitude": 51.503252,
                  "longitude": -0.127899,
                  "street1": "123 fake st.",
                  "street2": "floor 4, flat 48",
                  "neighbourhood": "Hackney",
                  "zone": "1",
                  "city": "London",
                  "region": "California",
                  "poBoxNumber": "1234",
                  "custom": {
                    "foo": "bar",
                    "biz": "baz",
                    "one": 1
                  },
                  "addresseeName": "John Smith"
                },
                "arrivalCity": "London",
                "arrivalCountryCode": "GBR",
                "arrivalTime": 1478883331000,
                "carrierName": "air canada",
                "carrierCode": "AC",
                "seatReservation": false,
                "custom": {
                  "foo": "bar",
                  "biz": "baz",
                  "one": 1
                }
              }
            ],
            "custom": {
              "foo": "bar",
              "biz": "baz",
              "one": 1
            }
          }
        ],
        "travelInsurance": true,
        "ticketClass": "first",
        "ticketType": "openreturn",
        "fulfilmentMethod": "email",
        "loyaltyCardId": "abc-123-loyalty-xyz",
        "discountCardId": "abc-123-loyalty-xyz",
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "passengers": [
      {
        "familyName": "Smith",
        "givenName": "John",
        "name": "John Smith",
        "dateOfBirth": "1980-11-21",
        "email": "jsmith@example.com",
        "telephone": "+447546186424",
        "telephoneCountry": "GBR",
        "documentType": "passport",
        "documentNumber": "1234-abcd",
        "documentIssuingCountry": "GBR",
        "documentIssueTime": 1479122053910,
        "documentExpiryTime": 1479122053910,
        "nationality": "GBR",
        "passengerType": "adult",
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        }
      }
    ],
    "email": "jsmith@example.com",
    "terminated": false,
    "sellerId": "abcde12345-ZXY",
    "customerLocation": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
order
required
 object

The order describing the goods or services the customer wants to, or has attempted to buy. (See orders.)

Hide definition
Name Type Description Example
orderId
required
 string

A unique identifier for this order.

 "abcde12345-ZXY"
creationTime
important
 integer

The time that the order was submitted by the customer. Used in reporting.

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1479122053
status
important

The stage of order in the purchase and delivery flow. Used in reporting.

One of the following:
 { "stage": "pending", "actor": "merchant" }
•

Pending: The order is yet to be submitted for payment and processing, and you are yet to decide whether you will accept the order.

Show definition
•

Accepted: The customer has submitted the order and you intend to fulfill it. This stage is useful if you provide the goods and services before taking payment. If you take payment immediately, you can consider the order fulfilled.

Show definition
•

Failed: Something went wrong, and the order can no longer be fulfilled.

Show definition
•

Cancelled: The order has been cancelled.

Show definition
•

Fulfilled: The goods have been provided to the customer and payment has been successfully taken.

Show definition
•

Refunded: The order is has been refunded.

Show definition
price
important
 integer

The total price for this order, including delivery and taxes, in the currency's basic units. This price should always equal the sum of each items', tickets', and rooms' price times quantity.

 10000
currency
important
 string

The currency of the price for this order as an ISO 4217 currency code.

 "GBP"
country
important
 string

The country the order should be attributed to for reporting and risk bucketing. See markets. Should reflect the country segmentation that you use for your reporting internally, whether that's by billing or shipping address, for example.

 "GBR"
market
important
 string

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

 "emea"
marketCity
important
 string

The city that the customer belongs to. Used for reporting and risk bucketing. See markets.

 "london"
generalItems
important
 array

Any line items of the order which do not fit into the other categories, including but not limited to tax, booking fees, rental cards, insurance.

Show definition
hotelRooms
important
 array

The hotel rooms booked in this order.

Show definition
tickets
important
 array

The tickets purchased in this order, granting access to travel.

Show definition
passengers
important
 array

The passengers who are embarking on this trip.

Show definition
email
optional
 string

Contact e-mail for this order

 "jsmith@example.com"
terminated
optional
 boolean false
vendorId
optional
 string

The unique identifier of the merchant who processed this order.
sellerId
optional
 string

The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. The airline code, travel agent code, etc.

 "abcde12345-ZXY"
customerLocation
optional
 object

The location of the customer when ordering, if available.

Show definition
custom
optional
 object

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

The ID of the customer whose order is being updated.

 "abc-123-ZYZ"
tempCustomerId
optional
 string

A temporary ID for a customer when the real account ID has yet to be minted. This must evenutally be sent in conjunction with a real customer ID to migrate the data into the full customer account.

 "abc-123-XYZ"
device
optional
 object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

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

Order Statuses

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

POST /v2/travel/paymentmethod

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.

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 the Ravelin vault

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "payment": {
    "card": {
      "paymentMethodId": "123-abc-XYZ",
      "lastVerified": 1480340580,
      "registrationTime": 1480340580,
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "instrumentId": "123-abc-XYZ",
      "cardBin": "123456",
      "cardLastFour": "1234",
      "expiryMonth": 4,
      "expiryYear": 2020,
      "nameOnCard": "John Smith",
      "successfulRegistration": true,
      "billingAddress": {
        "country": "GBR",
        "postalCode": "E1 1AA",
        "latitude": 51.503252,
        "longitude": -0.127899,
        "street1": "123 fake st.",
        "street2": "floor 4, flat 48",
        "neighbourhood": "Hackney",
        "zone": "1",
        "city": "London",
        "region": "California",
        "poBoxNumber": "1234",
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        },
        "addresseeName": "John Smith"
      },
      "billingFamilyName": "Smith",
      "billingGivenName": "John"
    }
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
payment
required

The payment method being registered by the customer. (See payment methods.)

Hide definition
Name Type Description Example
paymentMethodId
optional
 string

The ID of an existing payment method.

 "abc-123-XYZ"
card
optional
 object

The credit or debit card this payment method represents.

Show definition
paypal
optional
 object

The PayPal account this payment method represents.

Show definition
voucher
optional
 object

The voucher this payment method represents.

Show definition
cash
optional
 boolean

Just cash.

 true
paymentMethodCipher
optional
 object

The encrypted ciphertext of the credit or debit card this payment method represents. (See client-side encryption.)

Show definition
fromTransaction
optional
 object

The other payment method this payment method represents, as identified by a transaction the other payment method was already used on.

One of the following:
Show definition
•Type: , example: {}
•Type: , example: {}
other
optional
 object

Another instrument of payment this payment method represents.

Show definition
customerId
optional
 string

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

A temporary ID for a customer when the real account ID has yet to be minted. This must evenutally be sent in conjunction with a real customer ID to migrate the data into the full customer account.

 "abc-123-XYZ"
device
optional
 object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

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/travel/checkout?score=true HTTP/1.1
Content-Type: application/json

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

… and completed their order successfully:

POST /v2/travel/checkout HTTP/1.1
Content-Type: application/json

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

If the customer then 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/travel/paymentmethod HTTP/1.1
Content-Type: application/json

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

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

POST /v2/travel/transaction/before-psp

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.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "orderId": "abcde12345-ZXY",
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "currency": "GBP",
    "type": "auth_capture",
    "payment": {
      "card": {
        "paymentMethodId": "123-abc-XYZ",
        "lastVerified": 1480340580,
        "registrationTime": 1480340580,
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        },
        "instrumentId": "123-abc-XYZ",
        "cardBin": "123456",
        "cardLastFour": "1234",
        "expiryMonth": 4,
        "expiryYear": 2020,
        "nameOnCard": "John Smith",
        "successfulRegistration": true,
        "billingAddress": {
          "country": "GBR",
          "postalCode": "E1 1AA",
          "latitude": 51.503252,
          "longitude": -0.127899,
          "street1": "123 fake st.",
          "street2": "floor 4, flat 48",
          "neighbourhood": "Hackney",
          "zone": "1",
          "city": "London",
          "region": "California",
          "poBoxNumber": "1234",
          "custom": {
            "foo": "bar",
            "biz": "baz",
            "one": 1
          },
          "addresseeName": "John Smith"
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John"
      }
    },
    "gateway": "braintree",
    "gatewayReference": "123-abc-XYZ",
    "success": true,
    "3ds": {
      "attempted": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false
    },
    "declineCode": "1234",
    "authCode": "1234",
    "avsResultCode": {
      "street": "M",
      "postalCode": "M"
    },
    "cvvResultCode": "M",
    "mccCode": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
orderId
required
 string

A unique identifier for the order this transaction pertains to.

 "abcde12345-ZXY"
transaction
required
 object

The transaction we are considering submitting to the PSP. (See transaction.)

The fields we cannot yet know until after talking to the PSP are not allowed here.

Hide definition
Name Type Description Example
currency
required
 string

The currency of the amount of this transaction, as an ISO 4217 currency code.

 "GBP"
gateway
required
 string

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

 "braintree"
payment
required
 object

The payment method this transaction interacts with. (See payment methods.)

Hide definition
Name Type Description Example
paymentMethodId
optional
 string

The ID of an existing payment method.

 "abc-123-XYZ"
card
optional
 object

The credit or debit card this payment method represents.

Show definition
paypal
optional
 object

The PayPal account this payment method represents.

Show definition
voucher
optional
 object

The voucher this payment method represents.

Show definition
cash
optional
 boolean

Just cash.

 true
paymentMethodCipher
optional
 object

The encrypted ciphertext of the credit or debit card this payment method represents. (See client-side encryption.)

Show definition
fromTransaction
optional
 object

The other payment method this payment method represents, as identified by a transaction the other payment method was already used on.

One of the following:
Show definition
•Type: , example: {}
•Type: , example: {}
other
optional
 object

Another instrument of payment this payment method represents.

Show definition
transactionId
important
 string

A unique identifier for the transaction.

Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference.

 "123-abc-XYZ"
time
important
 integer

The time that the transaction is being attempted.

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1480340580291
amount
important
 integer

The amount to be charged to the payment method, in the currency's basic units.

 1000
type
important
 string

The type of interaction with the payment method.

One of: preauth, auth, capture, auth_capture, void, refund, redeem, or use.

"auth_capture"
3ds
important
 object

Information about 3DSecure used to authorize the transaction.

Show definition
mccCode
optional
 string

The merchant category classification code associated with the transaction."

 "0742"
mid
optional
 string

The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.

 "mid-1"
acquirerId
optional
 string

The acquirer is a financial institution with whom the merchant has a bank account.

 "adyen"
custom
optional
 object

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

Whether this transaction is associated with a chargeback.
email
deprecated
 string

The e-mail that the customer wants to be notified about this transaction on
debit
deprecated
 integer

Deprecated in favour of amount. The debit amount of the transaction in the lowest denomination of the currency. Required if credit and amount are not set.
credit
deprecated
 integer

Deprecated in favour of amount. The credit amount of the transaction in the lowest denomination of the currency. Required if debit and amount are not set.
customerId
optional
 string

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

A temporary ID for a customer when the real account ID has yet to be minted. This must evenutally be sent in conjunction with a real customer ID to migrate the data into the full customer account.

 "abc-123-XYZ"
device
optional
 object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

POST /v2/travel/transaction

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.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "orderId": "abcde12345-ZXY",
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "type": "auth_capture",
    "payment": {
      "card": {
        "paymentMethodId": "123-abc-XYZ",
        "lastVerified": 1480340580,
        "registrationTime": 1480340580,
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        },
        "instrumentId": "123-abc-XYZ",
        "cardBin": "123456",
        "cardLastFour": "1234",
        "expiryMonth": 4,
        "expiryYear": 2020,
        "nameOnCard": "John Smith",
        "successfulRegistration": true,
        "billingAddress": {
          "country": "GBR",
          "postalCode": "E1 1AA",
          "latitude": 51.503252,
          "longitude": -0.127899,
          "street1": "123 fake st.",
          "street2": "floor 4, flat 48",
          "neighbourhood": "Hackney",
          "zone": "1",
          "city": "London",
          "region": "California",
          "poBoxNumber": "1234",
          "custom": {
            "foo": "bar",
            "biz": "baz",
            "one": 1
          },
          "addresseeName": "John Smith"
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John"
      }
    },
    "3ds": {
      "attempted": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false
    },
    "declineCode": "1234",
    "authCode": "1234",
    "avsResultCode": {
      "street": "M",
      "postalCode": "M"
    },
    "cvvResultCode": "M",
    "mccCode": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
orderId
required
 string

A unique identifier for the order this transaction pertains to.

 "abcde12345-ZXY"
transaction
required

The transaction that was submitted to your PSP, and whether it was successful.

Hide definition
Name Type Description Example
currency
required
 string

The currency of the amount of this transaction, as an ISO 4217 currency code.
gateway
required
 string

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.
success
required
 boolean

Whether the transaction succesfully completed with no error.
gatewayReference
required
 string

The reference given to this transaction by the processing gateway. Used to link to chargebacks. Usually only available after attempting the payment.
transactionId
important
 string

A unique identifier for the transaction.

Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference.

 "123-abc-XYZ"
time
important
 integer

The time that the transaction is being attempted.

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1480340580291
amount
important
 integer

The amount to be charged to the payment method, in the currency's basic units.

 1000
type
important
 string

The type of interaction with the payment method.

One of: preauth, auth, capture, auth_capture, void, refund, redeem, or use.

"auth_capture"
payment
important
 object

The payment method this transaction interacts with. (See payment methods.)

Show definition
3ds
important
 object

Information about 3DSecure used to authorize the transaction.

Show definition
declineCode
important
 string

The decline code from the payment gateway, if applicable.

 "1234"
authCode
optional
 string

A code returned from the payment gateway after an attempt to charge, if applicable.

 "1234"
avsResultCode
optional
 object

The result of address verification. You must have at least one of street or postal code.

Show definition
cvvResultCode
optional
 string

Result code of address or cvv verification by issuer, compatible with common PSP codes

One of: M, N, U, I, A, E, pass, fail, unavailable, unchecked, 0, 1, 2, 4, 8, P, S, 3, 5, 6, missing, issuer_not_certified, issuer_not_signed_up, or not_checked.

"M"
mccCode
optional
 string

The merchant category classification code associated with the transaction."

 "0742"
mid
optional
 string

The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.

 "mid-1"
acquirerId
optional
 string

The acquirer is a financial institution with whom the merchant has a bank account.

 "adyen"
custom
optional
 object

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

Whether this transaction is associated with a chargeback.
email
deprecated
 string

The e-mail that the customer wants to be notified about this transaction on
debit
deprecated
 integer

Deprecated in favour of amount. The debit amount of the transaction in the lowest denomination of the currency. Required if credit and amount are not set.
credit
deprecated
 integer

Deprecated in favour of amount. The credit amount of the transaction in the lowest denomination of the currency. Required if debit and amount are not set.
customerId
optional
 string

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

A temporary ID for a customer when the real account ID has yet to be minted. This must evenutally be sent in conjunction with a real customer ID to migrate the data into the full customer account.

 "abc-123-XYZ"
device
optional
 object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
 string

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

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

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.

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/travel/checkout?score=true HTTP/1.1
Content-Type: application/json

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

… and completed their order successfully:

POST /v2/travel/checkout HTTP/1.1
Content-Type: application/json

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

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/travel/transaction HTTP/1.1
Content-Type: application/json

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

This is available through the fromTransaction payment method type on the transaction, which requires either a transactionId or a gateway and gatewayReference.

POST /v2/travel/login

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.

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.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234",
      "custom": {
        "foo": "bar",
        "biz": "baz",
        "one": 1
      },
      "addresseeName": "John Smith"
    },
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
customerId
required
 string

The ID of the customer who has successfully logged in.

 "abc-123-ZYZ"
tempCustomerId
optional
 string

A temporary ID for a customer when the real account ID has yet to be minted. This must evenutally be sent in conjunction with a real customer ID to migrate the data into the full customer account.

 "abc-123-XYZ"
device
optional
 object

The device used by the customer who just logged in. Sending IP address information here is particularly important. Mutually exclusive with deviceId.

Show definition
deviceId
optional
 string

The ID of the device used by the customer who just logged in. Mutually exclusive with device.

 "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260"

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.

Device Tracking

Ravelin’s Device Identification & Tracking API for web browsers, written in JavaScript, sends user activity directly from your website to Ravelin. This includes information about the device, pages viewed, and actions taken. Custom events can be tracked to ensure any subtleties are tracked.

The tracking library requires a Public API Key which can be sent to users’ browsers. The Public API Key is a write-only authorisation token which cannot be used to read data from Ravelin.

Authenticating Requests

Authenticating with the client-side libraries require the use of your publishable API key which begins publishable_key_... or pk_....

Getting Started

Embed the script with your Public API Key by including the following script snippet at the bottom of your HTML pages:

<script>
(function(r,a,v,e,l,i,n){r[l]=r[l]||function(){(r[l].q=r[l].q||[]).push(arguments)};i=a.createElement(v);i.async=i.defer=1;i.src=e;a.body.appendChild(i)})(window,document,'script','https://cdn.ravelin.net/js/rvn-beta.min.js','ravelin');
ravelin('setApiKey', 'your-api-key');
// ravelin('setCustomerId', '$CUSTOMER_ID'); (See below).
// ravelin('setCookieDomain', '.$MYDOMAIN'); (See below).
</script>

The following configuration options are supported:

  • ravelin('setCustomerId', '$CUSTOMER_ID') will file tracked events under a particular customer account. This is not required to track anonymous activity, but is expected when the customer is logged in. Should be set before calling any track methods on every page where we know the customer.
  • ravelin('setCookieDomain', '.$MYDOMAIN') will store the cookies under the named domain so that it can be shared between subdomains.

Tracking

With the script installed and configured we are now ready to send events to Ravelin. The following events should be triggered by your app:

  • ravelin('trackPage', {meta}) to indicate when the user hits a new page. You are encouraged to add metadata to describe the page that the user has landed on (such as search terms), especially if the URL does not contain that information.
  • ravelin('trackLogin', {meta}) to indicate that the user has just authenticated themselves. Separate setCustomerId calls should remain.
  • ravelin('trackLogout', {meta}) to indicate when the user has signed out of their session.

And from the checkout page we should call:

ravelin('fingerprint')
Custom Events and Metadata

The track method can be used to log notable client-side events:

ravelin('track', 'eventName', {meta})

Where the URL of a page does not fully describe the data contained within, custom track events can be used to provide Ravelin with that information. On a search results page reached with form POST, for example, you can send the user query with:

ravelin('trackPage', {query: "user's search query"});

Synchronising with Server-Side API

Ravelin’s device ID is made available to your server, and should be used as the deviceId in server-side requests made for the current session. This allows Ravelin to identify which customer orders were made from which device.

Beta Guarantee

Note that the library snippet included above is using rvn-beta.min.js - the beta release of Ravelin’s page-tracking. The API is intended to be released as-is when shipped as latest, but this is not guaranteed.

Upgrading from Live Version
  • The ravelinUuid cookie is being renamed to ravelinDeviceId.
  • The ravelin('send') call should be replaced with ravelin('fingerprint').

Vault

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

The vault is PCI DSS Compliant and is the only Ravelin API that can accept RAW card numbers.

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). This still makes sense on the vault, as long as you use your PSPs identifier here, and not the Ravelin Card token from the public facing Ravelin Vault.
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
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

Only use your PUBLISHABLE KEY for the public vault API (starts with pk_...).

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 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 or callback
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"
warnings array of warnings Ravelin can return warnings on API responses when malformed or absent data may negative impact fraud-detection, but where we would rather return a best-effort score instead of out-right rejecting the API request.

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/travel/checkout?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 score 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.

Do not implement any logic based upon the source of the action. Furthermore, do not attempt to deserialise it into an enum, as we reserve the right to add new sources to our scoring engine without warning.

Callbacks

{
    "customerId": "123456789",
    "action": "ALLOW",
    "score": 11,
    "source": "MANUAL_REVIEW",
    "scoreId": "40ba-843e-43c71",
    "comment": "Best customer!"
}

When the fraud status of one of your customers changes, Ravelin sends you a callback.

This can happen for a variety of reasons, including but not limited to:

  • A customer is manually reviewed through the dashboard, or
  • An event is received through the API, or
  • We discover a fraud network, and some of them exist in your system, or
  • Machine learning models are updated.

Any of these will cause a HTTPS request to your system. The body is a JSON blob, with the same semantics as the response to scored POST requests (see above).

Suggested callback handling

The most important field in the payload is action:

on this action In your system...
ALLOW Unban this customer if they are currently banned
REVIEW Take no immediate action, but review this customer on Ravelin
PREVENT Ban this customer

Configuration

Callbacks are configured in the dashboard under Settings → Integrations → HTTP.

Callbacks can be configured to supply an additional Authorization header to your system. This will be prefixed with token + a space. E.g. if you configure abcdef123 as the token, this header will be added to the HTTPS request:

Authorization: token abcdef123

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/travel/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 labeling 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 Tag 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/travel/tag/customer

Request:

{
  "tagNames":["staff","vip"],
  "customerId":"368487"
}

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 as shown below. 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 unique identifier of this customer in your system.
tagNames []string The name of the tags to append to the customer.

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

To remove a tag, call delete on the tag customer endpoint. This will remove the tag. the tagName field may be a single tag or a comma separated list of tags. This returns the same body as given by the POST endpoint.

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

This returns the tags for a specific customer. This returns the same body as given by the POST 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/travel/backfill/customer /v2/travel/customer Send only if you have registrationTime.
See Timestamps on Backfill Data.
/v2/travel/backfill/paymentmethod /v2/travel/paymentmethod Send only if you have registrationTime and paymentMethodId and, either the instrumentId or the cardBin and cardLastFour.
/v2/travel/backfill/transaction /v2/travel/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/travel/backfill/order /v2/travel/order Send only if you have sent transactions, and you have the order's transactionId.
/v2/travel/backfill/chargeback /v2/travel/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.

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.

See API Warnings for full information on handling data warnings, and a breakdown of each warning class and their potential impact.

Parameter Type Description
class string Identifier for this warning. Format is [a-z-]+ so you can safely record it in your metrics system.
help URL A link to more information about this class of warning and the impact of not resolving.
msg string A description indicating why this warning has been issued.

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.