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.
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-foundNo 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-foundNo 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-foundNo 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.
paymentmethod-not-foundNo 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.
refund-not-foundNo refund with the given refundId exists in Ravelin’s systems. Ravelin will be unable to use information associated with the refund (the amount, the items refunded) when scoring.
customer-absent-emailThe 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.
customer-absent-reg-timeThe 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.
customer-phone-not-e164The 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-absent-priceThe 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.
order-absent-currencyThe order does not have a currency. Ravelin will not be able to understand how much a monetary value represents in comparison to others.
order-absent-statusThe 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.
order-absent-creation-timeThe order does not have a creation time. Ravelin will be unable to understand when the order actually happened.
fulfilled-order-absent-successful-transactionThe 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.
order-absent-deviceThe 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.
order-phone-not-e164The 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-absent-typeThe 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.
transaction-absent-currencyThe transaction does not have a currency. Ravelin will not be able to understand how much a monetary value represents in comparison to others.
transaction-absent-amountThe transaction has no amount. A transaction that exchanges no value is meaningless.
transaction-absent-paymentmethodThe 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.
transaction-multiple-customer-ordersThe 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.
transaction-multiple-typesThe 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.
transaction-multiple-gatewaysThe 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.
transaction-multiple-gatewayrefThe 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.
transaction-capture-after-preventA transaction was succesfully captured after Ravelin returned an action of PREVENT for the given customer. This indicates that the action returned is being ignored.
transaction-capture-not-scoredA 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.
paymentmethod-absent-registration-timeThe 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.
paymentmethod-absent-card-binThe 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.
paymentmethod-absent-card-last4The 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.
paymentmethod-absent-card-expiry-monthThe 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.
paymentmethod-absent-card-expiry-yearThe 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.
paymentmethod-pan-instrumentThe 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.
paymentmethod-multiple-typesThe 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.
paymentmethod-multiple-instrumentsThe 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.
paymentmethod-multiple-card-binsThe provided card has received multiple different BINs. If the customer begins using a new payment card a new paymentMethodId should be used.
paymentmethod-multiple-card-last4The provided card has received multiple different last 4 digits. If the customer begins using a new payment card a new paymentMethodId should be used.
refund-absent-request-time The refund does not have a request time. Ravelin will not be able to determine when the refund was initiated.
refund-absent-issued-time The refund does not have an issued time. Ravelin will not be able to understand when the refund was completed.
refund-absent-decline-reason The refund does not include a decline reason. Ravelin will not be able to identify why the refund was rejected.
refund-absent-type The refund does not have a type. Ravelin will not be able to understand whether the refund is for a repayment, an exchange or replacement of the original item.
refund-absent-claim The refund does not reference a claim. Ravelin will not be able to understand whether the refund request is a partial or full one.
refund-absent-reason The refund does not have a reason. Ravelin will not be able to understand why the refund was requetsed or issued.
refund-absent-amount The refund does not have an amount. A refund that has no value is meaningless.
refund-absent-currency The refund does not specify a currency. Ravelin will not be able to understand how much a monetary value represents in comparison to others.
dispute-absent-customerThe 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.
dispute-absent-orderThe 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.
dispute-absent-transactionThe 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.
dispute-multiple-ordersThe 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.
dispute-multiple-transactionsThe 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.
dispute-multiple-gatewaysThe 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.
dispute-multiple-gateway-referencesThe 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.
[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 the Sending Disputes guide to learn more.
chargeback-absent-customerThe 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.
chargeback-absent-orderThe 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.
chargeback-absent-transactionThe 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.
chargeback-multiple-ordersThe 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.
chargeback-multiple-transactionsThe 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.
chargeback-multiple-gatewaysThe 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.
chargeback-multiple-gateway-referencesThe 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.
payout-absent-scheduleThe payout does not have a schedule. Ravelin will not be able to identify the schedule on which the payout was created.
payout-absent-revenue-sourceThe payout does not have a breakdown of revenue source. Ravelin will not be able to understand the different revenue streams.
Was this page helpful?