Core V2 API Reference

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

There are 3 key parts to a Ravelin integration:

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

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

Connection

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

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

Event Metadata

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

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

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

The simplest, most reliable way to integrate Ravelin into your checkout flow is using our /v2/checkout endpoint before charging a card, followed by /v2/transaction to indicate success. A single /v2/checkout submission contains all customer, order, payment method and transaction information for a single payment attempt, and should be sent to Ravelin at the exact moment your customer attempts to complete their purchase.

Having access to all of this information at once is not always possible in some systems, so we also support sending these entities individually using our other endpoints, but use of the checkout endpoint decreases the likelihood of pesky race-conditions and of overlooking parts of the payment journey.

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "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"
    }
  },
  "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",
    "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
  },
  "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",
      "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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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

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/chargeback

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

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

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

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

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

{
  "timestamp": 1512828988826,
  "chargeback": {
    "chargebackId": "abc-123-XYZ",
    "gateway": "braintree",
    "gatewayReference": "abc-123-XYZ",
    "transactionId": "abc-123-XYZ",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "reason": "fraud",
    "status": "LOST",
    "liabilityShifted": true,
    "nonFraud": false
  }
}
Name Type Description Example
timestamp
required
 integer

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

A unix timestamp as an integer count of seconds, 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

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

 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.
 "LOST"
liabilityShifted
optional
 boolean

Whether liability for this chargeback was shifted to a third-party, such as your PSP or gateway. (See liability-shifted chargebacks.)

 true
nonFraud
optional
 boolean

Whether this chargeback was claimed for reasons other than fraud. If this chargeback was not filed for reasons of fraud (e.g. goods not as described) then be sure to set a reason. (See non-fraudulent chargebacks.)

 false
custom
optional
 object

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

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

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

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

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

POST /v2/customer

When a customer registers, or changes their profile, send their info to the customer endpoint. Creating a new customer and updating an existing customer is the same operation: a POST to this endpoint is an upsert. Customers are your users, the central entity that all Ravelin fraud detection revolves around.

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM",
    "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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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

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

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

 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"

POST /v2/order

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

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "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",
    "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
  },
  "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 as an integer count of seconds, 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 seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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

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

 1512828988826
eventType
optional
 string

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

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

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

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

 "abc-123-XYZ"
device
optional
 object

The device used by the customer to trigger this update.

Show definition
deviceId
optional
 string

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

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

POST /v2/paymentmethod

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

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

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

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "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
  },
  "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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
paymentMethod
required

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

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
eventType
optional
 string

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

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

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

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

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

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

… and completed their order successfully:

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

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

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

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

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

POST /v2/pretransaction

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

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

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

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

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

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

 1512828988826
orderId
required
 string

A unique identifier for this order.

 "abcde12345-ZXY"
transaction
required
 object

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

Hide definition
Name Type Description Example
transactionId
important
 string

A unique identifier for the transaction.

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
optional
 string

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

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

The type of transaction interacting with the payment method.

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

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

"auth_capture"
gateway
important
 string

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

 "braintree"
3ds
optional
 object

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

Show definition
mcc
optional
 string

The Merchant Category Code associated with the transaction.

 "0742"
mid
optional
 string

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

 "mid-1"
acquirerId
optional
 string

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

 "adyen"
acquirerBin
optional
 string

The BIN (Bank Identification Number) of the acquirer.

 "123456"
acquirerCountryCode
optional
 string

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

 "GBR"
custom
optional
 object

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

Whether this transaction is associated with a chargeback.
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.
credit
deprecated
 integer

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

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

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

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

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

 "abc-123-XYZ"
paymentMethodId
optional
 string

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

 "pm-abc123"
paymentMethod
optional
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
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/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",
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "eWallet": "applepay",
    "nameOnCard": "John Smith",
    "billingAddress": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826,
    "countryIssued": "GBR"
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "type": "auth_capture",
    "gateway": "braintree",
    "gatewayReference": "123-abc-XYZ",
    "success": true,
    "3ds": {
      "attempted": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false
    },
    "declineCode": "1234",
    "authCode": "1234",
    "avsResultCode": {
      "street": "pass",
      "postalCode": "unchecked"
    },
    "cvvResultCode": "pass",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen"
  }
}
Name Type Description Example
timestamp
required
 integer

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

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

 1512828988826
orderId
required
 string

A unique identifier for this order.

 "abcde12345-ZXY"
transaction
required
 object

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

