Payment Fraud Integration

Requesting Recommendations

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:

Recommendations at checkout

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.

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"
    }
  },
  "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.

Recommendations at payment method registration

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.

Cached scores

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"
  }
}

Next steps

Send order updates so we know how our recommendations are performing

Send disputes to help us learn about your fraud

Feedback

© Ravelin Technology Ltd. All rights reserved