Core V2 API Reference

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

There are 3 key parts to a Ravelin integration:

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

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

Events

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

Event Metadata

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

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

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

The simplest, most reliable way to integrate Ravelin into your checkout flow is using our /v2/checkout endpoint before charging a card, followed by /v2/transaction to indicate success. 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": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "tags": {
      "foo": true,
      "bar": false
    },
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "tempCustomerId": "abc-123-XYZ",
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "category": "delivery",
    "to": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "from": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ],
    "email": "jsmith@example.com",
    "telephone": "+441234558887",
    "telephoneCountry": "GBR",
    "sellerId": "abcde12345-ZXY",
    "executionTime": 1512828988826,
    "suppliers": [
      {
        "supplierId": "abc-123-ZYZ",
        "status": {
          "stage": "fulfilled",
          "timestamp": 1512828988826,
          "reason": "Could not find passenger"
        },
        "fee": 250,
        "debt": 1000,
        "tip": 200,
        "currency": "GBP",
        "type": "courier"
      }
    ]
  },
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "scheme": "visa",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "eWallet": "applepay",
    "nameOnCard": "John Smith",
    "billingAddress": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "corporateCard": true,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826,
    "compromised": true,
    "compromisedReason": "stolen"
  },
  "paymentMethods": [
    {
      "methodType": "card",
      "paymentMethodId": "pm-abc123",
      "scheme": "visa",
      "instrumentId": "fp_abc123",
      "cardBin": "535522",
      "cardLastFour": "0001",
      "expiryMonth": 7,
      "expiryYear": 2020,
      "eWallet": "applepay",
      "nameOnCard": "John Smith",
      "billingAddress": {
        "country": "GBR",
        "postalCode": "E1 1AA",
        "latitude": 51.503252,
        "longitude": -0.127899,
        "addresseeName": "John Smith",
        "street1": "123 fake st.",
        "street2": "floor 4, flat 48",
        "neighbourhood": "Hackney",
        "zone": "1",
        "city": "London",
        "region": "California",
        "poBoxNumber": "1234"
      },
      "corporateCard": true,
      "successfulRegistration": true,
      "registrationTime": 1512828988826,
      "lastVerified": 1512828988826,
      "compromised": true,
      "compromisedReason": "stolen"
    }
  ],
  "paymentMethodId": "pm-abc123",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "type": "auth_capture",
    "paymentMethodId": "pm-abc123",
    "gateway": "braintree",
    "gatewayReference": "123-abc-XYZ",
    "success": true,
    "3ds": {
      "attempted": true,
      "challenged": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false,
      "version": "1.0.2",
      "liabilityShifted": true,
      "authenticationValue": "MDEyMzQ1Njc4OTAxMjM0NTY3ODk=",
      "eci": "5",
      "transStatus": "Y",
      "transStatusReason": "01",
      "messageType": "ARes",
      "iReqCode": "55"
    },
    "declineCode": "1234",
    "authCode": "1234",
    "avsResultCode": {
      "street": "pass",
      "postalCode": "unchecked"
    },
    "cvvResultCode": "pass",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "acquirerBin": "123456",
    "acquirerCountryCode": "GBR"
  },
  "voucherRedemptions": [
    {
      "paymentMethodId": "VOUCH-89-abc-123-ZYZ",
      "voucherCode": "VOUCH-89",
      "redemptionTime": 1512828988826,
      "success": true,
      "value": 10000,
      "currency": "GBP",
      "voucherType": "GENERAL"
    }
  ],
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Name Type Description Example

timestamp

required

integer

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

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

1512828988826

eventType

optional

string

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

customerId

important

string

The ID of the customer navigating through the checkout process. Mutually exclusive with customer.

"abc-123-ZYZ"

customer

important

object

The customer navigating through the checkout process. Mutually exclusive with customerId.

Show 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 preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

important

string

The email address of the customer.

"jsmith123@example.com"

emailVerifiedTime

optional

integer

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

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

1512828988826

name

important

string

The full name of the customer. If you have the name split into parts, consider familyName and givenName 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 confirming a code from an SMS you sent to the number.

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

1512828988826

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 where multiple dialing codes are used.

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

"DOM"

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.

category

optional

string

The highest level category that applies to this order as a whole, e.g. the type of service provided. See item.category to describe individual order items.

"delivery"

important

object

The delivery or drop-off location of the order. For taxis, can be the requested drop-off location to begin, and updated to the actual drop-off location once known.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

from

optional

object

The pick-up location of the order. For taxis, can be the requested pick-up location to begin, and updated to the actual pick-up location once known.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

items

important

array

The line items of the order, describing what the customer is purchasing. Including, but not limited to, products, services, journeys, tips, taxes, and delivery fees.

Show definition

Name Type Description Example

quantity

required

integer

Number of copies of this item that are present in the basket (set to 0 to remove).

1

sku

optional

string

A merchant specific identifier for an item or a service.

"delivery"

name

optional

string

The name of the product or service that is being purchased.

"Delivery Fee"

price

important

integer

The total price for a single one of these items, in the currency's basic units.

10000

currency

optional

string

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

Pattern: ^[a-zA-Z]{3}$

"GBP"

brand

optional

string

The name of the brand that the item is from.

upc

optional

string

The name of the Universal Item Code.

category

optional

string

The highest level category that this item is sold in.

"delivery"

subcategory

optional

string

A category that this item is sold in.

executionTime

optional

integer

The scheduled time for the service described by this item.

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

1512828988826

eventTicket

optional

object

If the item being purchased is a ticket for an event, associate the ticket and event information here.

Show definition

Name Type Description Example

ticket

required

object

The ticket information for this event.

Hide definition

Name	Type	Description	Example
ticketId required	string	A unique identifier for this ticket.	`"ticket_123"`
ticketType optional	string	A short human-readable description of the type of ticket.	`"Adult Single Day Pass"`
validFromTime optional	integer	Timestamp at which this ticket is valid from. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1480330580`
validUntilTime optional	integer	Timestamp at which this ticket is valid until. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1480340580`
refundable optional	boolean	Whether this ticket is refundable or not.

event

required

object

The event the ticket is granting access to. This could be a access to an event, an attraction, or any other activity the customer is purchasing a ticket to attend.

Hide definition

Name Type Description Example

eventId

required

string

A unique identifier for this event.

"event_123"

category

required

string

The category that best described the type of event.

One of: adventure, attraction, conference, convention, culinary, business, family, festival, health, live show, music, party, social, sport, or other.

"music"

venue

required

object

The location the event will take place.

Hide definition

Name Type Description Example

name

required

string

Name of the venue.

"Royal Albert Hall"

location

required

object

Location of the venue.

Hide definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

name

optional

string

The name of the event.

"The Fitzwilliam Museum."

description

optional

string

A short description of the event.

"Fitzwilliam Museum, Exhibition of Old Things"

startTime

optional

Timestamp at which event is scheduled to start. If the event is ongoing/recurring, you can use the ticket time here.

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

1480340580

endTime

optional

Timestamp at which event is scheduled to end. If the event is ongoing/recurring, you can use the ticket time here.

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

1480340580

guest

optional

object

The individual who will be attending the event.

Show definition

Name	Type	Description	Example
givenName required	string	The named guest's given name.	`"John"`
familyName required	string	The named guest's family name.	`"Smith"`
name optional	string	The named guest's full name.	`"John Smith"`
purchaser optional	boolean	Whether this guest is the individual who is purchasing the tickets.

travelTicket

optional

If the item being purchased is a ticket for travel, associate the journey information here.

Show definition

Name Type Description Example

ticketId

required

string

A unique identifier for the ticket

"tk_123"

description

optional

string

A human-readable text description of what the ticket provides

"Standard Advanced Single - Adult - Full Fare"

passenger

optional

object

The person travelling with this ticket.

Show definition

Name	Type	Description	Example
familyName optional	string		`"Smith"`
givenName optional	string		`"John"`
name optional	string		`"John Smith"`
email optional	string		`"jsmith@example.com"`
telephone optional	string		`"+447546186424"`
telephoneCountry optional	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
documentType optional	string	The type of document the passenger is traveling under One of: `passport`, `driverslicense`, or `id`.	`"passport"`
documentNumber optional	string	The number that identifies the document	`"1234-abcd"`
documentIssuingCountry optional	string	The 3 country code of the issuing country for the document	`"GBR"`
documentIssueTime optional	integer	The Unix timestamp that the document was issued	`1479122053910`
documentExpiryTime optional	integer	The Unix timestamp that the document expires	`1479122053910`
nationality optional	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
passengerType optional	string	The type of passenger this is One of: `adult`, `child`, `infant`, or `senior`.	`"adult"`
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.
gender deprecated	string

routes

optional

array

The list of routes that this ticket grants the holder travel on.

Show definition

Name Type Description Example

direction

optional

string

The direction of travel along this route, e.g. 'outward' or 'return'.

"outward"

journeyId

optional

string