Hide definition
Name Type Description Example
transactionId
important
 string

A unique identifier for the transaction.

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
optional
 string

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

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

The type of transaction interacting with the payment method.

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

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

"auth_capture"
gateway
important
 string

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

 "braintree"
gatewayReference
important
 string

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

 "123-abc-XYZ"
success
important
 boolean

Whether the transaction successfully completed with no error.

 true
3ds
optional
 object

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

Show definition
declineCode
important
 string

the decline code from the payment gateway, if applicable.

 "1234"
authCode
optional
 string

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

 "1234"
avsResultCode
optional

The result of AVS checks. You must have at least one of street or postal code.

One of the following:
 "fail"
• Show definition
•Type: string, example: "fail"
cvvResultCode
optional
 string

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

One of: M, N, U, I, A, E, pass, fail, unavailable, unchecked, 0, 1, 2, 4, 8, P, S, 3, 5, 6, missing, issuer_not_certified, issuer_not_signed_up, not_checked, B, C, D, F, G, H, J, K, L, O, Q, R, T, V, W, X, Y, or Z.

"pass"
mcc
optional
 string

The Merchant Category Code associated with the transaction.

 "0742"
mid
optional
 string

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

 "mid-1"
acquirerId
optional
 string

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

 "adyen"
acquirerBin
optional
 string

The BIN (Bank Identification Number) of the acquirer.

 "123456"
acquirerCountryCode
optional
 string

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

 "GBR"
custom
optional
 object

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

Whether this transaction is associated with a chargeback.
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.
credit
deprecated
 integer

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

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

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

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

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

 "abc-123-XYZ"
paymentMethodId
optional
 string

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId. Prefer {"paymentMethod": {"methodType": "cash"}} instead of paymentMethodId for cash payments.

 "pm-abc123"
paymentMethod
optional
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
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"

Refund Transaction Payment Methods

When sending a refund transaction it can be useful to refer back to the payment method by the transaction which originally debited the card. For example, if a customer has successfully gone through the fraud check:

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

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

… and completed their order successfully:

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

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

We can then create a refund transaction without then knowing the payment method by instead knowing that the refund was for transaction tx-123:

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

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

POST /v2/login

If previous events for this customer were sent as anonymous events (with a tempCustomerId instead of a customerId), set the tempCustomerId field here to tie those together.

Optionally, if there is device information available, send Ravelin information about the device the customer is using in this event.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
customerId
required
 string

The ID of the customer who has successfully logged in.

 "abc-123-ZYZ"
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-_]*$
tempCustomerId
optional
 string

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

 "abc-123-XYZ"
device
optional
 object

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

Show definition
deviceId
optional
 string

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

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

POST /v2/paymentmethod/voucher

If part of an order is being paid for through use of a voucher or of credit associated to a user’s account, you can communicate that to Ravelin with a paymentmethod/voucher event. For these redemptions, you can either provide the voucher details alongside its redemption details, or you can specify a previously registered voucher via the paymentMethodId.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "voucherRedemption": {
    "paymentMethodId": "VOUCH-89-abc-123-ZYZ",
    "voucherCode": "VOUCH-89",
    "redemptionTime": 1512828988826,
    "success": true,
    "value": 10000,
    "currency": "GBP",
    "voucherType": "GENERAL"
  }
}
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 seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

 1512828988826
voucherRedemption
required
 object

Represents the redemption of the voucher

Hide definition
Name Type Description Example
paymentMethodId
required
 string

A unique identifier for the voucher usage. A transactionId for vouchers.

 "VOUCH-89-abc-123-ZYZ"
voucherCode
required
 string

The string customers actually see in their app.

 "VOUCH-89"
value
required
 integer

The value that the voucher can be exchanged for, in the currency's basic units.

 10000
redemptionTime
required
 integer

The time that the customer is utilising the voucher.

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

 1512828988826
success
required
 boolean

Whether the voucher has successfully been used by the customer.

 true
currency
optional
 string

The currency of the value of this voucher, as an ISO 4217 currency code.

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

The time the after which the voucher can no longer be redeemed.

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

The type of the voucher. If REFERRAL, also set the referredId so Ravelin will create a network of who has invited who.

One of: REFERRAL, REACTIVATION, or GENERAL.

"GENERAL"
referrerId
optional
 string

The customerId of the customer who created this voucher.
referralValue
optional
 integer

The amount the referring customer of the voucher gets when the voucher is used, in the currency's basic units.
failureReason
optional
 string

