API Warnings

Ravelin APIs return warnings when we believe the action we recommend may be suffering from bad or missing data. Warnings have a class, e.g. customer-not-found, a help URL (this page), and description of why the warning has triggered:

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

{
    "timestamp": 1538150837183,
    "customerId": "eg-cust-a",
    "order": {
        "orderId": "eg-order-1",
        "price": 100
    },
    "paymentMethodId": "eg-card-a"
}

200 OK
Content-Type: application/json

{"data": {
    "warnings": [
        {
            "class": "customer-not-found",
            "help": "https://developer.ravelin.com/apis/warnings/#customer-not-found",
            "msg": "Customer \"eg-cust-a\" not found."
        },
        {
            "class": "order-absent-currency",
            "help": "https://developer.ravelin.com/apis/warnings/#order-absent-currency",
            "msg": "Order \"eg-order-1\" does not have a currency."
        }
    ],
    "more": "..."
}}

Handling Warnings

The class on warnings is safe to use programmatically, and suitable for adding to tags in your metrics system for monitoring how frequently you receive these warnings.

Do not throw exceptions when you receive warnings in your API responses. While important to count for regression monitoring and integration improvement, Ravelin’s recommendation action will be best-effort despite the warnings.

Missing Entities

When customer, order, payment method, and transaction data arrives in individual API calls to Ravelin, some data references (e.g. customerId or orderId) may not be resolvable if the request which transmitted the data does not make it to Ravelin, or if the request gets rejected because validation failed.

Bad entity references can be of high impact to Ravelin.

Using /v2/checkout or /v2/travel/checkout and sending full customer, order, payment method, and transaction data each time can mitigate the impact of lost-in-flight data, and minimises the opportunity for using inconsistent identifiers.

Customer Not Found — customer-not-found

No customer with the given customerId exists in Ravelin’s systems. Ravelin will be unable to utilise useful information associated with the customer (name, email, registration time) when scoring.

Order Not Found — order-not-found

No order with the given orderId exists in Ravelin’s systems. Ravelin will be unable to use information associated with the order (the price, the items bought) when scoring.

Transaction Not Found — transaction-not-found

No transaction with the given transactionId exists in Ravelin’s systems. Ravelin will be unable to utilise information associated with the transaction (whether it was successful or not, the amount associated) when scoring.

Payment Method Not Found — paymentmethod-not-found

No payment method with the given paymentMethodId exists in Ravelin’s systems. Ravelin will be unable to utilise information associated with the payment method (issuer, instrumentId, billing address etc) when scoring.

Customer Warnings

Absent Email — customer-absent-email

The customer does not have an email address. Ravelin will not be able to link the customer to other customers in the graph network, nor utilise useful signals contained in the email when scoring.

Absent Registration Time — customer-absent-reg-time

The customer does not have a registration time. Ravelin will be unable to understand how old the customer’s account is - a factor crucial in scoring. Most fraud tends to be committed by customers that have signed up very recently.

If your system supports guest checkout and there is no registration event at which to define a registration time, please use the current time. Ravelin will retain the earliest registration time as a kind of “first seen” time.

Order Warnings

Absent Price — order-absent-price

The order does not have a price. Price is a factor crucial in scoring: fraudsters tend to buy items that are more expensive than normal customers.

Absent Currency — order-absent-currency

The order does not have a currency. Ravelin will not be able to understand how much a monetary value represents in comparison to others.

Absent Status — order-absent-status

The order does not have a status. Ravelin cannot use the status of the order to discard orders that were cancelled that were not the customer’s fault - for example, if a restaurant rejected the order because they were too busy. This can lead to the customer receiving a higher score than they otherwise should have. If a status is never sent, it is impossible to understand whether the order was fulfilled or not - leading to confusion on the dashboard.

Absent Creation Time — order-absent-creation-time

The order does not have a creation time. Ravelin will be unable to understand when the order actually happened.

Transaction Warnings

Absent Type — transaction-absent-type

The transaction does not have a type. The type is very useful when understanding the flow of money between two parties. Ravelin will be unable to understand if it was responsible for blocking the transaction without the type.

Absent Currency — transaction-absent-currency

The transaction does not have a currency. Ravelin will not be able to understand how much a monetary value represents in comparison to others.

Absent Amount — transaction-absent-amount

The transaction has no amount. A transaction that exchanges no value is meaningless.

Absent Payment Method — transaction-absent-paymentmethod

The transaction has no reference to a payment method (either via a paymentMethodId, or by a complete paymentMethod entity sent alongside the transaction). Ravelin will be unable to use information about this payment method in scoring - including in any rules that look at the ‘current’ payment method.

Capture After Prevent — transaction-capture-after-prevent

A transaction was succesfully captured after Ravelin returned an action of PREVENT for the given customer. This indicates that the action returned is being ignored.

Capture Not Scored — transaction-capture-not-scored

A transaction was successfully captured, but Ravelin had never scored the given customer. Ravelin never had the chance to recommend an action for the provided customer.

Payment Method Warnings

Absent Registration Time — paymentmethod-absent-registration-time

The provided card does not have a registration time associated with it. Ravelin will not be able to understand how recently this card was added to the user account.

Absent BIN — paymentmethod-absent-card-bin

The provided card does not have a BIN associated with it. Ravelin will not be able to perform crucial BIN enrichment such as determining the issuer, issuing country and whether or not the card is pre-paid without this value.

Absent Last Four — paymentmethod-absent-card-last4

The provided card does not have a last4 associated with it. Ravelin will be less capable of determining whether or not this is a new card, or a previously registered card, in cases where an instrumentId is also not provided. It will also impede an analyst using the Ravelin dashboard ability to determine whether or not this card matches a previously used card by this customer.

Absent Expiry Month — paymentmethod-absent-card-expiry-month

The provided card does not have an expiry month associated with it. This makes it more difficult to determine whether or not this card matches a card previously used by this customer, or whether this card is a renewal of a previously known card.

Absent Expiry Year — paymentmethod-absent-card-expiry-year

The provided card does not have an expiry year associated with it. This makes it more difficult to determine whether or not this card matches a card previously used by this customer, or whether this card is a renewal of a previously known card.