openapi: 3.0.1
info:
  title: Risk Service
  description: >-
    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](/gettingstarted#basic-authentication).
     
     
    __The URL to the production server is `https://api.nelnetpay.com/psd/risk`__
  version: 2025.04.03.0
servers:
  - url: https://api.uat.nelnetpay.com/psd/risk
    description: UAT
security:
  - basicAuth: []
paths:
  /update:
    post:
      summary: Update a Previously Scored Transaction
      description: >
        Perform a request to update a previously scored transaction. 


        This endpoint uses a valid Basic Authentication username and password
        for authentication.
      operationId: update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Authentication Failed
          content: {}
        '404':
          description: URL Not Found
        '405':
          description: Method Not Allowed
          content: {}
      security:
        - basicAuth: []
  /score:
    post:
      summary: Evaluates a Transaction for Risk Scoring Purposes
      description: >
        Perform a request to evaluate a transaction for risk scoring purposes. 


        This endpoint uses a valid Basic Authentication username and password
        for authentication.
      operationId: score
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoreRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Authentication Failed
          content: {}
        '404':
          description: URL Not Found
        '405':
          description: Method Not Allowed
          content: {}
      security:
        - basicAuth: []
  /score/{uuid}:
    get:
      summary: Retrieve a Previously Scored Transaction by Risk Uuid
      description: >
        Perform a request to retrieve a previously scored transaction by risk
        uuid. 


        This endpoint uses a valid Basic Authentication username and password
        for authentication.
      operationId: read
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Authentication Failed
          content: {}
        '404':
          description: URL Not Found
        '405':
          description: Method Not Allowed
          content: {}
      security:
        - basicAuth: []
components:
  schemas:
    Message:
      type: object
      properties:
        message:
          type: string
          description: Content of the message such as Internal Error
          example: Internal Server Error
        dataPath:
          type: string
          description: Path to the data file
          example: payment
      description: Array[object], messages if there is any error
    Response:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: true
        uuid:
          type: string
          description: Unique ID for request which is generated by risk service
          readOnly: true
          example: e4ef2a10-20b1-4caa-8db0-60b2a3d68070
        code:
          type: string
          description: The code if there is an error, such as 900 for internal error
          example: '900'
          default: 'null'
        messages:
          type: array
          description: Array[object], messages if there is any error
          items:
            $ref: '#/components/schemas/Message'
        data:
          $ref: '#/components/schemas/ResponseData'
    ResponseData:
      type: object
      properties:
        id:
          type: string
          description: UUID of the request
          example: e4ef2a10-20b1-4caa-8db0-60b2a3d68070
        riskScore:
          type: integer
          description: Risk score, on a scale from 0 (low risk) to 100 (high risk)
          format: int32
          example: 50
        mostSevereAction:
          type: string
          description: Applied action, according to risk assessment
          example: cancelled
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      properties:
        action:
          type: string
          description: Action name related to rule
          example: cancelled
        name:
          type: string
          description: Name of your tag
          example: Rule Cancelled
        type:
          type: string
          description: >-
            Action that you would like your tag to have associated. 'label' will
            simply tag your order, while 'queue' will cause the order to be
            placed in a queue for later retrieval and review
          example: rule
        state:
          type: string
          description: Rule set
          example: Global Rule Set
    UpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          type: string
          description: Original risk score uuid
          example: e5c920e8-a619-4ca7-a06a-92e36a53e7e6
        agentUpdatedOn:
          type: string
          description: >-
            When the internal agent updated the order status in ISO 8601 format,
            UTC timezone, default to current time
          format: date-time
          example: '2017-02-13T21:27:45Z'
        agentCode:
          type: string
          description: Code for an internal agent who has made changes to the order
          example: agent123
          default: 'null'
        agentDept:
          type: string
          description: Department of internal agent
          example: dept123
          default: 'null'
        balance:
          type: integer
          description: If multiple payments for an order, the balance due
          format: int32
          example: 150
        event:
          type: string
          description: Note about the update
          example: event name
          default: 'null'
        paymentStatus:
          type: string
          description: Status of the order payment
          example: AUTH
          default: 'null'
          enum:
            - AUTH
            - PAID
            - PARTIALLY_PAID
            - INVOICED
            - REFUNDED
            - PARTIALLY_REFUNDED
            - DEFAULT
            - PARTIALLY_DEFAULT
            - CHARGEBACK
            - VOID
        status:
          type: string
          description: Status of the order
          example: APPROVED
          default: 'null'
          enum:
            - NEW
            - HOLD
            - QUEUED
            - APPROVED
            - CANCELLED
            - FULFILLED
            - RETURNED
        fraudType:
          type: string
          description: Fraud category
          example: OTHER
          default: 'null'
          enum:
            - PAYMENT_RISK
            - POLICY_ABUSE
            - FRIENDLY_FRAUD
            - OTHER
            - IDENTITY_THEFT
            - SYNTHETIC_IDENTITY
            - ACCOUNT_TAKEOVER
            - RETURN
            - REFUND
            - MARKETPLACE
            - NON_PAYMENT
            - PACKAGE_THEFT
        fraud:
          type: boolean
    Billing:
      type: object
      properties:
        firstName:
          type: string
          description: Customer first name
          example: John
          default: 'null'
        address1:
          type: string
          description: Building number and street address
          example: 230 17th St
          default: 'null'
        address2:
          type: string
          description: >-
            Apartment/suite/unit number, if both address1 and address2 are not
            provided, this will be set to be 'Not Provided'
          example: apt 1a
          default: 'null'
        company:
          type: string
          description: Company name, for business addresses
          example: Nelnet
          default: 'null'
        city:
          type: string
          description: Address city
          example: Omaha
          default: 'null'
        region:
          type: string
          description: Two or three digit state or province code, according to ISO3166
          example: NE
          default: 'null'
        postalCode:
          type: string
          description: Zip or postal code
          example: '68154'
          default: 'null'
        country:
          maxLength: 3
          minLength: 2
          type: string
          description: Two or three digit country code, according to ISO3166-1 alpha 2 or 3
          example: US
          default: 'null'
        email:
          type: string
          description: Email address
          example: jessica@ngilang.com
          default: 'null'
        phone:
          type: string
          description: >-
            Phone number. If the phone provided is in not a US number, precede
            the number with
          example: 212-289-1293
          default: 'null'
        lastName:
          type: string
          description: Customer last name
          example: Smith
          default: 'null'
      description: 'Object: billing information'
    Device:
      type: object
      properties:
        ipAddress:
          type: string
          description: String or null
          example: 127.32.32.1
          default: 'null'
        userAgent:
          type: string
          description: String or null
          example: >-
            MOZILLA/5.0 (IPHONE; CPU IPHONE OS 7_1 LIKE MAC OS X)
            APPLEWEBKIT/537.51.2
          default: 'null'
        fingerprintId:
          type: string
          description: String or null
          example: Id1234
          default: 'null'
        httpReferer:
          type: string
          description: String or null
          example: https://www.google.com
          default: 'null'
      description: 'Object: information about the device used for the transaction'
    PSD:
      type: object
      properties:
        clientId:
          type: string
          description: Your client id
          example: Gateway
          default: 'null'
        applicationId:
          type: string
          description: Id for your application, such as PaymentSpring AppId
          example: Enterprise
          default: 'null'
        productId:
          type: string
          description: Id for your product
          example: Forms
          default: 'null'
        appKey:
          type: string
          description: Key for your application if available
          example: appKey
          default: 'null'
        appKey1:
          type: string
          description: Another Key for your application if available
          example: appKey1
          default: 'null'
        appKey2:
          type: string
          description: Another Key for your application if available
          example: appKey2
          default: 'null'
        appKey3:
          type: string
          description: Another Key for your application if available
          example: appKey3
          default: 'null'
        appKey4:
          type: string
          description: Another Key for your application if available
          example: appKey4
          default: 'null'
        appKey5:
          type: string
          description: Another Key for your application if available
          example: appKey5
          default: 'null'
        appKey6:
          type: string
          description: Another Key for your application if available
          example: appKey6
          default: 'null'
        appKey7:
          type: string
          description: Another Key for your application if available
          example: appKey7
          default: 'null'
        acctHolderId:
          type: string
          description: The account id for the bussiness
          example: '123456'
          default: 'null'
        feeType:
          type: string
          description: >-
            If the payment is fee, and indicate which type the fee is if
            available
          example: Fee
          default: 'null'
        recurringId:
          type: string
          description: >-
            If it is recurring payment, what the id is if it is available, such
            as PlanId in the Payment API
          example: ABC123456
          default: 'null'
        recurringType:
          type: string
          description: If it is recurring, you define a value for the type
          example: RC1
          default: 'null'
        refundType:
          type: string
          description: >-
            If it is refund, you define a value for the type, this might be set
            to be RF1 if PsAchPaymentType is credit and Merchant is Remittance
            Only
          example: RF1
          default: 'null'
        remittanceType:
          type: string
          description: >-
            If it is remittance, you define a value for the type, this might be
            set to be RM1 if Merchant is Remittance Only
          example: RM1
          default: 'null'
      description: 'Object: extra information'
    Payment:
      required:
        - method
      type: object
      properties:
        paymentId:
          type: string
          description: Credit card/account token or identifier of payment
          example: 4teSTtkN123456
          default: 'null'
        actualAmt:
          type: number
          description: >-
            Transaction amt in the currency the transaction was actually
            conducted in
          format: double
          example: 150
        actualCcy:
          maxLength: 3
          minLength: 3
          type: string
          description: >-
            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
          example: USD
          default: 'null'
        chPresent:
          type: string
          description: User defined code indicating cardholder presence during transaction
          example: 'YES'
          default: 'null'
          enum:
            - 'YES'
            - 'NO'
            - NA
        method:
          type: string
          description: >-
            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.
          example: CREDIT_CARD
          default: 'null'
          enum:
            - ACH
            - CREDIT_CARD
            - DIRECT_DEBIT
            - GOOGLE_WALLET
            - APPLE_PAY
            - ANDROID_PAY
            - MASTERPASS
            - BITCOIN
            - CASH
            - CHECK
            - ECHECK
            - INVOICE
            - PAYPAL
            - OTHER
            - SEPA
            - NPP
            - FASTER
            - BCAS
            - CHAPS
            - SWIFT
        transactionLabel:
          type: string
          description: User defined label that categorizes the transaction
          example: tuition
          default: 'null'
        type:
          type: string
          description: If by credit card, which card network like VISA
          example: VISA
          default: 'null'
          enum:
            - AMEX
            - DISCOVER
            - MC
            - OTHER
            - VISA
            - DINERS_CLUB
        last4:
          maxLength: 4
          minLength: 4
          type: string
          description: The credit card number's or Account's last 4 digits
          example: '1234'
          default: 'null'
        paymentTypeByPaymentMethod:
          type: string
          example: '22'
        achStandardEntryCode:
          type: string
          enum:
            - ACK
            - ADV
            - ARC
            - ATX
            - BOC
            - CCD
            - CIE
            - COR
            - CTX
            - DNE
            - ENR
            - IAT
            - MTE
            - POP
            - POS
            - PPD
            - RCK
            - SHR
            - TEL
            - TRC
            - TRX
            - WEB
            - XCK
      description: 'Object: information about the payment'
    Product:
      required:
        - price
        - productId
        - quantity
        - title
      type: object
      properties: {}
      description: 'Array[Object]: production information'
    ScoreRequest:
      required:
        - billing
        - payment
      type: object
      properties:
        billing:
          $ref: '#/components/schemas/Billing'
        device:
          $ref: '#/components/schemas/Device'
        payment:
          $ref: '#/components/schemas/Payment'
        transaction:
          $ref: '#/components/schemas/Transaction'
        psd:
          $ref: '#/components/schemas/PSD'
    Seller:
      type: object
      properties: {}
      description: 'Object: information about the seller'
    Shipping:
      type: object
      properties: {}
      description: 'Object: information about the shipping'
    Transaction:
      type: object
      properties:
        orderTotal:
          type: number
          description: Amount spent for this order
          format: double
          example: 150
        status:
          type: string
          description: >-
            Status of transaction (usually NEW, QUEUED, APPROVED, CANCELLED, or
            FULFILLED), default to NEW
          example: NEW
          default: NEW
          enum:
            - NEW
            - HOLD
            - QUEUED
            - APPROVED
            - CANCELLED
            - FULFILLED
            - RETURNED
      description: 'Object: information about the payment transaction'
  securitySchemes:
    basicAuth:
      type: http
      description: Basic Authentication Username & Password
      scheme: basic
