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.

Phone Not E.164-Formatted — customer-phone-not-e164

The phone number of the customer is not formatted according to E.164 specification. Formatting a phone number as +447947123456 instead of 07947123456, allows Ravelin to identify the country of the phone number on your behalf.

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.

Absent Device — order-absent-device

The this order does not have a device. Ravelin cannot look at the IP associated with the order; or check Connect to see if the device has been used for malicious behaviour elsewhere.

Phone Not E.164-Formatted — order-phone-not-e164

The phone number of the order is not formatted according to E.164 specification. Formatting a phone number as +447947123456 instead of 07947123456, allows Ravelin to identify the country of the phone number on your behalf.

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.

Multiple links to Customer Orders — transaction-multiple-customer-orders

The transactionId has been used with multiple different orders belonging to one customer. A transaction should be limited to one payment attempt on one order, so Ravelin will not know which is the correct order to link the transaction to, and the resulting behaviour is undefined.

This is often a symptom of using the customerId or paymentMethodId as the transactionId, which you should not do. If the transaction is guaranteed to succeed – as may be the case if the payment method is a voucher – then generating a transactionId from the orderId is valid, as there cannot be re-use.

Multiple Types — transaction-multiple-types

The transaction has received multiple different types, suggesting useful customer activity may have been overridden. This can happen when the same transactionId is used for “capture” and “refund” transaction types, and a common workaround is to add a “-refund” suffix to distinguish between the two actions.

Multiple Gateways — transaction-multiple-gateways

The transaction has received multiple different gateways, suggesting useful customer activity may have been overridden. This often happens when the transactionId is generated from the orderId and triggers when the customer makes multiple attempts to pay for an order. The transactionId should change with each payment attempt of the customer, or Ravelin will lose the historic customer actions.

Multiple Gateway References — transaction-multiple-gatewayref

The transaction has received multiple different gateway references, suggesting useful customer activity may have been overridden. This often happens when the transactionId is generated from the orderId and triggers when the customer makes multiple attempts to pay for an order. The transactionId should change with each payment attempt of the customer, or Ravelin will lose the historic customer actions.

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.

Multiple Types — paymentmethod-multiple-types

The payment method has received multiple different types. Each paymentMethodId must be used to represent a single payment method used by the customer, and not overwritten with the next.

Multiple Instruments — paymentmethod-multiple-instruments

The payment method has received multiple different instrumentId. Each paymentMethodId must be used to represent a single payment method used by the customer, and not overwritten with the next.

Multiple Card BINs — paymentmethod-multiple-card-bins

The provided card has received multiple different BINs. If the customer begins using a new payment card a new paymentMethodId should be used.

Multiple Card Last4 — paymentmethod-multiple-card-last4

The provided card has received multiple different last 4 digits. If the customer begins using a new payment card a new paymentMethodId should be used.

Chargebacks

Absent Customer — chargeback-absent-customer

The references on the chargeback could not be resolved to a customer. This means the chargeback cannot be linked to a customer in Ravelin Connect and the customer purchase behaviour cannot considered by Ravelin’s machine learning models.

Absent Order — chargeback-absent-order

The references on the chargeback could not be resolved to an order. This means the customer purchase behaviour cannot considered by Ravelin’s machine learning models.

Absent Transaction — chargeback-absent-transaction

The references on the chargeback could not be resolved to a transaction. The chargeback cannot be linked to a customer in Ravelin Connect and the customer purchase behaviour cannot considered by Ravelin’s machine learning models.

Multiple links to Customer Orders — chargeback-multiple-orders

The chargeback has been linked to multiple orders belonging to one customer, suggesting that two disputes are sharing the same chargebackId. This may lead to reduced fraud detection or underreporting of Chargeback rates and costs.

Multiple links to Customer Transactions — chargeback-multiple-transactions

The chargeback has been linked to multiple transactions belonging to one customer, suggesting that two disputes are sharing the same chargebackId. This may lead to reduced fraud detection or underreporting of Chargeback rates and costs.

Multiple Gateways — chargeback-multiple-gateways

The chargeback has had multiple different gateway values, suggesting that two disputes are sharing the same chargebackId. This may lead to reduced fraud detection or underreporting of Chargeback rates and costs.

Multiple Gateway References — chargeback-multiple-gateway-references

The chargeback has had multiple different gateway references, suggesting that two disputes are sharing the same chargebackId. This may lead to reduced fraud detection or underreporting of Chargeback rates and costs.