This is an optional unique id to tie routes together. For example, You can tie a outbound and return route together with this. This way you can have multiple return tickets in one order and routes can be logically grouped together. This must be GLOBALLY UNIQUE

"xyz-123-ABC"

legs

optional

array

This is the list of travel legs taken by the passengers. It may contain any number of legs but must start at the first departure and end up at the final destination

Show definition

Name Type Description Example

legId

required

string

The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')

"leg-a1B2c3D4e5F6g7H"

departurePortCode

optional

string

Departure port code for the current leg. For flights: the 3 letter IATA airport code.

"LHR"

departurePort

optional

object

The location of the departure port for the current leg. For flights: the location of the airport.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

departureCity

optional

string

The name of the city of departure for the current leg.

"London"

departureCountryCode

optional

string

The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.

"GBR"

departureTime

optional

integer

The departure time for the current leg.

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

1478883331000

arrivalPortCode

optional

string

Arrival port code for the current leg. For flights: the 3 letter IATA airport code.

"SFO"

arrivalPort

optional

object

The location of the arrival port for the current leg. For flights: the location of the airport.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

arrivalCity

optional

string

The name of the city of arrival for the current leg.

"London"

arrivalCountryCode

optional

string

The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.

"GBR"

arrivalTime

optional

integer

The arrival time for the current leg.

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

1478883331000

carrierName

optional

string

The name of the carrier/company conducting the current leg.

"air canada"

carrierCode

optional

string

A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.

"AC"

transportationType

optional

string

The type of transportation.

One of: plane, train, bus, or ship.

seatReservation

optional

boolean

Whether there are seat reservations on this leg.

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.

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.

travelInsurance

optional

boolean

If the passenger purchased travel insurance.

true

ticketClass

optional

string

The class of travel this ticket grants access to.

One of: business, economy, first, or standard.

"first"

ticketType

optional

string

The type of ticket this belongs to. This includes round trip, multi city, open return, etc

"openreturn"

validUntilTime

optional

integer

The time that this ticket can be used until.

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

1478883331000

fulfilmentMethod

optional

string

The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc

"email"

loyaltyCardId

optional

string

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

"abc-123-loyalty-xyz"

discountCardId

optional

string

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

"abc-123-loyalty-xyz"

accommodation

optional

object

If the item being purchased represents accommodation being booked, associate the trip information here.

Show definition

Name Type Description Example

refundable

required

boolean

Whether this booking is refundable or not.

false

payOnArrival

required

boolean

Whether the payment is taken at the hotel during check-in.

true

guest

optional

object

The individual the booking is registered under (i.e the individual who will be checking in to the hotel). Either the current customer or another individual who the customer is booking the room on behalf of.

Show definition

Name	Type	Description	Example
familyName optional	string	The booked guest's family name.	`"Smith"`
givenName optional	string	The booked guest's given name.	`"John"`
name optional	string	The booked guest's full name.	`"John Smith"`

freeCancellationUntilTime

optional

integer

Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.

1480340580291

paymentDueBeforeTime

optional

integer

Timestamp at which payment is due. Ignore if payment is taken immediately at booking.

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

1480340580910

hotel

optional

object

Information on the hotel that the room is located in.

Show definition

Name Type Description Example

name

optional

string

The name of the hotel.

"The Overlook Hotel"

location

optional

object

The location of the hotel.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

starRating

optional

integer

The star-rating awarded to this hotel. Use an 'offical' hotel classification value here, not a customer rating value.

room

optional

object

Information on room being booked.

Show definition

Name	Type	Description	Example
name optional	string	The name of the room.	`"Grand Deluxe Double King Suite"`
checkInTime optional	integer	Timestamp at which guest check-in opens for the room. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
checkOutTime optional	integer	Timestamp at which guest check-out closes for the room. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
capacity optional	integer	Maximum number of adult guests the room can accomodate.

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.

note

optional

string

Descriptive text relating to the contents or nature of the order being completed.

optional

string

Contact e-mail for this order.

"jsmith@example.com"

telephone

optional

string

Contact phone number for this order. Best in E.164 format with an international dialing code.

"+441234558887"

telephoneCountry

optional

string

Contact phone number's country

"GBR"

sellerId

deprecated

string

The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. The restaurant, driver ID, etc.

"abcde12345-ZXY"

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.

executionTime

deprecated

integer

Deprecated in favour of items.executionTime. Execution or pick-up time of the order.

1512828988826

suppliers

optional

array

Suppliers (e.g. restaurants, couriers or drivers) involved in this order. See Suppliers for more information.

Show definition

Name Type Description Example

supplierId

required

string

The unique identifier of this supplier.

"abc-123-ZYZ"

type

required

string

The type of supplier.

One of: driver, courier, restaurant, shop, or other.

"courier"

status

important

object

Show definition

Name	Type	Description	Example
stage optional	string	The order processing stage reached by this supplier. One of: `accepted`, `in-progress`, `fulfilled`, or `cancelled`.	`"fulfilled"`
timestamp optional	integer	The time when the supplier's status changed. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
reason optional	string	The reason provided by the supplier for this status change.	`"Could not find passenger"`

fee

important

integer

The amount the supplier will earn from this order, in the currency's basic units.

250

debt

optional

integer

The value of a debt the supplier accrues to the platform as a result of this order, in the currency's basic units. For example, a supplier may accrue a debt if they accept a cash payment on behalf of the platform. The supplier's fee should not be deducted from the debt

e.g. if the supplier's fee is £2.50 and the customer pays the supplier £10 in cash, the debt should be 1000 and the fee 250.

1000

tip

optional

integer

A voluntary tip paid by the customer to the supplier for the order, in the currency's basic units. This is in addition to the supplier's fee.

200

currency

optional

string

The currency of the supplier's fee, tip and debt as an ISO 4217 currency code. Defaults to order currency.

Pattern: ^[a-zA-Z]{3}$

"GBP"

paymentMethod

important

object

A primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId and paymentMethods. One of the following:

One of the following:

•

card: A credit or debit card.

Show definition

Name Type Description Example

methodType

required

string

Vault card payment method indicator.

One of: card, creditcard, or debitcard.

"card"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

optional

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the cardBin, which should be preferred.

"visa"

instrumentId

important

string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

If you use multiple PSPs who each generate their own equivalent of an instrumentId, you should consider prefixing their values to indicate their origin to avoid collisions. Common examples include Stripe's fingerprint, or Braintree's unique_number_identifier).

"fp_abc123"

pan

pci, optional

string

The full Primary Account Number of the card. Used by Ravelin to determine the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

4111111111111111

cardBin

important

string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"

cardLastFour

important

string

The last four digits of the card number/PAN.

"0001"

issuer

optional

string

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard

optional

boolean

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued

optional

string

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

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

expiryMonth

important

integer

The expiry month of the card.

7

expiryYear

important

integer

The expiry year of the card.

2020

eWallet

deprecated

string

The e-Wallet to which the customer associated the card.

One of: applepay, googlepay, samsungpay, amazonpay, or visacheckout.

"applepay"

nameOnCard

important

string

The cardholder name.

"John Smith"

billingAddress

important

object

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

corporateCard

optional

boolean

Whether this payment method is a corporate card.

true

successfulRegistration

optional

boolean

Whether the card was successfully registered with your gateway/PSP.

true

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

compromised

optional

boolean

Whether the card has been compromised.

true

compromisedReason

important

string

The reason why the card is considered compromised.

One of: cloned, databreach, found, lost, stolen, frozen, defrosted, or uncompromised.

"stolen"

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.

active

deprecated

boolean

Whether this card is still saved to the customer's account.

banned

deprecated

boolean

Whether this card has been banned.

nickName

deprecated

string

The nickname the customer has given the payment method.

cardType

deprecated

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

•

paymentMethodCipher: An encrypted payment method, containing the full card details encrypted via a Ravelin SDK.

Show definition

Name Type Description Example

methodType

required

string

Client-side encrypted card payment method indicator.

Only: paymentMethodCipher.

"paymentMethodCipher"

cardCiphertext

required, pci

string

The card ciphertext produced by the Ravelin SDK card encryption.

This field constitutes cardholder data, and submission of this field therefore requires PCI DSS SAQ-A or SAQ-AEP certification. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

aesKeyCiphertext

required

string

The AES Key ciphertext produced by the Ravelin SDK card encryption.

algorithm

required

string

The algorithm used to generate the ciphertexts.

paymentMethodId

optional

string

Unique identifier for this payment method, different for each user.

ravelinSDKVersion

optional

string

The version of the ravelin SDK that performed this encryption.

keyIndex

optional

integer

The index of the public RSA key used to encrypt the card.

keySignature

optional

string

An identifier for the public key used during encryption.

billingAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

registrationTime

optional

integer

When the payment method was added to the user's account. Note: this is not the card start date.

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

ravelinjsVersion

deprecated

string

The version of the ravelinjs library that performed this encryption.

•

cash: The customer is paying in cash, or a cash-based payment method.

Show definition

