Transaction risk screening service API (1.0.0)

This is an API reference for the Transaction Risk Screening service.

Download OpenAPI description

risk-screening.json

risk-screening.yaml

Servers

Production environment

https://api-services.pxp.io/api/v1/

Sandbox environment

https://api-services.test.pxp.io/api/v1/

Initiate standalone fraud screening

Request

Performs a standalone fraud screening analysis for a transaction. All fields are optional.

Bodyapplication/jsonrequired

merchantGroupstring

Your unique merchant group identifier, as assigned by PXP.

Example: "GROUP123"

merchantstring<= 20 characters

Your unique merchant identifier, as assigned by PXP.

Example: "MERCHANT123"

sitestring<= 20 characters

Your unique site identifier, as assigned by PXP.

Example: "SITE123"

performRiskScreeningboolean

Whether to enable risk screening for this transaction.

Example: true

excludeDeviceDataboolean

Whether to exclude device fingerprinting data from analysis.

Example: false

channelstring<= 256 characters

The channel through which the transaction was initiated.

Example: "ACME_IOS_APP"

deviceSessionIdstring<= 256 characters^[0-9A-Za-z]*$

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.

creationDateTimestring(date-time)

The date and time when the order was placed, in ISO 8601 format.

Example: "2024-01-15T10:30:00Z"

userIpstring(ipv4)

The customer's IPv4 address, in dotted decimal notation.

Example: "192.168.1.27"

accountobject(Account)

Details about the customer's account.

itemsArray of objects(Item)

Array of details about each item in the order.

fulfillmentsArray of objects(Fulfillment)

Array of details about the fulfillment of the order.

transactionsArray of objects(Transaction)

Array of details about the payment transactions made for the order.

promotionsArray of objects(Promotion)

Array of promotions applied to this order.

loyaltyobject(Loyalty)

Details about a credit that was applied from a loyalty account.

customFieldsobject

Additional custom fields, in key-value pairs.

curl -i -X POST \
  https://api-services.pxp.io/api/v1/transaction-risk-screenings/standalone \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantGroup": "GROUP123",
    "merchant": "MERCH123",
    "site": "SITE123",
    "performRiskScreening": true,
    "excludeDeviceData": false,
    "channel": "web",
    "deviceSessionId": "abc123-def456-ghi789",
    "creationDateTime": "2024-01-15T10:30:00Z",
    "userIp": "192.168.1.100",
    "account": {
      "id": "user123456",
      "type": "registered",
      "creationDateTime": "2023-06-15T08:00:00Z",
      "username": "john.doe@pxp.io",
      "accountIsActive": true
    },
    "items": [
      {
        "id": "item001",
        "price": 2999,
        "description": "Wireless Bluetooth Headphones",
        "name": "Premium Headphones",
        "quantity": 1,
        "category": "Electronics",
        "subCategory": "Audio",
        "isDigital": false,
        "sku": "SKU-WBH-001",
        "upc": "123456789012",
        "brand": "TechBrand",
        "url": "https://example.com/products/wireless-headphones",
        "imageUrl": "https://example.com/images/headphones.jpg",
        "physicalAttributes": {
          "color": "Black",
          "size": "Medium",
          "weight": "250g",
          "height": "20cm",
          "width": "15cm",
          "depth": "8cm"
        },
        "descriptors": [
          "wireless",
          "bluetooth",
          "noise-cancelling"
        ],
        "isService": false
      }
    ],
    "fulfillments": [
      {
        "type": "SHIPPED",
        "shipping": {
          "shippingAmount": 599,
          "shippingProvider": "FedEx",
          "trackingNumber": "1234567890123456",
          "shippingMethod": "STANDARD"
        },
        "items": [
          {
            "id": "item001",
            "quantity": 1
          }
        ],
        "status": "PENDING",
        "accessUrl": null,
        "store": null,
        "recipientPerson": {
          "name": {
            "first": "John",
            "middle": "A",
            "family": "Doe",
            "prefix": "Mr",
            "suffix": null,
            "preferred": "John"
          },
          "emailAddress": "john.doe@example.com",
          "phoneNumber": "+1-555-123-4567",
          "address": {
            "line1": "123 Main Street",
            "line2": "Apt 4B",
            "city": "New York",
            "region": "NY",
            "countryCode": "US",
            "postalCode": "10001"
          },
          "dateOfBirth": "1990-05-15"
        },
        "merchantFulfillmentId": "FULFILL-001"
      }
    ],
    "transactions": [
      {
        "merchantTransactionId": "TXN-20240115-001",
        "processor": "stripe",
        "processorMerchantId": "acct_1234567890",
        "payment": {
          "type": "CREDIT_CARD",
          "paymentToken": "tok_1234567890abcdef",
          "bin": "424242",
          "last4": "4242"
        },
        "subtotal": 2999,
        "orderTotal": 3598,
        "currency": "USD",
        "tax": {
          "isTaxable": true,
          "taxableCountryCode": "US",
          "taxAmount": 240,
          "outOfStateTaxAmount": 0
        },
        "billedPerson": {
          "name": {
            "first": "John",
            "middle": "A",
            "family": "Doe",
            "prefix": "Mr",
            "suffix": null,
            "preferred": "John"
          },
          "emailAddress": "john.doe@example.com",
          "phoneNumber": "+1-555-123-4567",
          "address": {
            "line1": "123 Main Street",
            "line2": "Apt 4B",
            "city": "New York",
            "region": "NY",
            "countryCode": "US",
            "postalCode": "10001"
          },
          "dateOfBirth": "1990-05-15"
        },
        "transactionStatus": "AUTHORIZED",
        "authorizationStatus": {
          "authResult": "Approved",
          "dateTime": "2024-01-15T10:30:15Z",
          "verificationResponse": {
            "avsStatus": "Y",
            "cvvStatus": "Match"
          },
          "declineCode": null,
          "processorAuthCode": "AUTH123456",
          "processorTransactionId": "pi_1234567890abcdef",
          "acquirerReferenceNumber": "ACQ789012345"
        },
        "items": [
          {
            "id": "item001",
            "quantity": 1
          }
        ]
      }
    ],
    "promotions": [
      {
        "id": "PROMO-WINTER2024",
        "description": "Winter Sale - 10% off electronics",
        "status": "active",
        "statusReason": "promotion_applied",
        "discount": {
          "percentage": 0.1,
          "amount": 300,
          "currency": "USD"
        },
        "credit": null
      }
    ],
    "loyalty": {
      "id": "LOYALTY-12345",
      "description": "Premium Member Rewards",
      "credit": {
        "creditType": "points",
        "amount": 150,
        "currency": "USD"
      }
    },
    "customFields": {
      "example-custom-field-1": "AFF-001"
    }
  }'

Responses

Risk screening completed successfully

Bodyapplication/json

riskScreeningIdstring

The unique identifier for this risk screening request.

Example: "e721acfa-f844-4bec-9007-47eb07dcb117"

providerResultsobject

Details about the results of the risk screening.

Response

application/json

{
  "riskScreeningId": "e721acfa-f844-4bec-9007-47eb07dcb117",
  "providerResults": {
    "kount": { … }
  }
}

Transaction risk screening service API (1.0.0)

Initiate standalone fraud screening

RequestExpand all

Responses

Was this helpful?

Request