APIs
/
Risk
/
Fraud API
/
Evaluates a Transaction for Risk Scoring Purposes

Risk Service (2025.04.03.0)

The Risk Service provides clients monitoring abilities to aid in fraud prevention and risk mitigation. The Risk Service consists of a robust set of rules and a series of APIs (Score, Retrieve Scores and Updating Scores) that enable real-time risk scoring on transaction based on layers of rules defined. The Risk Service API requires Basic Authentication.

The URL to the production server is https://api.nelnetpay.com/psd/risk

Download OpenAPI description
risk-api-spec.json
risk-api-spec.yaml
Languages
Servers
Mock server

https://docs.nelnetpay.com/_mock/apis/risk-api-spec/

UAT

https://api.uat.nelnetpay.com/psd/risk/

Update a Previously Scored Transaction

Request

Perform a request to update a previously scored transaction.

This endpoint uses a valid Basic Authentication username and password for authentication.

Bodyapplication/jsonrequired
uuidstring^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Original risk score uuid

Example: "e5c920e8-a619-4ca7-a06a-92e36a53e7e6"
agentUpdatedOnstring(date-time)

When the internal agent updated the order status in ISO 8601 format, UTC timezone, default to current time

Example: "2017-02-13T21:27:45Z"
agentCodestring

Code for an internal agent who has made changes to the order

Default "null"
Example: "agent123"
agentDeptstring

Department of internal agent

Default "null"
Example: "dept123"
balanceinteger(int32)

If multiple payments for an order, the balance due

Example: 150
eventstring

Note about the update

Default "null"
Example: "event name"
paymentStatusstring

Status of the order payment

Default "null"
Enum"AUTH""PAID""PARTIALLY_PAID""INVOICED""REFUNDED""PARTIALLY_REFUNDED""DEFAULT""PARTIALLY_DEFAULT""CHARGEBACK""VOID"
Example: "AUTH"
statusstring

Status of the order

Default "null"
Enum"NEW""HOLD""QUEUED""APPROVED""CANCELLED""FULFILLED""RETURNED"
Example: "APPROVED"
fraudTypestring

Fraud category

Default "null"
Enum"PAYMENT_RISK""POLICY_ABUSE""FRIENDLY_FRAUD""OTHER""IDENTITY_THEFT""SYNTHETIC_IDENTITY""ACCOUNT_TAKEOVER""RETURN""REFUND""MARKETPLACE"
Example: "OTHER"
fraudboolean
curl -i -X POST \
  -u <username>:<password> \
  https://docs.nelnetpay.com/_mock/apis/risk-api-spec/update \
  -H 'Content-Type: application/json' \
  -d '{
    "uuid": "e5c920e8-a619-4ca7-a06a-92e36a53e7e6",
    "agentUpdatedOn": "2017-02-13T21:27:45Z",
    "agentCode": "agent123",
    "agentDept": "dept123",
    "balance": 150,
    "event": "event name",
    "paymentStatus": "AUTH",
    "status": "APPROVED",
    "fraudType": "OTHER",
    "fraud": true
  }'

Responses

OK