Optional reason why the attempt was not successful.

One of: EXPIRED, NOT_NEW_CUSTOMER, ALREADY_USED, ABUSER, SYSTEM_FAILURE, or MAX_ALLOWED_TIMES.

failureSource
optional
 string

the source of why the voucher failed

One of: RAVELIN, or CLIENT.

custom
optional
 object

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

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

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

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

 "abc-123-ZYZ"
customer
optional
 object Show definition

Markets

The market for a customer can be specified using the market, country & marketCity on customer and order events. If any of these three fields is non-empty on the customer, then the effective market for the customer is specified by the values on the customer. If all three fields are empty on the customer, then the effective market for the customer is specified by the fields on their latest order. The inability to ‘forget’ a market on a customer, regardless if any order market information is sent, has led to confusion in the past: thus we have deprecated them. We recommend you set values for these fields only on order events.

The effective market for a customer is used in reporting, risk thresholds, for model features, and for segmenting customers in the dashboard.

We recommend you use market, country & marketCity in a hierarchical manner, with market specifying the region (e.g. europe, emea, apac, etc).

Anonymous activity

Events can occur before a customer ID is known. For example: adding items to a shopping cart, and only being shown a “login or register now” form at check-out time; the cart events will not have an associated customerId.

For these events, there is the tempCustomerId field: it can occur at the top-level of most events which accept a customerId. This field should contain a session ID (or otherwise consistent value that will be used to later tie the events to a real customer, at log in time).

When a customer logs in (or registers), send a “log in event” (see above) to tie all previous tempCustomerId events to a real customer.

Except for the log in event, the tempCustomerId and customerId fields are mutually exclusive.

Scoring

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "123456789",
        "action": "PREVENT",
        "score": 77,
        "source": "RAVELIN",
        "scoreId": "2bf39d-d1299-31",
        "comment": "",
        "warnings": [{
            "class": "order-absent-currency",
            "help": "https://developer.ravelin.com/apis/warnings/#order-absent-currency",
            "msg": "Order \"example-order-1\" does not have a currency."
        }]
    }
}

Using the information supplied to Ravelin through the event endpoints, individual customers are categorized in one of three buckets:

  • ALLOW
  • REVIEW
  • PREVENT

This information is sent:

In both cases, the score payload is a JSON object with the same schema:

Parameter Type Description
customerId string Identifier for this customer, as supplied by the client
action string Action to take for this customer, according to Ravelin. One of ALLOW, REVIEW, PREVENT
score int Ravelin score for this customer as an integer. Debugging purposes only
source string Source of the score, e.g. RAVELIN or MANUAL_REVIEW
scoreId string Unique identifier for this score
comment string In the case of manual review, this is the comment left by the reviewer on this particular review action. E.g.: "Definitely not a fraudster, I know him personally", or "I know this person from another account, infamous fraudster"
warnings array of warnings Ravelin can return warnings on API responses when malformed or absent data may negative impact fraud-detection, but where we would rather return a best-effort score instead of out-right rejecting the API request.

Requesting a score

Events sent to Ravelin using POST requests get an empty response body by default. The information is stored in our system and no further action is taken during the request.

To force an immediate rescoring based on the information received up to and including an event: add the ?score=true query parameter. For example, the /v2/order endpoint becomes:

POST /v2/order?score=true

This will do two things:

  1. Process the event payload (as usual, see events)
  2. Force immediate recalculation of the score and return it

The score will be calculated based on the information in this event, and in all events previously received and met with a 200 OK status.

Suggested handling

The ?score=true query parameter is available on every event endpoint. Specify it when you want to make a decision during an order flow about where to go, based on the fraud score: allow regular check-out, or send down an extra validation path?

The most important field in the payload is action:

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

Other fields are provided for analytic and debugging purposes.

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

Callbacks

[DEPRECATION NOTICE] Callbacks are deprecated. You can still review our old callbacks documentation if you use them.

Label

The Label API allows you to change the status of a customer. This can be used to tie your own customer management tools into Ravelin.

Sending this label is the same as pressing the Genuine or Fraudster button in the Ravelin Dashboard.

POST /v2/label/customer

{
    "customerId": "customer1",
    "label": "GENUINE",
    "comment": "This customer called up and we have determined he is not a fraudster",
    "reviewer": {
      "name": "Bilbo Baggins",
      "email": "bilbo.b@shiremail.com"
    }
}

You can also query the labels that have been set since a point in time.

GET /v2/label/customer?after=2019-08-05T11:26:00Z

