This page explains how to request a payment fraud recommendation when either a customer attempts to complete a purchase or attempts to add a payment method to their account.
On this page:To request a payment fraud recommendation when a customer attempts to place an order, send a request to our Checkout endpoint using the Checkout Pre-Auth Checkpoint or Checkout Post-Auth Checkpoint.
To use the Checkout Pre-Auth Checkpoint add score=checkoutPreAuth as a query parameter to the URL.
The request should contain the customer, device, payment method, order and transaction data. Each of these entities is described below:
Customers
Customers place orders, attempt payment transactions, spend on payment methods,
log in from devices and file chargebacks.
If customers are not required to sign up to your service in order to make a
purchase, we recommend using their email address as the customerId in all cases.
Devices
Devices are used by customers to place orders. Multiple customers may use the same
device. They may be a web browser or a mobile device.
Orders
An order is placed by a customer, has a price and currency, contains order
items describing what is being bought, may have multiple failed transaction
payments, hopefully has a successful transaction payment, is placed from one
device, and has disputing chargebacks.
The order items may describe taxi rides, food orders, concert tickets,
hotel bookings, something else or some combination of each.
Transactions
A transaction is an attempt to pay for one order placed by one customer, it has an
amount and a currency, has one payment method and gateway processor, eventually
has a gateway reference, success flag and authentication/check information, and
may have multiple chargebacks associated with it.
Payment Methods
A payment method is used by one customer to provide funds to fulfill many
transactions and many orders. The payment method can be a payment card (having a
scheme, issuer, BIN, last-four digits, and a globally-identifying instrumentID),
a voucher, cash, PayPal account, or many other means of sending funds.
See our Checkout Endpoint API reference for all the supported fields. The more data you can provide, the better our recommendations will be.
An example request is shown below:
POST https://api.ravelin.com/v2/checkout?score=checkoutPreAuth HTTP/1.1
Authorization: token ...
Content-Type: application/json
{
"timestamp": 1512828988826,
"customer": {
"customerId": "abc-123-ZYZ",
"registrationTime": 1512828988826,
"email": "jsmith123@example.com",
"name": "John Smith",
"telephone": "+447000000001",
"telephoneCountry": "GBR"
},
"device": {
"deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
"type": "phone",
"manufacturer": "google",
"model": "Pixel XL",
"os": "android",
"language": "en-US",
"ipAddress": "81.152.92.84"
},
"order": {
"orderId": "abcde12345-ZXY",
"creationTime": 1512828988826,
"price": 1500,
"currency": "GBP",
"market": "emea",
"country": "GBR",
"marketCity": "london",
"items": [
{
"sku": "0001",
"name": "Margherita Pizza",
"quantity": 1,
"price": 1500
}
],
"status": {
"stage": "pending",
"actor": "merchant"
},
"shipping": {
"daysToDispatch": 7,
"method": "STANDARD",
"destinationType": "HOME",
"carrier":"DHL"
}
},
"paymentMethods": [
{
"paymentMethodId": "pm-abc123",
"instrumentId": "fp_abc123",
"methodType": "card",
"scheme": "visa",
"cardBin": "535522",
"cardLastFour": "0001",
"expiryMonth": 7,
"expiryYear": 2020,
"nameOnCard": "John Smith",
"billingAddress": {
"addresseeName": "John Smith",
"street1": "123 High Street",
"city": "London",
"country": "GBR",
"postalCode": "E1 1AA"
}
}
],
"transactions": [
{
"transactionId": "123-abc-XYZ",
"paymentMethodId": "pm-abc123",
"time": 1512828988826,
"amount": 1000,
"currency": "GBP",
"type": "auth",
"gateway": "example-gateway"
}
]
}An example response is shown below:
{
"status": 200,
"timestamp": 709513200,
"data": {
"action": "ALLOW",
"score": 12,
"source": "RAVELIN",
"customerId": "abc-123-ZYZ",
"scoreId": "2bf39d-d1299-31"
}
}The data.action field in the response contains our recommendation, you should use this to determine how you handle the order. The table below explains the actions.
| Action | Action to take |
|---|---|
ALLOW |
We think the order is from a genuine customer. Allow the order to proceed. |
REVIEW |
We suspect the activity is not from a genuine customer. Take extra verification steps for the order. |
3DS_AUTHENTICATE |
We suspect the activity is not from a genuine customer. We suggest verifying the customer using 3D Secure. |
MANUAL_REVIEW |
We suspect the activity is not from a genuine customer. We suggest verifying the customer by doing a manual review. |
PREVENT |
We suspect the order is fraudulent. Prevent the order. |
The action is based on the fraud score, which can be seen in the data.score field.
We will work with you to configure the fraud score thresholds to produce action values which match your risk appetite.
Other fields are provided for analytic and debugging purposes.
Do not implement any logic based upon the source field, or attempt to deserialise it into an enum,
as we may add new source values in the future.
See our API Reference for the full details of the Checkout Endpoint Response.
To request a payment fraud recommendation when a customer attempts to add a payment method to their account, send a request to our Payment Method endpoint using the Payment Method Registration Checkpoint.
To use the Payment Method Registration Checkpoint add score=paymentMethodRegistration as a query parameter to the URL.
The request should contain all the customer, device, payment method data.
An example request is shown below:
POST https://api.ravelin.com/v2/paymentmethod?score=paymentMethodRegistration HTTP/1.1
Authorization: token ...
Content-Type: application/json
{
"timestamp": 1512828988826,
"customerId": "abc-123-ZYZ",
"paymentMethod": {
"paymentMethodId": "pm-abc123",
"instrumentId": "fp_abc123",
"methodType": "card",
"scheme": "visa",
"cardBin": "535522",
"cardLastFour": "0001",
"expiryMonth": 7,
"expiryYear": 2020,
"nameOnCard": "John Smith",
"billingAddress": {
"addresseeName": "John Smith",
"street1": "123 High Street",
"city": "London",
"country": "GBR",
"postalCode": "E1 1AA"
}
},
"device": {
"deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
"type": "phone",
"manufacturer": "google",
"model": "Pixel XL",
"os": "android",
"language": "en-US",
"ipAddress": "81.152.92.84"
}
}This example request only contains a subset of all the fields the Payment Method Endpoint supports. See our Payment Method Endpoint API reference for all the supported fields. The more data you can provide, the better our recommendations will be.
An example response is shown below:
{
"status": 200,
"timestamp": 709513200,
"data": {
"action": "ALLOW",
"score": 12,
"source": "RAVELIN",
"customerId": "abc-123-ZYZ",
"scoreId": "2bf39d-d1299-31"
}
}The data.action field in the response contains our recommendation, you should use this to determine how you handle payment method registration. The table below explains the actions.
| Action | Action to take |
|---|---|
ALLOW |
We think this is a genuine customer. Allow them to add the payment method to their account. |
REVIEW |
Take extra validation steps (e.g. require the customer complete 3D Secure verification). |
PREVENT |
We suspect the customer is fraudulent. Do not allow them to add the payment method to their account. |
The action is based on the fraud score, which can be seen in the data.score field.
We will work with you to configure the fraud score thresholds to produce action values which match your risk appetite.
Other fields are provided for analytic and debugging purposes.
Do not implement any logic based upon the source field, or attempt to deserialise it into an enum,
as we may add new source values in the future.
See our API Reference for the full details of the Payment Method Endpoint Response.
In order to provide resiliency, on the rare occasion that Ravelin isn’t able to calculate a fraud score, a cached score is used
to determine the action. If a cached score was used, the cachedScore field in the response will be set to true .
The response will also contain the effectiveTime field which describes when the cached score was originally calculated.
If you’d rather not rely on cached scores, we suggest you treat responses containing cached scores the same way as a REVIEW action.
An example response containing a cached score is shown below:
{
"status": 200,
"timestamp": 709513200,
"data": {
"customerId": "123456789",
"action": "ALLOW",
"score": 4,
"source": "RAVELIN",
"scoreId": "2bf39d-d1299-31",
"cachedScore": true,
"effectiveTime": "2020-01-01T00:00:00.00000000Z"
}
}Send order updates so we know how our recommendations are performing
Send disputes to help us learn about your fraud
Was this page helpful?