Core V2 API Reference

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

There are 3 key parts to a Ravelin integration:

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

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

Events

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

Event Metadata

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

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

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

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

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

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

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

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

 1512828988826
eventType
optional
 string

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

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

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

 "abc-123-ZYZ"
customer
important
 object

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

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

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

One of the following:
•

card: A credit or debit card.

Show definition
•

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

Show definition
•

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

Show definition
•

bankaccount: Bank Accounts.

Show definition
•

paypal: PayPal payments.

Show definition
•

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

Show definition
•

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

Show definition
•

wallet: A digital wallet payment method.

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
•

directdebit: Direct Debits. - deprecated.

Show definition
•

banktransfer: Bank Transfers. - deprecated.

Show definition
•

Others - deprecated.

Show definition
•

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

Show definition
paymentMethods
important
 array

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

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

 "pm-abc123"
transaction
important
 object

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

Show definition
transactions
important
 array

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

Show definition
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/dispute

A dispute occurs when a cardholder contacts the issuer of their payment method to challenge the legitimacy of a payment. Since disputed payments and chargebacks are important indicators of fraudulent behaviour, sending these events to Ravelin is an essential part of every integration. See our disputes guide to learn more about disputes and chargebacks.

In order to learn from previous cases of fraud, we must be able to associate a dispute with the original transaction. Most payment gateways will provide an identifier for the original transaction with every dispute: - If the transaction identifier is generated by the payment gateway, use the gatewayReference field to reference the original transaction. - If the transaction identifier is provided by the merchant, use transactionId instead.

In either case, the identifier must match that of a previously sent transaction.

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

If we do not find a transaction with a matching transactionId, gatewayReference or orderId we will ignore the dispute.

{
  "timestamp": 1512828988826,
  "dispute": {
    "disputeId": "abc-123-XYZ",
    "gateway": "braintree",
    "gatewayReference": "abc-123-XYZ",
    "transactionId": "abc-123-XYZ",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "reason": "fraud",
    "stage": "CHARGEBACK",
    "outcome": "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
dispute
required
 object

A dispute occurs when a cardholder makes a claim to the issuer of their payment method to challenge the legitimacy of a payment, initiating a chargeback for card payment methods. See our disputes guide to learn more about chargebacks and the dispute process.

Hide definition
Name Type Description Example
disputeId
required
 string

Unique identifier for the dispute.

 "abc-123-XYZ"
stage
required
 string

Stage of the dispute. A dispute with the stage EARLY_FRAUD_WARNING or REQUEST_FOR_INFORMATION is not considered a chargeback for reporting purposes. See our disputes guide to learn more.

One of: EARLY_FRAUD_WARNING, REQUEST_FOR_INFORMATION, NOTIFICATION_OF_CHARGEBACK, CHARGEBACK, SECOND_CHARGEBACK, CHARGEBACK_REVERSED, PREARBITRATION, or ARBITRATION.

"CHARGEBACK"
gateway
important
 string

Name of the payment gateway that processed the disputed transaction.

 "braintree"
gatewayReference
important
 string

Payment gateway's identifier for the disputed transaction. Must match the gateway reference of the original transaction. Not required if you provide transactionId.

 "abc-123-XYZ"
transactionId
important
 string

Identifier for the disputed transaction. Must match the transaction identifier of the original transaction. Not required if you provide gatewayReference.

 "abc-123-XYZ"
amount
important
 integer

Disputed amount, in the currency's basic units, including any additional dispute fees or penalties.

 15212
currency
important
 string

Currency of the dispute amount, as an ISO 4217 currency code.

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

Time at which the dispute was created, used for 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

Reason given by the cardholder for disputing the transaction.

 "fraud"
outcome
optional
 string

Outcome of the dispute. Use ACCEPTED for disputes you have accepted and decided not to defend, WON for disputes you have successfully defended, EXPIRED for disputes that have timed out and LOST for disputes ruled in favour of the cardholder. Omit outcome if the dispute is still open.

One of: ACCEPTED, WON, LOST, or EXPIRED.

"LOST"
liabilityShifted
optional
 boolean

Whether liability for this dispute was shifted to a third-party, such as your payment gateway. (See liability-shifted disputes.)

 true
nonFraud
optional
 boolean

Whether the cardholder disputed the payment for reasons other than fraud. Make sure to set a reason if this is the case - see our disputes guide to learn more.

 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 dispute 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 dispute originated from. Ravelin will look this up from the referenced order or transaction.

POST /v2/chargeback

[DEPRECATION NOTICE] We have deprecated the /v2/chargeback endpoint. Please use /v2/dispute instead. You can still review our old chargeback documentation.

POST /v2/customer

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

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

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

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

 1512828988826
customer
required
 object

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

Hide definition
Name Type Description Example
customerId
required
 string

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

 "abc-123-ZYZ"
registrationTime
important
 integer

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

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

 1512828988826
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.
tags
optional
 object

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

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

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

 1512828988826
order
required
 object

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

Hide definition
Name Type Description Example
orderId
required
 string

A unique identifier for this order.

 "abcde12345-ZXY"
creationTime
important
 integer

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

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

 1512828988826
app
important
 object

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

Show definition
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
suppliers
optional
 array

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

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

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

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

 1512828988826
eventType
optional
 string

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

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

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

 "abc-123-ZYZ"
tempCustomerId
optional
 string

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

 "abc-123-XYZ"
paymentMethod
optional
 object

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

One of the following:
•

card: A credit or debit card.

Show definition
•

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

Show definition
•

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

Show definition
•

bankaccount: Bank Accounts.

Show definition
•

paypal: PayPal payments.

Show definition
•

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

Show definition
•

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

Show definition
•

wallet: A digital wallet payment method.

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
•

directdebit: Direct Debits. - deprecated.

Show definition
•

banktransfer: Bank Transfers. - deprecated.

Show definition
•

Others - deprecated.

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"

Saving Payment Methods after Checkout

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

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

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

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

… and completed their order successfully:

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

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

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

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

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

POST /v2/pretransaction

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

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

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

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

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

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

 1512828988826
orderId
required
 string

A unique identifier for this order.

 "abcde12345-ZXY"
transaction
required
 object

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

Hide definition
Name Type Description Example
transactionId
important
 string

A unique identifier for the transaction.

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

 "123-abc-XYZ"
time
important
 integer

The time that the transaction is being attempted.

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

 1480340580291
amount
important
 integer

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

 1000
currency
optional
 string

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

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

The type of transaction interacting with the payment method.

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

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

"auth_capture"
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
 object
One of the following:
•

card: A credit or debit card.

Show definition