Travel API Reference

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

There are 3 key parts to a Ravelin integration:

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

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

Connection

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

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

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

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

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

Make sure to replace sk_live_XXXXXXXX with your API key.

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

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

Events

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

We strive to represent everything relevant to the travel domain but if you think you have domain data that is relevant to fraud but not represented in our models then you may send this data via the custom field. You will find this field on all of our properties. Data in the custom field is not initially mapped to our internal properties, but we do periodically check if there are any fraud signals that we can use to improve the scoring. If so, we retroactively extract the data from all previous events that specified it, without requiring you to send it again.

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

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

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

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
customerId
optional
string

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

"abc-123-ZYZ"
customer
optional
object

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

Show definition
order
optional
object

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

Show definition
transaction
optional
object

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

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

One of the following:
Show definition
Show definition
Show definition
Show definition
device
optional
object

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

Show definition
deviceId
optional
string

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

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

POST /v2/travel/chargeback

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

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

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

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
chargeback
required
object

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

Hide definition
Name Type Description Example
chargebackId
required
string

A unique identifier for the chargeback.

"abc-123-XYZ"
gateway
important
string

The gateway that the originating transaction was processed by.

"braintree"
gatewayReference
important
string

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

"abc-123-XYZ"
transactionId
important
string

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

"abc-123-XYZ"
amount
important
integer

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

15212
currency
important
string

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

Pattern: ^[a-zA-Z]{3}$
"GBP"
disputeTime
important
integer

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

1479302798
reason
optional
string

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

"fraud"
status
optional
string

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

"lost"
liabilityShifted
optional
boolean

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

true
nonFraud
optional
boolean

Whether this chargeback was claimed for reasons other than fraud.

false
custom
optional
object

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

orderId
optional
string

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

customerId
deprecated
string

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

"abc-123-ZYZ"

Valid chargeback status strings:

status Description
OPEN The chargeback, retrieval, or pre-arb has been issued and no action has been taken yet.
ACCEPTED You have opted out of providing evidence for the chargeback or pre-arb.
DISPUTED You have submitted evidence against the claim and are waiting for the decision from the bank.
WON The bank has ruled in your favor, and the funds should return to your bank account within 2-3 business days.
LOST The bank has not ruled in your favor, and the funds will remain with the cardholder.
EXPIRED The reply-by date to submit evidence has passed and you have forfeited your right to dispute the case.

POST /v2/travel/customer

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

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

All fields except customerId are optional, but the more information, the better. If you send the customerId field it will be considered an update. Therefore a new property will overwrite any previously received property for this customer. We keep all mutations so we will know the history of a customer but we use the most up-to-date data to build the current customer profile.

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
customer
required
object

The customer registering or updating their account profile.

Hide definition
Name Type Description Example
customerId
required
string

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

"abc-123-ZYZ"
registrationTime
important
integer

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

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

1479302798391
email
important
string

The email address of the customer.

"jsmith123@example.com"
emailVerifiedTime
optional
integer

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

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

14793027980391
name
important
string

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

"John Smith"
familyName
important
string

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

"Smith"
givenName
important
string

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

"John"
telephone
important
string

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

"+16045555555"
telephoneVerifiedTime
optional
integer

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

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

1479302798401
telephoneCountry
optional
string

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

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

Pattern: ^[A-Z]{2,3}$
"GBR"
passwordBcrypted
optional
string

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

passwordHashed
optional
string

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

password
optional
string

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

passwordChanged
optional
boolean

Set to true on events where the password has been changed, false or omit otherwise

location
optional
object Show definition
custom
optional
object

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

banned
deprecated
boolean

Whether the customer is banned in your systems.

username
deprecated
string

The username the customer would log in with.

gender
deprecated
string

The gender of the customer.

market
deprecated
string

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

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

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

Pattern: ^[A-Z]{2,3}$
marketCity
deprecated
string

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

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

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

device
optional
object

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

Show definition
deviceId
optional
string

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

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

Location

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

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

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

POST /v2/travel/order

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

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
order
required
object

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

Hide definition
Name Type Description Example
orderId
required
string

A unique identifier for this order.

"abcde12345-ZXY"
creationTime
important
integer

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

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