Name		Type	Description	Example
methodType required		string	Indicator of a cash payment, or cash-based payment method (e.g. paysafecard). Only: `cash`.	`"cash"`
scheme optional		string	The name of the cash-based payment service used, if applicable.	`"paysafecard"`

•

bankaccount: Bank Accounts.

Show definition

Name Type Description Example

methodType

required

string

Bank account indicator.

Only: bankaccount.

"bankaccount"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

The type of transfer: whether the customer is initiating the payment, or you are withdrawing funds from the customer's bank account based on an agreement to initiate payments on their behalf. Use "push" for a customer-initiated payment (e.g. a bank transfer) and "pull" for a merchant-initiated payment (e.g. Direct Debit).

One of: push, or pull.

"push"

scheme

important

string

The name of the payment scheme or instrument used for the transfer of funds.

"sepa"

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

"GBR"

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

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.

•

paypal: PayPal payments.

Show definition

Name Type Description Example

methodType

required

string

PayPal indicator.

Only: paypal.

"paypal"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

payerId

optional

string

PayPal payer ID.

"WDJJHEBZ4X2LY"

important

string

Account email address.

"hello@examples.ru"

billingAddress

optional

object

The address of the account holder. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

countryIssued

optional

string

The two-character IS0-3166-1 account country_code sent by PayPal.

"GB"

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

If the payment method has been banned

active

deprecated

boolean

Whether the payment method is active for use by this account

•

credit: This payment method type should be used for any payments made using credit that a customer has with the merchant.

Show definition

Name	Type	Description	Example
methodType required	string	Credit payment indicator. Only: `credit`.	`"credit"`
paymentMethodId required	string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
scheme optional	string	The name of the store credit scheme used as a payment method, if applicable.	`"store-credit"`
registrationTime optional	integer	When the payment method was added to the user's account. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
lastVerified optional	integer	A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
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.

•

invoice: This payment method should be used whenever the merchant provides credit to the customer.

Show definition

Name Type Description Example

methodType

required

string

Invoice payment indicator.

Only: invoice.

"invoice"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

important

string

The name of the invoice or 'buy now, pay later' scheme used, if applicable.

"klarna-pay-later"

registrationTime

optional

integer

When the payment method was added to the user's account.

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

lastVerified

optional

integer

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

1512828988826

accountOwnerName

optional

string

The nickname for the payment method that the customers gives, if applicable.

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

optional

string

The email address used by the customer to register an invoice or 'buy now, pay later' payment method.

"jsmith123@example.com"

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.

•

wallet: A digital wallet payment method.

Show definition

Name Type Description Example

methodType

required

string

Vault card payment method indicator.

Only: wallet.

"wallet"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

required

string

The name of the digital wallet scheme or electronic payment service.

"applepay"

cardScheme

optional

string

The card network or scheme of the card used within a wallet payment method, such as visa or mastercard. Ravelin will identify the cardScheme on your behalf if you send the cardBin, which should be preferred.

"visa"

instrumentId

important

string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

"fp_abc123"

pan

pci, optional

string

4111111111111111

cardBin

important

string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"

cardLastFour

important

string

The last four digits of the card number/PAN.

"0001"

cardType

deprecated

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

issuer

optional

string

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard

optional

boolean

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued

optional

string

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

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

expiryMonth

important

integer

The expiry month of the card.

7

expiryYear

important

integer

The expiry year of the card.

2020

nameOnCard

important

string

The cardholder name.

"John Smith"

billingAddress

important

object

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

successfulRegistration

optional

boolean

Whether the card was successfully registered with your gateway/PSP.

true

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

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.

active

deprecated

boolean

Whether this card is still saved to the customer's account.

banned

deprecated

boolean

Whether this card has been banned.

nickName

deprecated

string

The nickname the customer has given the payment method.

•

fromTransaction: Refer to the payment method used by a named transaction. For usage examples, see saving cards after checkout or refunds to unknown cards.

Show definition

Name	Type	Description	Example
methodType required	string	Only: `fromTransaction`.	`"fromTransaction"`
transactionId important	string	The transaction ID to look up the payment method from.	`"tx-123"`
gateway important	string	The gateway that the transaction was processed through.	`"adyen"`
gatewayReference important	string	The gateway ref provided by the gateway for the transaction.	`"39407366378-1"`
paymentMethodId optional	string	When present, will duplicate the payment method from the referenced transaction and save it under this paymentMethodId for use later. Used when saving cards after checkout.	`"pm-abc123"`

•

~~directdebit: Direct Debits.~~ - deprecated.

Show definition

Name Type Description Example

methodType

required

string

Direct Debit indicator.

Only: directdebit.

"directdebit"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

Bank transfer type

Only: directdebit.

scheme

required

string

The type of direct debit scheme.

One of: autogiro, bacs, becs, becsnz, betalingsservice, or sepa.

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

mandateRef

optional

string

The unique reference issued for the direct debit mandate.

"DDREF12345"

mandateURL

optional

string

A URL to access the direct debit mandate agreement.

"https://somesite.com/ddportal/mandates/DDREF12345"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

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.

•

~~banktransfer: Bank Transfers.~~ - deprecated.

Show definition

Name Type Description Example

methodType

required

string

Bank transfer indicator.

Only: banktransfer.

"banktransfer"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

Bank transfer type

One of: bancontact, eps, giropay, ideal, inghomepay, sofort, or sepa.

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

"GBR"

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

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.

•

~~Others~~ - deprecated.

Show definition

Name	Type	Description	Example
methodType required	string	Other method type indicator. One of: `voucher`, `bitcoin`, `transfer`, `paysafe`, `cheque`, or `edenred`.	`"voucher"`
paymentMethodId required	string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
registrationTime optional	integer	When the payment method was added to the user's account. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
lastVerified optional	integer	A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
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.
nickName deprecated	string	The nickname for the payment method that the customers gives, if applicable.
banned deprecated	boolean	If the payment method has been banned
active deprecated	boolean	Whether the payment method is active for use by this account

•

Removal: Used for marking a saved payment method as removed from the account.

Show definition

Name		Type	Description	Example
paymentMethodId required		string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
active required		boolean	False to indicate the payment method has been deactivated. Only: `false`.	`false`

paymentMethods

important

array

One or more payment methods to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethodId.

paymentMethodId

important

string

The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod and paymentMethods.

"pm-abc123"

transaction

important

object

An attempt to charge a payment method to pay or be refunded for an order. Mutually exclusive with transactions.

Show definition

Name Type Description Example

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 preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1480340580291

amount

important

integer

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

1000

currency

optional

string

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

Pattern: ^[a-zA-Z]{3}$

"GBP"

type

important

string

The type of transaction interacting with the payment method.

auth: An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
capture: A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
auth_capture: A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
refund: A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refund transaction payment methods.
void: A void transaction is the explicit discarding of authorization of funds.
use, redeem: Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.

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

"auth_capture"

paymentMethodId

important

string

The ID of the payment method to be charged in this transaction.

"pm-abc123"

gateway

important

string

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

"braintree"

gatewayReference

important

string

The reference given to this transaction by the processing gateway. Used to link to chargebacks. Usually only available after attempting the payment. Each transaction should have a unique gateway reference.

"123-abc-XYZ"

success

important

boolean

Whether the transaction succesfully completed with no error.

true

3ds

optional

object

Details on how 3D Secure (3DS) was used to authenticate the transaction.

Show definition

Name	Type	Description	Example
attempted optional	boolean	Set to `true` if the 3D Secure authentication process was initiated for the transaction. The 3DS process is considered initiated when a check is performed to confirm issuer and cardholder enrolment, before asking for a challenge to be performed. This is set to `false` if the 3DS process was not initiated and the transaction proceeded to authorisation.	`true`
challenged optional	boolean	Set to `true` if a step-up authentication was initiated, for example, the user was asked to enter a password or use a form of biometric authentication. If `attempted` is set to `false`, then `challenged` should be omitted. If `attempted` is set to `true`, and a challenge was not presented to the user, then this field should be set to `false`. In 3DS2, if a user achieves a frictionless authentication this should also be set to `false`.	`true`
success optional	boolean	Set to `true` if the user was successfully authenticated using 3D Secure (either through frictionless authentication or a challenge) and the 3DS process was completed successfully. This field should be set to `false` if the user was unable to authenticate themselves during the challenge process, if an error occured, or frictionless authentication was not successful. This field should be omitted if `attempted` is set to `false`.	`true`
startTime optional	integer	The time at which the user was directed to 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064910`
endTime optional	integer	The time at which the user returned from 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064919`
timedOut optional	boolean	Whether the user is believed to have abandoned 3DS.	`false`
version optional	string	The version of 3DS which was used to authenticate the user. Either `1.0.2` or `2.1.0`	`"1.0.2"`
liabilityShifted optional	boolean	Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer. (See Liability Shifted Chargebacks.)	`true`
authenticationValue optional	string	A cryptographic value generated by the ACS to be used by the acquirer to validate the integrity of the authentication result. This should be a 28 character, base64 encoded string. For VISA transactions this is the CAVV (Cardholder Authentication Verification Value). For Mastercard transactions this is the AAV (Accountholder Authentication Value). For American Express transactions this is the AEVV (American Express Verification Value).	`"MDEyMzQ1Njc4OTAxMjM0NTY3ODk="`
eci optional	string	The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.	`"5"`
transStatus optional	string	The Transaction Status (transStatus) value received in the final authentication message. The final message type (PaRes, ARes, CRes) will vary depending on the version of 3DS and whether the user was challenged.	`"Y"`
transStatusReason optional	string	Provides information on why the transStatus field has the specified value. Will only be provided by the issuer when the transStatus value is N, U or R. (3DS 2 only)	`"01"`
messageType optional	string	Identifies the type of message from which the transStatus value was received. (3DS 2 only)	`"ARes"`
iReqCode optional	string	If the transStatus value is U the accompanying invalid request code (iReqCode) should be provided to further explain the reason authentication could not be performed. (3DS 1 only)	`"55"`

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 AVS checks. You must have at least one of street or postal code.