{
    "meta": {
        "next": "https://api.ravelin.com/v2/label/customer?scroll_id=shjfhsjdfhasdjkfwuibas"
    },
    "reviews": [
        {
            "customerId": "customer1",
            "label": "GENUINE",
            "reviewer": {
                "name": "Bilbo Baggins",
                "email": "bilbo.b@shiremail.com"
            },
            "timestamp": "2019-08-05T11:27:15Z"
        },
        {
            "customerId": "customer77",
            "label": "FRAUDSTER",
            "reviewer": {
                "name": "Frodo Baggins",
                "email": "frodo.b@shiremail.com"
            },
            "timestamp": "2019-08-06T14:21:15Z"
        }
    ]
}

Note that the comment field is not available in the GET response. To retrieve all results you must follow the URL supplied in meta.next on each response until you receive a response with no reviews. You must send these follow-up requests within 1 minute of the previous response.

This is an optional API integration. You may manage these labels completely within the Ravelin Dashboard. This is simply a helper API so you can integrate labelling in your own tools.

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

Reviewer

The reviewer is the person who is doing the review. Their details will appear in the audit log on the dashboard so you are able to see who did this review and why.

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

Tag

The Tags API allows you to change the tags attached to a customer. This can be used to tie your own customer management tools into Ravelin. Calling this API is the same as setting a tag in the Ravelin Dashboard.

POST /v2/tag/customer

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

{
    "timestamp": 1429029735,

    "customerId": "61283761287361",
    "tagNames": ["staff", "vip"]
}

Example response:

{
    "tagNames": ["staff", "vip", "highroller"],
    "label":    "GENUINE"
}

Attaching a tag to a customer is done by posting to this endpoint with the body filled with customerId and an array of tagNames. This will attach the tag and respond with the full list of attached tags and the label for that customer.

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

GET /v2/tag/customer/:customerId

This returns all the tags for a specific customer as well as the label for the customer. This returns the same body as the POST tag endpoint.

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

To remove a tag, make a DELETE http request on the tag customer endpoint. This will remove the tag from the customer. The tagName field may be a single tag or, to remove multiple tags, a comma separated list of tags. This returns the same body as the POST tag endpoint.

Backfill

Backfill is the process of sending your historical data to Ravelin. We will use the backfill data to train a model which uniquely identifies the fraud you are experiencing. This model will then be used to evaluate your live data.

However, it is only worth doing backfill if your historical data is representative of your live data. If not, the model which is trained won’t accurately detect fraud in your live data.

If your backfill data is not representative of your live data, or if you don’t have a enough backfill data, and you are receiving enough enough traffic through your platform, it may be preferable to just collect live data and use that to train a model instead. Please speak to our integrations team about whether this is an option for you.

If you choose to proceed with backfill we recommend that you start sending us live data before performing the backfill, but don’t request scoring. This means you will avoid a gap in data during the period between completing your backfill and when we finish preparing your fraud model.

If performing backfill these are the steps you should follow:

  1. Start sending us all live events with scoring set to score=false.
  2. Perform the backfill and wait for us to confirm your fraud model has been generated.
  3. Switch your live events to use score=true for those you wish to score.

Requesting a score only works for known customers, which is why we recommend you complete backfill before enabling scoring.

Backfill Endpoints

In order to perform the backfill you should send data to our backfill API endpoints. Every one of our primary API endpoints has an equivalent backfill endpoint. These endpoints receive data in exactly the same format as our primary API endpoints. Fields which are required by the primary API are also required by the backfill API. For details about the format see the documentation for each of the primary API endpoints.

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

Timestamps on Backfill Data

Timestamps should be provided for all backfill data. If a timestamp isn’t available for an entity, a timestamp from a related entity can be used instead. For example, if you don’t have the registration time for a customer the time of their first order could be used instead. Regardless of their source, make sure all timestamps for backfill data are in the past so that they don’t conflict with live events.

Rate Limiting During Backfill

The rate limits for the backfill endpoints are much higher than the rate limits for the primary endpoints so you needn’t worry about being rate limited during backfill.

Warnings

Ravelin will avoid rejecting requests with bad data in some cases, with the understanding that our best effort is usually still preferable to nothing at all. Our machine-learning scoring may be impacted by a missing order price, but we can still see when a credit card has sent you chargebacks before.

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

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

Errors

Ravelin uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided request and codes in the 5xx range indicate an error with Ravelin’s system.

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

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