Warnings

On this page:

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.

Instead, our endpoint will return warnings when we believe the action we recommend may be suffering from bad or missing data.

See the Checkout Endpoint response for the format of the of the warnings.

An example of a warning JSON object is shown below:

{
  "class": "customer-not-found",
  "help": "https://developer.ravelin.com/api/warnings/#customer-not-found",
  "msg": "Customer \"eg-cust-a\" not found."
}

The class field 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.

Missing Entity Warnings

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.

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 Transaction on Fulfilled Order — fulfilled-order-absent-successful-transaction

The order has been marked as fulfilled but Ravelin has not received a successful transaction for the order. This may result in any Chargebacks for such orders not being linked back to the customer or payment method, and fraudulent activity may continue longer than it should as a result, or fraud-detection models may be unable to learn the behaviour exhibited by this fraudulent customer.

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.

Instrument ID Looks Like a PAN — paymentmethod-pan-instrument

The provided card appears to have the ~16 digit card number in the instrumentId field. Only the pan field sent to pci.ravelin.com may contain a real card number, per Ravelin’s PCI DSS compliance.

Note that this warning is only issued if the detected PAN passes the Luhn check, and that 1 in every 10 numbers pass the Luhn check by accident.

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.

Dispute Warnings

Absent Customer — dispute-absent-customer

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

Absent Order — dispute-absent-order

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

Absent Transaction — dispute-absent-transaction

The references on the dispute could not be resolved to a transaction. The dispute 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 — dispute-multiple-orders

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

Multiple links to Customer Transactions — dispute-multiple-transactions

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

Multiple Gateways — dispute-multiple-gateways

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

Multiple Gateway References — dispute-multiple-gateway-references

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

Chargeback Warnings (Deprecated)

[DEPRECATION NOTICE] We have deprecated chargebacks in favour of disputes, to improve our handling of early fraud warnings and allow for more detailed reporting. Please use the Dispute endpoint. See our guide to Disputes to learn more.

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 our graph network 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 our graph network 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 efficacy 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 efficacy 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 efficacy 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 efficacy or underreporting of chargeback rates and costs.

Feedback

© Ravelin Technology Ltd. All rights reserved