Any of the following:

Show definition

Name		Type	Description	Example
street optional		string	Compatible with common PSP codes	`"pass"`
postalCode optional		string	Compatible with common PSP codes	`"unchecked"`

cvvResultCode

optional

string

The result of CVV verification from the issuer, compatible with common PSP codes.

"pass"

mcc

optional

string

The Merchant Category 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"

acquirerBin

optional

string

The BIN (Bank Identification Number) of the acquirer.

"123456"

acquirerCountryCode

optional

string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"

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.

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.

credit

deprecated

integer

Deprected in favour of amount. The credit amount of the transaction in the lowest denomination of the currency.

transactions

important

array

One or more attempts to charge a payment method to pay or be refunded for an order. Mutually exclusive with transaction.

Show definition

Name Type Description Example

transactionId

important

string

A unique identifier for the transaction.

"123-abc-XYZ"

time

important

integer

The time that the transaction is being attempted.

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

1480340580291

amount

important

integer

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

1000

currency

optional

string

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

Pattern: ^[a-zA-Z]{3}$

"GBP"

type

important

string

The type of transaction interacting with the payment method.

auth: An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
capture: A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
auth_capture: A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
refund: A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refund transaction payment methods.
void: A void transaction is the explicit discarding of authorization of funds.
use, redeem: Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.

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

"auth_capture"

paymentMethodId

important

string

The ID of the payment method to be charged in this transaction.

"pm-abc123"

gateway

important

string

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

"braintree"

gatewayReference

important

string

"123-abc-XYZ"

success

important

boolean

Whether the transaction succesfully completed with no error.

true

3ds

optional

object

Details on how 3D Secure (3DS) was used to authenticate the transaction.

Show definition

Name	Type	Description	Example
attempted optional	boolean	Set to `true` if the 3D Secure authentication process was initiated for the transaction. The 3DS process is considered initiated when a check is performed to confirm issuer and cardholder enrolment, before asking for a challenge to be performed. This is set to `false` if the 3DS process was not initiated and the transaction proceeded to authorisation.	`true`
challenged optional	boolean	Set to `true` if a step-up authentication was initiated, for example, the user was asked to enter a password or use a form of biometric authentication. If `attempted` is set to `false`, then `challenged` should be omitted. If `attempted` is set to `true`, and a challenge was not presented to the user, then this field should be set to `false`. In 3DS2, if a user achieves a frictionless authentication this should also be set to `false`.	`true`
success optional	boolean	Set to `true` if the user was successfully authenticated using 3D Secure (either through frictionless authentication or a challenge) and the 3DS process was completed successfully. This field should be set to `false` if the user was unable to authenticate themselves during the challenge process, if an error occured, or frictionless authentication was not successful. This field should be omitted if `attempted` is set to `false`.	`true`
startTime optional	integer	The time at which the user was directed to 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064910`
endTime optional	integer	The time at which the user returned from 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064919`
timedOut optional	boolean	Whether the user is believed to have abandoned 3DS.	`false`
version optional	string	The version of 3DS which was used to authenticate the user. Either `1.0.2` or `2.1.0`	`"1.0.2"`
liabilityShifted optional	boolean	Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer. (See Liability Shifted Chargebacks.)	`true`
authenticationValue optional	string	A cryptographic value generated by the ACS to be used by the acquirer to validate the integrity of the authentication result. This should be a 28 character, base64 encoded string. For VISA transactions this is the CAVV (Cardholder Authentication Verification Value). For Mastercard transactions this is the AAV (Accountholder Authentication Value). For American Express transactions this is the AEVV (American Express Verification Value).	`"MDEyMzQ1Njc4OTAxMjM0NTY3ODk="`
eci optional	string	The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.	`"5"`
transStatus optional	string	The Transaction Status (transStatus) value received in the final authentication message. The final message type (PaRes, ARes, CRes) will vary depending on the version of 3DS and whether the user was challenged.	`"Y"`
transStatusReason optional	string	Provides information on why the transStatus field has the specified value. Will only be provided by the issuer when the transStatus value is N, U or R. (3DS 2 only)	`"01"`
messageType optional	string	Identifies the type of message from which the transStatus value was received. (3DS 2 only)	`"ARes"`
iReqCode optional	string	If the transStatus value is U the accompanying invalid request code (iReqCode) should be provided to further explain the reason authentication could not be performed. (3DS 1 only)	`"55"`

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 AVS checks. You must have at least one of street or postal code.

Any of the following:

Show definition

Name		Type	Description	Example
street optional		string	Compatible with common PSP codes	`"pass"`
postalCode optional		string	Compatible with common PSP codes	`"unchecked"`

cvvResultCode

optional

string

The result of CVV verification from the issuer, compatible with common PSP codes.

"pass"

mcc

optional

string

The Merchant Category 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"

acquirerBin

optional

string

The BIN (Bank Identification Number) of the acquirer.

"123456"

acquirerCountryCode

optional

string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"

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.

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.

credit

deprecated

integer

Deprected in favour of amount. The credit amount of the transaction in the lowest denomination of the currency.

voucherRedemption

optional

object

A voucher that is being used to pay for some of the order.

Show definition

Name	Type	Description	Example
paymentMethodId required	string	A unique identifier for the voucher usage. A transactionId for vouchers.	`"VOUCH-89-abc-123-ZYZ"`
voucherCode required	string	The string customers actually see in their app.	`"VOUCH-89"`
value required	integer	The value that the voucher can be exchanged for, in the currency's basic units.	`10000`
redemptionTime required	integer	The time that the customer is utilising the voucher. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
success required	boolean	Whether the voucher has successfully been used by the customer.	`true`
currency optional	string	The currency of the value of this voucher, as an ISO 4217 currency code. Pattern: `^[a-zA-Z]{3}$`	`"GBP"`
expiry optional	integer	The time the after which the voucher can no longer be redeemed. A unix timestamp as an integer count of milliseconds, or nanoseconds since `1970-01-01T00:00` UTC.
voucherType optional	string	The type of the voucher. If `REFERRAL`, also set the `referredId` so Ravelin will create a network of who has invited who. One of: `REFERRAL`, `REACTIVATION`, or `GENERAL`.	`"GENERAL"`
referrerId optional	string	The `customerId` of the customer who created this voucher.
referralValue optional	integer	The amount the referring customer of the voucher gets when the voucher is used, in the currency's basic units.
failureReason optional	string	Optional reason why the attempt was not successful. One of: `EXPIRED`, `NOT_NEW_CUSTOMER`, `ALREADY_USED`, `ABUSER`, `SYSTEM_FAILURE`, or `MAX_ALLOWED_TIMES`.
failureSource optional	string	the source of why the voucher failed One of: `RAVELIN`, or `CLIENT`.
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.

voucherRedemptions

optional

array

Any vouchers that are being used to pay for some of the order.

Show definition

Name	Type	Description	Example
paymentMethodId required	string	A unique identifier for the voucher usage. A transactionId for vouchers.	`"VOUCH-89-abc-123-ZYZ"`
voucherCode required	string	The string customers actually see in their app.	`"VOUCH-89"`
value required	integer	The value that the voucher can be exchanged for, in the currency's basic units.	`10000`
redemptionTime required	integer	The time that the customer is utilising the voucher. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
success required	boolean	Whether the voucher has successfully been used by the customer.	`true`
currency optional	string	The currency of the value of this voucher, as an ISO 4217 currency code. Pattern: `^[a-zA-Z]{3}$`	`"GBP"`
expiry optional	integer	The time the after which the voucher can no longer be redeemed. A unix timestamp as an integer count of milliseconds, or nanoseconds since `1970-01-01T00:00` UTC.
voucherType optional	string	The type of the voucher. If `REFERRAL`, also set the `referredId` so Ravelin will create a network of who has invited who. One of: `REFERRAL`, `REACTIVATION`, or `GENERAL`.	`"GENERAL"`
referrerId optional	string	The `customerId` of the customer who created this voucher.
referralValue optional	integer	The amount the referring customer of the voucher gets when the voucher is used, in the currency's basic units.
failureReason optional	string	Optional reason why the attempt was not successful. One of: `EXPIRED`, `NOT_NEW_CUSTOMER`, `ALREADY_USED`, `ABUSER`, `SYSTEM_FAILURE`, or `MAX_ALLOWED_TIMES`.
failureSource optional	string	the source of why the voucher failed One of: `RAVELIN`, or `CLIENT`.
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.