1479122053
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
status
important

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

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

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

Show definition

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

Show definition

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

Show definition

Cancelled: The order has been cancelled.

Show definition

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

Show definition

Refunded: The order is has been refunded.

Show definition
price
important
integer

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

10000
currency
important
string

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

Pattern: ^[a-zA-Z]{3}$
"GBP"
country
important
string

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

Pattern: ^[A-Z]{2,3}$
"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"
generalItems
important
array

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

Show definition
hotelRooms
important
array

The hotel rooms booked in this order.

Show definition
tickets
important
array

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

Show definition
passengers
important
array

The passengers who are embarking on this trip.

Show definition
email
optional
string

Contact e-mail for this order

"jsmith@example.com"
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

Pattern: ^[A-Z]{2,3}$
"GBR"
terminated
optional
boolean false
sellerId
optional
string

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

"abcde12345-ZXY"
customerLocation
optional
object

The location of the customer when ordering, if available.

Show definition
custom
optional
object

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

customerId
optional
string

The ID of the customer whose order is being updated.

"abc-123-ZYZ"
tempCustomerId
optional
string

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

"abc-123-XYZ"
device
optional
object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
string

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

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

Order Status

Order statuses specify the current status of the order.

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

Order Statuses

Valid reasons for different order status stages:

stage Valid reason values
pending None – omit reason field.
accepted None – omit reason field.
failed payment_declined, seller_rejected, system_error
cancelled buyer, seller, merchant, ravelin
fulfilled None – omit reason field.
refunded returned, complaint

Item

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

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

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

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

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

POST /v2/travel/paymentmethod

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
payment
required

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

Hide definition
Name Type Description Example
paymentMethodId
optional
string

The ID of an existing payment method.

"abc-123-XYZ"
card
optional
object

The credit or debit card this payment method represents.

Show definition
paypal
optional
object

The PayPal account this payment method represents.

Show definition
voucher
optional
object

The voucher this payment method represents.

Show definition
cash
optional
boolean

Just cash.

true
paymentMethodCipher
optional
object

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

Show definition
fromTransaction
optional
object

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

One of the following:
Show definition
banktransfer
optional
object

Details of payment via bank transfer

One of the following:
Show definition
directdebit
optional
object

Details of payment by direct debit

One of the following:
Show definition
other
optional
object

Another instrument of payment this payment method represents.

Show definition
customerId
optional
string

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

"abc-123-ZYZ"
tempCustomerId
optional
string

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

"abc-123-XYZ"
device
optional
object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
string

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

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

Saving Payment Methods after Checkout

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

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

POST /v2/travel/checkout?score=true HTTP/1.1
Content-Type: application/json

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

… and completed their order successfully:

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

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

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

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

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

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

POST /v2/travel/transaction/before-psp

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

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

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
orderId
required
string

A unique identifier for the order this transaction pertains to.

"abcde12345-ZXY"
transaction
required
object

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.

One of the following:
Hide 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1480340580291
amount
important
integer

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

1000
currency
important
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 interaction with the payment method.

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

"auth_capture"
payment
important
object

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

Show definition
gateway
important
string

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

"braintree"
3ds
important
object

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

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

Pattern: ^[A-Z]{2,3}$
"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.

email
deprecated
string

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

debit
deprecated
integer

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

credit
deprecated
integer

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

Show definition
Show definition
Show definition
customerId
optional
string

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

"abc-123-ZYZ"
tempCustomerId
optional
string

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

"abc-123-XYZ"
device
optional
object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
string

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

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

POST /v2/travel/transaction

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

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

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

The time at which this data 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 as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826
orderId
required
string

A unique identifier for the order this transaction pertains to.

"abcde12345-ZXY"
transaction
required
object

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

One of the following:
Hide definition
Name Type Description Example
currency
required
string

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

Pattern: ^[a-zA-Z]{3}$
"GBP"
transactionId
important
string

A unique identifier for the transaction.

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

"123-abc-XYZ"
time
important
integer

The time that the transaction is being attempted.

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

1480340580291
amount
important
integer

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

1000
type
important
string

The type of interaction with the payment method.

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

"auth_capture"
payment
important
object

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

Show definition