Initiate fraud screening

Request an integrated fraud screening.

Initiate a fraud screening request

POST

/v1/transactions

Request example

To initiate an integrated fraud screening, include the shopper and riskScreeningData objects in your transaction request. For more details about the other parameters, see the Transactions API reference.

{
  // other transaction properties
  "shopper": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "countryCode": "US",
    "state": "CA",
    "city": "San Francisco",
    "postalCode": "94102",
    "street": "Market Street",
    "houseNumberOrName": "123",
    "phoneNumber": "+1-555-123-4567",
    "addressLine2": "Apt 4B"
  },
  "riskScreeningData": {
    "performRiskScreening": true,
    "excludeDeviceData": true,
    "deviceSessionId": "session_xyz123456",
    "items": [
      {
        "price": 4525,
        "quantity": 2,
        "category": "Electronics",
        "sku": "WIDGET_001"
      },
      {
        "price": 1000,
        "quantity": 1,
        "category": "Electronics",
        "sku": "WIDGET_002"
      }
    ],
    "fulfillments": [
      {
        "type": "Shipped",
        "recipientPerson": {
          "name": {
            "first": "Jane",
            "middle": "Marie",
            "family": "Smith",
            "prefix": "Ms.",
            "suffix": null,
            "preferred": "Jane"
          },
          "address": {
            "line1": "456 Shipping Street",
            "line2": "Apartment 2B",
            "city": "London",
            "region": "Greater London",
            "countryCode": "GB",
            "postalCode": "SW2B2BB"
          },
          "email": "jane.smith@example.com",
          "phoneNumber": "+442079460958"
        }
      }
    ],
    "transaction": {
      "subtotal": 10050
    }
  }
}

Parameter	Description
`shopper` object	Details about the shopper.
`shopper.email` string (≤ 100 characters)	The email address of the shopper.
`shopper.firstName` string (≤ 100 characters)	The first name of the shopper.
`shopper.lastName` string (≤ 100 characters)	The last name of the shopper.
`shopper.countryCode` string (2 characters)	The country code of the shopper's address, in ISO-3166-1 alpha-2 format.
`shopper.state` string (2 characters)	The state or province associated with the shopper's address, in ISO 3166-2 format.
`shopper.city` string	The city associated with the shopper's address.
`shopper.postalCode` string (≤ 10 characters)	The postal or ZIP code of the shopper's address. This field accepts up to 5 digits for US addresses or up to 10 characters for addresses in other countries, accommodating global variations in postal code formats.
`shopper.street` string (≤ 100 characters)	The street associated with the shopper's address.
`shopper.houseNumberOrName` string (≤ 100 characters)	The house number or name associated with the shopper's address.
`shopper.phoneNumber` string (≤ 50 characters)	The shopper's phone number.
`shopper.addressLine2` string (≤ 100 characters)	The second line of the shopper's address.
`riskScreeningData.performRiskScreening` boolean	Whether to enable risk screening for this transaction.
`riskScreeningData.excludeDeviceData` boolean	Whether to exclude device fingerprinting data from analysis.
`riskScreeningData.deviceSessionId` string (≤ 256 characters)	The unique session identifier for the customer's end-user session on your site or app. This must be the same session ID used in the device data collection from the client-side Kount SDK. Format: `^[[0-9A-Za-z]]*$`.
`riskScreeningData.items.price` integer	The price of the single item in the lowest currency factor. For example, the lowest currency in `USD` is pennies, so $1.00 would have the value of `100`. Must be a natural number including `0`.
`riskScreeningData.items.quantity` integer	The quantity of the item being purchased. This must be at least `1`.
`riskScreeningData.items.category` string	A high-level or generalised description of the item.
`riskScreeningData.items.sku` string	The item's Stock Keeping Unit identifier (SKU).
`riskScreeningData.fulfillments` array	Array of details about the fulfillment of the order.
`riskScreeningData.fulfillments.type`	The type of fulfillment. Possible values: `SHIPPED` `DIGITAL` `STORE_PICK_UP` `LOCAL_DELIVERY` `STORE_DRIVE_UP` `IN_PERSON`
`riskScreeningData.fulfillments.recipientPerson` object	Details about the order's recipient.
`riskScreeningData.fulfillments.recipientPerson.name` object	Details about the recipient's name.
`riskScreeningData.fulfillments.recipientPerson.name.first` string	The recipient's first name.
`riskScreeningData.fulfillments.recipientPerson.name.middle` string`	The recipient's middle name or initial.
`riskScreeningData.fulfillments.recipientPerson.name.family` string	The recipient's last name/family name.
`riskScreeningData.fulfillments.recipientPerson.name.prefix` string	The prefix of the recipient's name.
`riskScreeningData.fulfillments.recipientPerson.name.suffix` string	The suffix of the recipient's name.
`riskScreeningData.fulfillments.recipientPerson.name.preferred` string	The recipient's preferred name.
`riskScreeningData.fulfillments.recipientPerson.address` object	Details about the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.address.line1` string	The first line of the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.address.line2` string	The second line of the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.address.city` string	The city of the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.address.region` string	The state, province, or region code of the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.address.countryCode` string	The country of the recipient's address, in ISO 3166-1 alpha-2 format.
`riskScreeningData.fulfillments.recipientPerson.address.postalCode` string	The postal or ZIP code of the recipient's address.
`riskScreeningData.fulfillments.recipientPerson.email` string	The recipient's email address.
`riskScreeningData.fulfillments.recipientPerson.phoneNumber` string	The recipient's phone number.
`riskScreeningData.transaction` object	Details about the payment transaction.
`riskScreeningData.transaction.subtotal` integer	The total amount of the order without shipping and tax included, in its lowest denomination. For example, the lowest denomination in USD is the penny, so $1.00 has a "total" of `100`. The total must be a natural number, which includes `0`.

Response example

If your request is successful, you'll receive a 200 response.

{
  "state": "Authorised",
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "avsResult": "noInformationAvailable",
    "cvcResult": "noInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "avsResult": "D",
      "cvcResult": "A",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "PAR12345678901234567890",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}

Initiate fraud screening

Initiate a fraud screening request

Request example

Response example

Was this helpful?