device

optional

object

The device used by the customer to trigger this update.

Show definition

Name Type Description Example

deviceId

required

string

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

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

ipAddress

important

string

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

"81.152.92.84"

language

optional

string

The ISO 639 code of your user's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

"en-US"

userAgent

important

string

The browser user-agent string, if the device represents a web browser - window.navigator.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

important

string

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

"Pixel XL"

important

string

The operating system that the device is running.

"android"

type

optional

string

The type of device.

One of: computer, phone, or tablet.

"phone"

manufacturer

optional

string

The maker of the device.

"google"

location

optional

object

The geolocated position of the device.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

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.

browser

deprecated

string

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

javascriptEnabled

deprecated

boolean

Whether Javascript is enabled on the web browser.

cookiesEnabled

deprecated

boolean

Whether cookies are enabled on the web browser.

screenResolution

deprecated

string

The resolution of the screen on the device in the format XxY

deviceId

optional

string

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

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

POST /v2/chargeback

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

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

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

If only the original order ID is known, Ravelin will guess that the first successful auth, capture, or auth_capture transaction is the charge being disputed.

If no transaction with a matching orderId, gatewayReference or transactionId 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
  }
}

Name Type Description Example

timestamp

required

integer

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

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

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	The PSP/gateway's reference for the transaction which was 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. Pattern: `^[a-zA-Z]{3}$`	`"GBP"`
disputeTime important	integer	The time that the dispute that lead to this chargeback was opened. Used in reporting. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479302798`
reason optional	string	The reason code from the chargeback.	`"fraud"`
status optional	string	The status of the dispute. Preferably one of: `OPEN`: No action has been taken yet. `ACCEPTED`: You have opted out of providing evidence against the chargeback or pre-arb. `DISPUTED`: You have submitted evidence against the claim and are waiting for the decision from the bank. `LOST`: The bank has not ruled in your favour, the funds will be returned to the cardholder, and you will pay a chargeback penalty. `WON`: The bank has ruled in your favour, and you will keep the funds originally collected from the card. `EXPIRED`: The date to submit evidence has passed and you have forfeited your right to dispute the case. See notifications of fraud for sending TC-40s, Ethoca Alerts and other early notifications.	`"LOST"`
liabilityShifted optional	boolean	Whether liability for this chargeback was shifted to a third-party, such as your PSP or gateway. (See liability-shifted chargebacks.)	`true`
nonFraud optional	boolean	Whether this chargeback was claimed for reasons other than fraud. If this chargeback was not filed for reasons of fraud (e.g. goods not as described) then be sure to set a `reason`. (See non-fraudulent chargebacks.)	`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.

eventType

optional

string

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

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

optional

string

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

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

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

Name Type Description Example

timestamp

required

integer

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

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

1512828988826

customer

required

object

The customer registering or updating their account profile. (See customers.)

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 preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

important

string

The email address of the customer.

"jsmith123@example.com"

emailVerifiedTime

optional

integer

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

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

1512828988826

name

important

string

The full name of the customer. If you have the name split into parts, consider familyName and givenName 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 confirming a code from an SMS you sent to the number.

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

1512828988826

telephoneCountry

optional

string

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

"DOM"

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.

POST /v2/order

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

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "tempCustomerId": "abc-123-XYZ",
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "category": "delivery",
    "to": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "from": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ],
    "email": "jsmith@example.com",
    "telephone": "+441234558887",
    "telephoneCountry": "GBR",
    "sellerId": "abcde12345-ZXY",
    "executionTime": 1512828988826,
    "suppliers": [
      {
        "supplierId": "abc-123-ZYZ",
        "status": {
          "stage": "fulfilled",
          "timestamp": 1512828988826,
          "reason": "Could not find passenger"
        },
        "fee": 250,
        "debt": 1000,
        "tip": 200,
        "currency": "GBP",
        "type": "courier"
      }
    ]
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Name Type Description Example

timestamp

required

integer

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

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

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 preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

app

important

object

The mobile or web app that this order was submitted on. Used for segmenting business analytics and creating app-specific risk profiles.

Show definition

Name	Type	Description	Example
name optional	string	The name or brand of the app, used to segment orders. Use the name that customer sees when installing and using the app, or the website title. Shouldn't repeat the platform or domain.	`"Our App Lite"`
platform optional	string	Where this app runs. One of: `ios`, `android`, `web`, or `mobile-web`.	`"web"`
domain optional	string	The domain from the URL of the web app, using the characters `a-z0-9-.`. Pattern: `^[a-z0-9-\.]+$`	`"us.brand.com"`

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

Name		Type	Description	Example
stage required		string	Only: `pending`.	`"pending"`
actor optional		string	The actor who caused the status change e.g. buyer, merchant.	`"merchant"`

•

Show definition

•

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

Show definition

Name	Type	Description	Example
stage required	string	Only: `failed`.	`"failed"`
reason required	string	Description of why the order has failed. One of: `payment_declined`, `seller_rejected`, or `system_error`.	`"payment_declined"`
actor optional	string	The actor who caused the status change e.g. buyer, merchant.	`"buyer"`

•

Cancelled: The order has been cancelled.

Show definition

Name	Type	Description	Example
stage required	string	Only: `cancelled`.
reason required	string	Description of why the order has been cancelled. One of: `buyer`, `seller`, `merchant`, or `ravelin`.	`"buyer"`
actor optional	string	The actor who caused the status change e.g. buyer, merchant.	`"buyer"`

•

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

Show definition

Name		Type	Description	Example
stage required		string	Only: `fulfilled`.	`"fulfilled"`
actor optional		string	The actor who caused the status change e.g. buyer, merchant.	`"buyer"`

•

Refunded: The order has been refunded.

Show definition

Name	Type	Description	Example
stage required	string	Only: `refunded`.	`"refunded"`
reason required	string	A description of why the order has been refunded. One of: `returned`, `complaint`, or `ato`.	`"returned"`
actor optional	string	The actor who caused the status change e.g. buyer, merchant.	`"buyer"`

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.

Pattern: ^[a-zA-Z]{3}$

"GBP"

country

important

string

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

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

"emea"

marketCity

important

string

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

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

"london"

category

optional

string

The highest level category that applies to this order as a whole, e.g. the type of service provided. See item.category to describe individual order items.

"delivery"

important

object

The delivery or drop-off location of the order. For taxis, can be the requested drop-off location to begin, and updated to the actual drop-off location once known.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

from

optional

object

The pick-up location of the order. For taxis, can be the requested pick-up location to begin, and updated to the actual pick-up location once known.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

items

important

array

The line items of the order, describing what the customer is purchasing. Including, but not limited to, products, services, journeys, tips, taxes, and delivery fees.

Show definition

Name Type Description Example

quantity

required

integer

Number of copies of this item that are present in the basket (set to 0 to remove).

1

sku

optional

string

A merchant specific identifier for an item or a service.

"delivery"

name

optional

string

The name of the product or service that is being purchased.

"Delivery Fee"

price

important

integer

The total price for a single one of these items, in the currency's basic units.

10000

currency

optional

string

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

Pattern: ^[a-zA-Z]{3}$

"GBP"

brand

optional

string

The name of the brand that the item is from.

upc

optional

string

The name of the Universal Item Code.

category

optional

string

The highest level category that this item is sold in.

"delivery"

subcategory

optional

string

A category that this item is sold in.

executionTime

optional

integer

The scheduled time for the service described by this item.

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

1512828988826

eventTicket

optional

object

If the item being purchased is a ticket for an event, associate the ticket and event information here.

Show definition

Name Type Description Example

ticket

required

object

The ticket information for this event.

Hide definition

Name	Type	Description	Example
ticketId required	string	A unique identifier for this ticket.	`"ticket_123"`
ticketType optional	string	A short human-readable description of the type of ticket.	`"Adult Single Day Pass"`
validFromTime optional	integer	Timestamp at which this ticket is valid from. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1480330580`
validUntilTime optional	integer	Timestamp at which this ticket is valid until. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1480340580`
refundable optional	boolean	Whether this ticket is refundable or not.

event

required

object

The event the ticket is granting access to. This could be a access to an event, an attraction, or any other activity the customer is purchasing a ticket to attend.

Hide definition

Name Type Description Example

eventId

required

string

A unique identifier for this event.

"event_123"

category

required

string

The category that best described the type of event.

One of: adventure, attraction, conference, convention, culinary, business, family, festival, health, live show, music, party, social, sport, or other.

"music"

venue

required

object

The location the event will take place.

Hide definition