Body*/*
successboolean

Whether the request was successful

Example: true
uuidstringread-only

Unique ID for request which is generated by risk service

Example: "e4ef2a10-20b1-4caa-8db0-60b2a3d68070"
codestring

The code if there is an error, such as 900 for internal error

Default "null"
Example: "900"
messagesArray of objects

Array[object], messages if there is any error

dataobject

Evaluates a Transaction for Risk Scoring Purposes

Request

Perform a request to evaluate a transaction for risk scoring purposes.

This endpoint uses a valid Basic Authentication username and password for authentication.

Bodyapplication/jsonrequired
billingobjectrequired

Object: billing information

billing.​firstNamestring

Customer first name

Default "null"
Example: "John"
billing.​address1string

Building number and street address

Default "null"
Example: "230 17th St"
billing.​address2string

Apartment/suite/unit number, if both address1 and address2 are not provided, this will be set to be 'Not Provided'

Default "null"
Example: "apt 1a"
billing.​companystring

Company name, for business addresses

Default "null"
Example: "Nelnet"
billing.​citystring

Address city

Default "null"
Example: "Omaha"
billing.​regionstring

Two or three digit state or province code, according to ISO3166

Default "null"
Example: "NE"
billing.​postalCodestring

Zip or postal code

Default "null"
Example: "68154"
billing.​countrystring[ 2 .. 3 ] characters

Two or three digit country code, according to ISO3166-1 alpha 2 or 3

Default "null"
Example: "US"
billing.​emailstring

Email address

Default "null"
Example: "jessica@ngilang.com"
billing.​phonestring

Phone number. If the phone provided is in not a US number, precede the number with

Default "null"
Example: "212-289-1293"
billing.​lastNamestring

Customer last name

Default "null"
Example: "Smith"
deviceobject

Object: information about the device used for the transaction

paymentobjectrequired

Object: information about the payment

payment.​paymentIdstring

Credit card/account token or identifier of payment

Default "null"
Example: "4teSTtkN123456"
payment.​actualAmtnumber(double)

Transaction amt in the currency the transaction was actually conducted in

Example: 150
payment.​actualCcystring= 3 characters

The currency of the transaction occurred in (ISO4127 currency code like USD), if it is not set, it will be set by the value of currency Merchant configuration

Default "null"
Example: "USD"
payment.​chPresentstring

User defined code indicating cardholder presence during transaction

Default "null"
Enum"YES""NO""NA"
Example: "YES"
payment.​methodstringrequired

What method is the customer using for payment. If you would like to add other payment methods, please contact your customer success team member for instructions.

Default "null"
Enum"ACH""CREDIT_CARD""DIRECT_DEBIT""GOOGLE_WALLET""APPLE_PAY""ANDROID_PAY""MASTERPASS""BITCOIN""CASH""CHECK"
Example: "CREDIT_CARD"
payment.​transactionLabelstring

User defined label that categorizes the transaction

Default "null"
Example: "tuition"
payment.​typestring

If by credit card, which card network like VISA

Default "null"
Enum"AMEX""DISCOVER""MC""OTHER""VISA""DINERS_CLUB"
Example: "VISA"
payment.​last4string= 4 characters

The credit card number's or Account's last 4 digits

Default "null"
Example: "1234"
payment.​paymentTypeByPaymentMethodstring
Example: "22"
payment.​achStandardEntryCodestring
Enum"ACK""ADV""ARC""ATX""BOC""CCD""CIE""COR""CTX""DNE"
transactionobject

Object: information about the payment transaction

psdobject

Object: extra information

curl -i -X POST \
  -u <username>:<password> \
  https://docs.nelnetpay.com/_mock/apis/risk-api-spec/score \
  -H 'Content-Type: application/json' \
  -d '{
    "billing": {
      "firstName": "John",
      "address1": "230 17th St",
      "address2": "apt 1a",
      "company": "Nelnet",
      "city": "Omaha",
      "region": "NE",
      "postalCode": "68154",
      "country": "US",
      "email": "jessica@ngilang.com",
      "phone": "212-289-1293",
      "lastName": "Smith"
    },
    "device": {
      "ipAddress": "127.32.32.1",
      "userAgent": "MOZILLA/5.0 (IPHONE; CPU IPHONE OS 7_1 LIKE MAC OS X) APPLEWEBKIT/537.51.2",
      "fingerprintId": "Id1234",
      "httpReferer": "https://www.google.com"
    },
    "payment": {
      "paymentId": "4teSTtkN123456",
      "actualAmt": 150,
      "actualCcy": "USD",
      "chPresent": "YES",
      "method": "CREDIT_CARD",
      "transactionLabel": "tuition",
      "type": "VISA",
      "last4": "1234",
      "paymentTypeByPaymentMethod": "22",
      "achStandardEntryCode": "ACK"
    },
    "transaction": {
      "orderTotal": 150,
      "status": "NEW"
    },
    "psd": {
      "clientId": "Gateway",
      "applicationId": "Enterprise",
      "productId": "Forms",
      "appKey": "appKey",
      "appKey1": "appKey1",
      "appKey2": "appKey2",
      "appKey3": "appKey3",
      "appKey4": "appKey4",
      "appKey5": "appKey5",
      "appKey6": "appKey6",
      "appKey7": "appKey7",
      "acctHolderId": "123456",
      "feeType": "Fee",
      "recurringId": "ABC123456",
      "recurringType": "RC1",
      "refundType": "RF1",
      "remittanceType": "RM1"
    }
  }'

Responses

OK

Body*/*
successboolean

Whether the request was successful

Example: true
uuidstringread-only

Unique ID for request which is generated by risk service

Example: "e4ef2a10-20b1-4caa-8db0-60b2a3d68070"
codestring

The code if there is an error, such as 900 for internal error

Default "null"
Example: "900"
messagesArray of objects

Array[object], messages if there is any error

dataobject

Retrieve a Previously Scored Transaction by Risk Uuid

Request

Perform a request to retrieve a previously scored transaction by risk uuid.

This endpoint uses a valid Basic Authentication username and password for authentication.

Path
uuidstring^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required
curl -i -X GET \
  -u <username>:<password> \
  'https://docs.nelnetpay.com/_mock/apis/risk-api-spec/score/{uuid}'

Responses

OK

Body*/*
successboolean

Whether the request was successful

Example: true
uuidstringread-only

Unique ID for request which is generated by risk service

Example: "e4ef2a10-20b1-4caa-8db0-60b2a3d68070"
codestring

The code if there is an error, such as 900 for internal error

Default "null"
Example: "900"
messagesArray of objects

Array[object], messages if there is any error

dataobject