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": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "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,
    "customerLocation": {
      "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"
    },
    "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",
    "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
  },
  "paymentMethodId": "pm-abc123",
  "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,
      "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",
    "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
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"
order
important
 object

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

Show definition
paymentMethod
important
 object

The primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId.

One of the following:
•

card: A credit or debit card.

Show definition
•

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

Show definition
•

cash: The customer is paying in cash.

Show definition
•

banktransfer: Bank Transfers.

Show definition
•

directdebit: Direct Debits.

Show definition
•

paypal: PayPal payments.

Show definition
•

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
•

Others

Show definition
•

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

Show definition
paymentMethodId
important
 string

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

 "pm-abc123"
transaction
important
 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.

Show definition
voucherRedemption
optional
 object

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

Show definition
voucherRedemptions
optional
 array

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

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

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": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "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",
    "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
email
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.
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.
username
deprecated
 string

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

The gender of the customer.
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.
banned
deprecated
 boolean

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

The home country for this customer. Doesn't change when the customer is briefly abroad. See markets.
market
deprecated
 string

The logical region in which this customer exists. See markets.

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

The logical city in which this customer exists. See markets.

Pattern: ^[0-9a-z-]*$
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-_]*$
device
optional
 object

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

Show definition
deviceId
optional
 string

The ID of the device that 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",
  "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,
    "customerLocation": {
      "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"
    },
    "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",
    "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
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 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.

 "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"
to
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
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
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
note
optional
 string

Descriptive text relating to the contents or nature of the order being completed.
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

 "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
generalItems
deprecated
 array

Deprecated in favour of items.

Show definition