Name Type Description Example

name

required

string

Name of the venue.

"Royal Albert Hall"

location

required

object

Location of the venue.

Hide definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

name

optional

string

The name of the event.

"The Fitzwilliam Museum."

description

optional

string

A short description of the event.

"Fitzwilliam Museum, Exhibition of Old Things"

startTime

optional

Timestamp at which event is scheduled to start. If the event is ongoing/recurring, you can use the ticket time here.

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

1480340580

endTime

optional

Timestamp at which event is scheduled to end. If the event is ongoing/recurring, you can use the ticket time here.

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

1480340580

guest

optional

object

The individual who will be attending the event.

Show definition

Name	Type	Description	Example
givenName required	string	The named guest's given name.	`"John"`
familyName required	string	The named guest's family name.	`"Smith"`
name optional	string	The named guest's full name.	`"John Smith"`
purchaser optional	boolean	Whether this guest is the individual who is purchasing the tickets.

travelTicket

optional

If the item being purchased is a ticket for travel, associate the journey information here.

Show definition

Name Type Description Example

ticketId

required

string

A unique identifier for the ticket

"tk_123"

description

optional

string

A human-readable text description of what the ticket provides

"Standard Advanced Single - Adult - Full Fare"

passenger

optional

object

The person travelling with this ticket.

Show definition

Name	Type	Description	Example
familyName optional	string		`"Smith"`
givenName optional	string		`"John"`
name optional	string		`"John Smith"`
email optional	string		`"jsmith@example.com"`
telephone optional	string		`"+447546186424"`
telephoneCountry optional	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
documentType optional	string	The type of document the passenger is traveling under One of: `passport`, `driverslicense`, or `id`.	`"passport"`
documentNumber optional	string	The number that identifies the document	`"1234-abcd"`
documentIssuingCountry optional	string	The 3 country code of the issuing country for the document	`"GBR"`
documentIssueTime optional	integer	The Unix timestamp that the document was issued	`1479122053910`
documentExpiryTime optional	integer	The Unix timestamp that the document expires	`1479122053910`
nationality optional	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
passengerType optional	string	The type of passenger this is One of: `adult`, `child`, `infant`, or `senior`.	`"adult"`
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.
gender deprecated	string

routes

optional

array

The list of routes that this ticket grants the holder travel on.

Show definition

Name Type Description Example

direction

optional

string

The direction of travel along this route, e.g. 'outward' or 'return'.

"outward"

journeyId

optional

string

"xyz-123-ABC"

legs

optional

array

This is the list of travel legs taken by the passengers. It may contain any number of legs but must start at the first departure and end up at the final destination

Show definition

Name Type Description Example

legId

required

string

The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')

"leg-a1B2c3D4e5F6g7H"

departurePortCode

optional

string

Departure port code for the current leg. For flights: the 3 letter IATA airport code.

"LHR"

departurePort

optional

object

The location of the departure port for the current leg. For flights: the location of the airport.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

departureCity

optional

string

The name of the city of departure for the current leg.

"London"

departureCountryCode

optional

string

The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.

"GBR"

departureTime

optional

integer

The departure time for the current leg.

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

1478883331000

arrivalPortCode

optional

string

Arrival port code for the current leg. For flights: the 3 letter IATA airport code.

"SFO"

arrivalPort

optional

object

The location of the arrival port for the current leg. For flights: the location of the airport.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

arrivalCity

optional

string

The name of the city of arrival for the current leg.

"London"

arrivalCountryCode

optional

string

The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.

"GBR"

arrivalTime

optional

integer

The arrival time for the current leg.

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

1478883331000

carrierName

optional

string

The name of the carrier/company conducting the current leg.

"air canada"

carrierCode

optional

string

A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.

"AC"

transportationType

optional

string

The type of transportation.

One of: plane, train, bus, or ship.

seatReservation

optional

boolean

Whether there are seat reservations on this leg.

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.

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.

travelInsurance

optional

boolean

If the passenger purchased travel insurance.

true

ticketClass

optional

string

The class of travel this ticket grants access to.

One of: business, economy, first, or standard.

"first"

ticketType

optional

string

The type of ticket this belongs to. This includes round trip, multi city, open return, etc

"openreturn"

validUntilTime

optional

integer

The time that this ticket can be used until.

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

1478883331000

fulfilmentMethod

optional

string

The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc

"email"

loyaltyCardId

optional

string

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

"abc-123-loyalty-xyz"

discountCardId

optional

string

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

"abc-123-loyalty-xyz"

accommodation

optional

object

If the item being purchased represents accommodation being booked, associate the trip information here.

Show definition

Name Type Description Example

refundable

required

boolean

Whether this booking is refundable or not.

false

payOnArrival

required

boolean

Whether the payment is taken at the hotel during check-in.

true

guest

optional

object

Show definition

Name	Type	Description	Example
familyName optional	string	The booked guest's family name.	`"Smith"`
givenName optional	string	The booked guest's given name.	`"John"`
name optional	string	The booked guest's full name.	`"John Smith"`

freeCancellationUntilTime

optional

integer

Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.

1480340580291

paymentDueBeforeTime

optional

integer

Timestamp at which payment is due. Ignore if payment is taken immediately at booking.

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

1480340580910

hotel

optional

object

Information on the hotel that the room is located in.

Show definition

Name Type Description Example

name

optional

string

The name of the hotel.

"The Overlook Hotel"

location

optional

object

The location of the hotel.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

starRating

optional

integer

The star-rating awarded to this hotel. Use an 'offical' hotel classification value here, not a customer rating value.

room

optional

object

Information on room being booked.

Show definition

Name	Type	Description	Example
name optional	string	The name of the room.	`"Grand Deluxe Double King Suite"`
checkInTime optional	integer	Timestamp at which guest check-in opens for the room. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
checkOutTime optional	integer	Timestamp at which guest check-out closes for the room. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
capacity optional	integer	Maximum number of adult guests the room can accomodate.

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.

note

optional

string

Descriptive text relating to the contents or nature of the order being completed.

optional

string

Contact e-mail for this order.

"jsmith@example.com"

telephone

optional

string

Contact phone number for this order. Best in E.164 format with an international dialing code.

"+441234558887"

telephoneCountry

optional

string

Contact phone number's country

"GBR"

sellerId

deprecated

string

The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. The restaurant, driver ID, etc.

"abcde12345-ZXY"

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.

executionTime

deprecated

integer

Deprecated in favour of items.executionTime. Execution or pick-up time of the order.

1512828988826

suppliers

optional

array

Suppliers (e.g. restaurants, couriers or drivers) involved in this order. See Suppliers for more information.

Show definition

Name Type Description Example

supplierId

required

string

The unique identifier of this supplier.

"abc-123-ZYZ"

type

required

string

The type of supplier.

One of: driver, courier, restaurant, shop, or other.

"courier"

status

important

object

Show definition

Name	Type	Description	Example
stage optional	string	The order processing stage reached by this supplier. One of: `accepted`, `in-progress`, `fulfilled`, or `cancelled`.	`"fulfilled"`
timestamp optional	integer	The time when the supplier's status changed. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
reason optional	string	The reason provided by the supplier for this status change.	`"Could not find passenger"`

fee

important

integer

The amount the supplier will earn from this order, in the currency's basic units.

250

debt

optional

integer

e.g. if the supplier's fee is £2.50 and the customer pays the supplier £10 in cash, the debt should be 1000 and the fee 250.

1000

tip

optional

integer

A voluntary tip paid by the customer to the supplier for the order, in the currency's basic units. This is in addition to the supplier's fee.

200

currency

optional

string

The currency of the supplier's fee, tip and debt as an ISO 4217 currency code. Defaults to order currency.

Pattern: ^[a-zA-Z]{3}$

"GBP"

eventType

optional

string

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

customerId

optional

string

The ID of the customer whose order is being submitted or updated. (See customers.)

"abc-123-ZYZ"

tempCustomerId

optional

string

A temporary ID for a customer when the real account ID has yet to be minted. This must eventually 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

Name Type Description Example

deviceId

required

string

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

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

ipAddress

important

string

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

"81.152.92.84"

language

optional

string

The ISO 639 code of your user's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

"en-US"

userAgent

important

string

The browser user-agent string, if the device represents a web browser - window.navigator.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

important

string

"Pixel XL"

important

string

The operating system that the device is running.

"android"

type

optional

string

The type of device.

One of: computer, phone, or tablet.

"phone"

manufacturer

optional

string

The maker of the device.

"google"

location

optional

object

The geolocated position of the device.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

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.

browser

deprecated

string

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

javascriptEnabled

deprecated

boolean

Whether Javascript is enabled on the web browser.

cookiesEnabled

deprecated

boolean

Whether cookies are enabled on the web browser.

screenResolution

deprecated

string

The resolution of the screen on the device in the format XxY

deviceId

optional

string

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

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

POST /v2/paymentmethod

This endpoint is used to inform Ravelin of payment methods being saved to or used by a customer account.

