# Initiate fraud screening

Request an integrated fraud screening.

## Initiate a fraud screening request

/v1/transactions

**Device data collection required**

Before calling the Transactions API with risk screening enabled, you must complete the device data collection process using the PXP SDK. This process generates a `deviceSessionId` that must be included in the `riskScreeningData` object. The `sessionID` ensures that the fraud screening is processed with complete device intelligence data, which is critical for accurate risk assessment.

### 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](/apis/transaction).

```json
{
  // 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.

```json
{
  "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"
    }
  }
}
```