The information that you use to populate the paymentMethod varies between PSPs, after tokenization. If the PSP is unable to provide you with a suitable instrumentId, you should strongly consider allowing Ravelin to generate instrumentIds on your behalf by submitting either full PANs, or client-side encrypted cards to Ravelin. For more information, please refer to our PCI DSS documentation.

Ravelin does not accept submission of the CVV, PIN or magnetic stripe data to any of our API endpoints.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "tempCustomerId": "abc-123-XYZ",
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "scheme": "visa",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "eWallet": "applepay",
    "nameOnCard": "John Smith",
    "billingAddress": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "corporateCard": true,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826,
    "compromised": true,
    "compromisedReason": "stolen"
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Name Type Description Example

timestamp

required

integer

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

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

1512828988826

eventType

optional

string

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

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 eventually be sent in conjunction with a real customer ID to migrate the data into the full customer account.

"abc-123-XYZ"

paymentMethod

optional

object

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

One of the following:

•

card: A credit or debit card.

Show definition

Name Type Description Example

methodType

required

string

Vault card payment method indicator.

One of: card, creditcard, or debitcard.

"card"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

optional

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the cardBin, which should be preferred.

"visa"

instrumentId

important

string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

"fp_abc123"

pan

pci, optional

string

4111111111111111

cardBin

important

string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"

cardLastFour

important

string

The last four digits of the card number/PAN.

"0001"

issuer

optional

string

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard

optional

boolean

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued

optional

string

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

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

expiryMonth

important

integer

The expiry month of the card.

7

expiryYear

important

integer

The expiry year of the card.

2020

eWallet

deprecated

string

The e-Wallet to which the customer associated the card.

One of: applepay, googlepay, samsungpay, amazonpay, or visacheckout.

"applepay"

nameOnCard

important

string

The cardholder name.

"John Smith"

billingAddress

important

object

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

corporateCard

optional

boolean

Whether this payment method is a corporate card.

true

successfulRegistration

optional

boolean

Whether the card was successfully registered with your gateway/PSP.

true

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

compromised

optional

boolean

Whether the card has been compromised.

true

compromisedReason

important

string

The reason why the card is considered compromised.

One of: cloned, databreach, found, lost, stolen, frozen, defrosted, or uncompromised.

"stolen"

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.

active

deprecated

boolean

Whether this card is still saved to the customer's account.

banned

deprecated

boolean

Whether this card has been banned.

nickName

deprecated

string

The nickname the customer has given the payment method.

cardType

deprecated

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

•

paymentMethodCipher: An encrypted payment method, containing the full card details encrypted via a Ravelin SDK.

Show definition

Name Type Description Example

methodType

required

string

Client-side encrypted card payment method indicator.

Only: paymentMethodCipher.

"paymentMethodCipher"

cardCiphertext

required, pci

string

The card ciphertext produced by the Ravelin SDK card encryption.

Please see our PCI DSS documentation for more information.

aesKeyCiphertext

required

string

The AES Key ciphertext produced by the Ravelin SDK card encryption.

algorithm

required

string

The algorithm used to generate the ciphertexts.

paymentMethodId

optional

string

Unique identifier for this payment method, different for each user.

ravelinSDKVersion

optional

string

The version of the ravelin SDK that performed this encryption.

keyIndex

optional

integer

The index of the public RSA key used to encrypt the card.

keySignature

optional

string

An identifier for the public key used during encryption.

billingAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

registrationTime

optional

integer

When the payment method was added to the user's account. Note: this is not the card start date.

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

ravelinjsVersion

deprecated

string

The version of the ravelinjs library that performed this encryption.

•

cash: The customer is paying in cash, or a cash-based payment method.

Show definition

Name		Type	Description	Example
methodType required		string	Indicator of a cash payment, or cash-based payment method (e.g. paysafecard). Only: `cash`.	`"cash"`
scheme optional		string	The name of the cash-based payment service used, if applicable.	`"paysafecard"`

•

bankaccount: Bank Accounts.

Show definition

Name Type Description Example

methodType

required

string

Bank account indicator.

Only: bankaccount.

"bankaccount"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

One of: push, or pull.

"push"

scheme

important

string

The name of the payment scheme or instrument used for the transfer of funds.

"sepa"

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

"GBR"

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

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.

•

paypal: PayPal payments.

Show definition

Name Type Description Example

methodType

required

string

PayPal indicator.

Only: paypal.

"paypal"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

payerId

optional

string

PayPal payer ID.

"WDJJHEBZ4X2LY"

important

string

Account email address.

"hello@examples.ru"

billingAddress

optional

object

The address of the account holder. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

countryIssued

optional

string

The two-character IS0-3166-1 account country_code sent by PayPal.

"GB"

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

If the payment method has been banned

active

deprecated

boolean

Whether the payment method is active for use by this account

•

credit: This payment method type should be used for any payments made using credit that a customer has with the merchant.

Show definition

Name	Type	Description	Example
methodType required	string	Credit payment indicator. Only: `credit`.	`"credit"`
paymentMethodId required	string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
scheme optional	string	The name of the store credit scheme used as a payment method, if applicable.	`"store-credit"`
registrationTime optional	integer	When the payment method was added to the user's account. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
lastVerified optional	integer	A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
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.

•

invoice: This payment method should be used whenever the merchant provides credit to the customer.

Show definition

Name Type Description Example

methodType

required

string

Invoice payment indicator.

Only: invoice.

"invoice"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

important

string

The name of the invoice or 'buy now, pay later' scheme used, if applicable.

"klarna-pay-later"

registrationTime

optional

integer

When the payment method was added to the user's account.

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

lastVerified

optional

integer

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

1512828988826

accountOwnerName

optional

string

The nickname for the payment method that the customers gives, if applicable.

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

optional

string

The email address used by the customer to register an invoice or 'buy now, pay later' payment method.

"jsmith123@example.com"

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.

•

wallet: A digital wallet payment method.

Show definition

Name Type Description Example

methodType

required

string

Vault card payment method indicator.

Only: wallet.

"wallet"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

required

string

The name of the digital wallet scheme or electronic payment service.

"applepay"

cardScheme

optional

string

"visa"

instrumentId

important

string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

"fp_abc123"

pan

pci, optional

string

4111111111111111

cardBin

important

string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"

cardLastFour

important

string

The last four digits of the card number/PAN.

"0001"

cardType

deprecated

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

issuer

optional

string

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard

optional

boolean

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued

optional

string

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

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

expiryMonth

important

integer

The expiry month of the card.

7

expiryYear

important

integer

The expiry year of the card.

2020

nameOnCard

important

string

The cardholder name.

"John Smith"

billingAddress

important

object

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

successfulRegistration

optional

boolean

Whether the card was successfully registered with your gateway/PSP.

true

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

lastVerified

optional

integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

1512828988826

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.

active

deprecated

boolean

Whether this card is still saved to the customer's account.

banned

deprecated

boolean

Whether this card has been banned.

nickName

deprecated

string

The nickname the customer has given the payment method.

•

fromTransaction: Refer to the payment method used by a named transaction. For usage examples, see saving cards after checkout or refunds to unknown cards.

Show definition

Name	Type	Description	Example
methodType required	string	Only: `fromTransaction`.	`"fromTransaction"`
transactionId important	string	The transaction ID to look up the payment method from.	`"tx-123"`
gateway important	string	The gateway that the transaction was processed through.	`"adyen"`
gatewayReference important	string	The gateway ref provided by the gateway for the transaction.	`"39407366378-1"`
paymentMethodId optional	string	When present, will duplicate the payment method from the referenced transaction and save it under this paymentMethodId for use later. Used when saving cards after checkout.	`"pm-abc123"`

•

~~directdebit: Direct Debits.~~ - deprecated.

Show definition

Name Type Description Example

methodType

required

string

Direct Debit indicator.

Only: directdebit.

"directdebit"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

Bank transfer type

Only: directdebit.

scheme

required

string

The type of direct debit scheme.

One of: autogiro, bacs, becs, becsnz, betalingsservice, or sepa.

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

mandateRef

optional

string

The unique reference issued for the direct debit mandate.

"DDREF12345"

mandateURL

optional

string

A URL to access the direct debit mandate agreement.

"https://somesite.com/ddportal/mandates/DDREF12345"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

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.

•

~~banktransfer: Bank Transfers.~~ - deprecated.

Show definition

Name Type Description Example

methodType

required

string

Bank transfer indicator.

Only: banktransfer.

"banktransfer"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

transferType

required

string

Bank transfer type

One of: bancontact, eps, giropay, ideal, inghomepay, sofort, or sepa.

iban

optional

string

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

"GB15HBUK40127612345678"

countryIssued

optional

string

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

"GBR"

accountAddress

optional

object

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

accountOwnerName

optional

string

The name of the account owner.

"John Smith"

bankCode

optional

string

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

"401276"

bankName

optional

string

Name of bank which account belongs to.

"HSBC Bank"

bic

optional

string

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

"HBUKGB4B"

accountNumber

optional

string

The account number issued by the bank.

"12345678"

nickName

optional

string

The nickname for the payment method that the customers gives, if applicable.

"joescard"

registrationTime

important

integer

The time that the card was saved to the customer's account. (Not the card start date.)

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

1512828988826

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.

•

~~Others~~ - deprecated.

Show definition

Name	Type	Description	Example
methodType required	string	Other method type indicator. One of: `voucher`, `bitcoin`, `transfer`, `paysafe`, `cheque`, or `edenred`.	`"voucher"`
paymentMethodId required	string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
registrationTime optional	integer	When the payment method was added to the user's account. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).
lastVerified optional	integer	A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1512828988826`
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.
nickName deprecated	string	The nickname for the payment method that the customers gives, if applicable.
banned deprecated	boolean	If the payment method has been banned
active deprecated	boolean	Whether the payment method is active for use by this account

•

Removal: Used for marking a saved payment method as removed from the account.

Show definition

Name		Type	Description	Example
paymentMethodId required		string	A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.	`"pm-abc123"`
active required		boolean	False to indicate the payment method has been deactivated. Only: `false`.	`false`

device

optional

object

The device used by the customer to trigger this update.

Show definition

Name Type Description Example

deviceId

required

string

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

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

ipAddress

important

string

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

"81.152.92.84"

language

optional

string

The ISO 639 code of your user's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

"en-US"

userAgent

important

string

The browser user-agent string, if the device represents a web browser - window.navigator.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

important

string

"Pixel XL"

important

string

The operating system that the device is running.

"android"

type

optional

string

The type of device.

One of: computer, phone, or tablet.

"phone"

manufacturer

optional

string

The maker of the device.

"google"

location

optional

object

The geolocated position of the device.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`
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.
geohash deprecated	string	The geohash of the location.

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.

browser

deprecated

string

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

javascriptEnabled

deprecated

boolean

Whether Javascript is enabled on the web browser.

cookiesEnabled

deprecated

boolean

Whether cookies are enabled on the web browser.

screenResolution

deprecated

string

The resolution of the screen on the device in the format XxY

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/checkout HTTP/1.1
Authorization: token ...
Content-Type: application/json

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

… and completed their order successfully:

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

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

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

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

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

POST /v2/pretransaction

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

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

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

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "orderId": "abcde12345-ZXY",
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "eWallet": "applepay",
    "nameOnCard": "John Smith",
    "billingAddress": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826,
    "countryIssued": "GBR"
  },
  "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,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "type": "auth_capture",
    "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": "pass",
      "postalCode": "unchecked"
    },
    "cvvResultCode": "pass",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen"
  }
}

Name Type Description Example

timestamp

required

integer

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

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

1512828988826

orderId

required

string

A unique identifier for this order.

"abcde12345-ZXY"

transaction

required

object

A transaction is an attempt to charge a payment method to pay or be refunded for an order. You can think of it as the data included in your request from your application to a payment gateway. One order could have many transactions associated with it: e.g. pay part of balance with a card, pay part of balance with a voucher.

Hide definition

Name Type Description Example

transactionId

important

string

A unique identifier for the transaction.

"123-abc-XYZ"

time

important

integer

The time that the transaction is being attempted.

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

1480340580291

amount

important

integer

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

1000

currency

optional

string

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

Pattern: ^[a-zA-Z]{3}$

"GBP"

type

important

string

The type of transaction interacting with the payment method.

auth: An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
capture: A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
auth_capture: A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
refund: A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refund transaction payment methods.
void: A void transaction is the explicit discarding of authorization of funds.
use, redeem: Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.

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

"auth_capture"

gateway

important

string

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

"braintree"

3ds

optional

object

Details on how 3D Secure (3DS) was used to authenticate the transaction.

Show definition

Name	Type	Description	Example
attempted optional	boolean	Set to `true` if the 3D Secure authentication process was initiated for the transaction. The 3DS process is considered initiated when a check is performed to confirm issuer and cardholder enrolment, before asking for a challenge to be performed. This is set to `false` if the 3DS process was not initiated and the transaction proceeded to authorisation.	`true`
challenged optional	boolean	Set to `true` if a step-up authentication was initiated, for example, the user was asked to enter a password or use a form of biometric authentication. If `attempted` is set to `false`, then `challenged` should be omitted. If `attempted` is set to `true`, and a challenge was not presented to the user, then this field should be set to `false`. In 3DS2, if a user achieves a frictionless authentication this should also be set to `false`.	`true`
success optional	boolean	Set to `true` if the user was successfully authenticated using 3D Secure (either through frictionless authentication or a challenge) and the 3DS process was completed successfully. This field should be set to `false` if the user was unable to authenticate themselves during the challenge process, if an error occured, or frictionless authentication was not successful. This field should be omitted if `attempted` is set to `false`.	`true`
startTime optional	integer	The time at which the user was directed to 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064910`
endTime optional	integer	The time at which the user returned from 3DS. A unix timestamp preferably as an integer count of milliseconds since `1970-01-01T00:00` UTC (nanoseconds are also accepted).	`1479231064919`
timedOut optional	boolean	Whether the user is believed to have abandoned 3DS.	`false`
version optional	string	The version of 3DS which was used to authenticate the user. Either `1.0.2` or `2.1.0`	`"1.0.2"`
liabilityShifted optional	boolean	Whether the liability of the transaction resulting in a chargeback has moved from the merchant to the card issuer. (See Liability Shifted Chargebacks.)	`true`
authenticationValue optional	string	A cryptographic value generated by the ACS to be used by the acquirer to validate the integrity of the authentication result. This should be a 28 character, base64 encoded string. For VISA transactions this is the CAVV (Cardholder Authentication Verification Value). For Mastercard transactions this is the AAV (Accountholder Authentication Value). For American Express transactions this is the AEVV (American Express Verification Value).	`"MDEyMzQ1Njc4OTAxMjM0NTY3ODk="`
eci optional	string	The Electronic Commerce Indicator (ECI) value returned by the issuer after authentication was attempted.	`"5"`
transStatus optional	string	The Transaction Status (transStatus) value received in the final authentication message. The final message type (PaRes, ARes, CRes) will vary depending on the version of 3DS and whether the user was challenged.	`"Y"`
transStatusReason optional	string	Provides information on why the transStatus field has the specified value. Will only be provided by the issuer when the transStatus value is N, U or R. (3DS 2 only)	`"01"`
messageType optional	string	Identifies the type of message from which the transStatus value was received. (3DS 2 only)	`"ARes"`
iReqCode optional	string	If the transStatus value is U the accompanying invalid request code (iReqCode) should be provided to further explain the reason authentication could not be performed. (3DS 1 only)	`"55"`

mcc

optional

string

The Merchant Category 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"

acquirerBin

optional

string

The BIN (Bank Identification Number) of the acquirer.

"123456"

acquirerCountryCode

optional

string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"

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.

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.

credit

deprecated

integer

Deprected in favour of amount. The credit amount of the transaction in the lowest denomination of the currency.

eventType

optional

string

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

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 eventually be sent in conjunction with a real customer ID to migrate the data into the full customer account.

"abc-123-XYZ"

paymentMethodId

optional

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

paymentMethod

optional

object

One of the following:

•

card: A credit or debit card.

Show definition

Name Type Description Example

methodType

required

string

Vault card payment method indicator.

One of: card, creditcard, or debitcard.

"card"

paymentMethodId

required

string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"

scheme

optional

string

The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the cardBin, which should be preferred.

"visa"

instrumentId

important

string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

"fp_abc123"

pan

pci, optional

string

4111111111111111

cardBin

important

string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"

cardLastFour

important

string

The last four digits of the card number/PAN.

"0001"

issuer

optional

string

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard

optional

boolean

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued

optional

string

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

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

expiryMonth

important

integer

The expiry month of the card.

7

expiryYear

important

integer

The expiry year of the card.

2020

eWallet

deprecated

string

The e-Wallet to which the customer associated the card.

One of: applepay, googlepay, samsungpay, amazonpay, or visacheckout.

"applepay"

nameOnCard

important

string

The cardholder name.

"John Smith"

billingAddress

important

object

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

Name	Type	Description	Example
country important	string	A ISO 3166-1 Alpha 3 or Alpha 2 country code.	`"GBR"`
postalCode important	string	The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.	`"E1 1AA"`
latitude important	number	The latitude of the location.	`51.503252`
longitude important	number	The longitude of the location.	`-0.127899`
addresseeName optional	string	The name of the person that will accept delivery of goods to this address.	`"John Smith"`
street1 optional	string	The street address of the location.	`"123 fake st."`
street2 optional	string	The street address of the location.	`"floor 4, flat 48"`
neighbourhood optional	string	The neighbourhood of the location.	`"Hackney"`
zone optional	string	The zone of the location.	`"1"`
city optional	string	The city/village/town	`"London"`
region optional	string	The state/county of the location.	`"California"`
poBoxNumber optional	string	The PO box number related to the location.	`"1234"`