openapi: 3.1.0
info:
  title: Payments API
  description: >
    The Payments API provides a single, secure interface for accepting and
    managing payments across credit cards, ACH transfers, and Apple Pay. It is
    designed to simplify integration, reduce risk, and give your team consistent
    tools for handling every stage of the payment lifecycle.


    The Payments API follows modern REST conventions and uses JSON for requests
    and responses, making it straightforward to integrate from any language or
    platform. A single endpoint and a shared field model mean you can start with
    one payment type and expand to others with minimal additional development.


    **Built-In Security and Compliance**


    Security and compliance are built in. Tokenization protects sensitive data
    and aligns with the latest PCI DSS and Nacha security standards. Because
    payment details never touch your servers, a merchant’s compliance scope is
    reduced, and cardholder or account data is safeguarded.


    **Key Features**


    - Data masking to protect sensitive information during processing and
    storage.

    - Rate limiting to ensure reliability, control usage, and mitigate fraud.

    - Field-level validation to catch errors in real time, reduce declines, and
    improve the user experience.
  version: 1.0.27
servers:
  - url: https://api.uat.nelnetpay.com/payments-api
    description: UAT
security:
  - bearerAuth: []
paths:
  /payments:
    post:
      summary: Process a Payment Request
      description: >-
        Perform a request to process a payment. 


        This endpoint uses a valid Bearer Authentication API Key ID and HMAC Key
        for authentication.
      operationId: processPaymentRequest
      parameters:
        - name: nps-trace-uuid
          in: header
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            examples:
              ACH Request:
                description: ACH Request
                value:
                  entityId: 1325691045
                  paymentType:
                    ach:
                      bankAccount:
                        accountNumber: 459887746321Z
                        routingNumber: '021000021'
                        accountType: CHECKING
                  transactionType: ACH_DEBIT
                  amount: 123.65
                  accountHolder:
                    accountHolderName: John Smith
                    accountHolderId: '134267'
                  transactionInformation:
                    customId: 330d4c38-7904-47cf-be8e-0972a93f7386
                    description: tuition
                    additionalPaymentInformation: U00102
                    companyName: College Prep
                    companyDiscretionaryData: Test1234
                    standardEntryCode: WEB
                    terminalCity: MPLS
                    terminalState: MN
                    discretionaryData: R
                    effectiveEntryDate: '250110'
                    originalTransactionType: ''
                    originalPaymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                  riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
              Credit Card Request:
                description: Credit Card Request
                value:
                  entityId: 1325691045
                  paymentType:
                    creditCard:
                      token: 4NTSIT839d9b1234
                      card:
                        expiration: '1227'
                        cardVerificationValue: '123'
                  transactionType: AUTH_ONLY
                  amount: 123.65
                  accountHolder:
                    accountHolderName: John Smith
                    ipAddress: 10.101.101.101
                    billing:
                      address:
                        addressLine1: 123 Smith Ave
                        addressLine2: Suite 201
                        postalCode: '11201'
                    registeredUserIndicator: 'YES'
                    lastRegisteredDate: 05/20/2025
                  payfac:
                    payfacId: '7213'
                    payfacName: ABC
                    subMerchant:
                      name: Prep School
                      id: '341334'
                      address:
                        city: Omaha
                        stateCode: NE
                        countryCode: USA
                        postalCode: '68102'
                      emailAddress: test@abc.com
                      phoneNumber: '4021234567'
                    acceptor:
                      address:
                        addressLine1: 123 Smith Ave
                      phoneNumber: '4021234569'
                      customerServicePhoneNumber: '4021234568'
                    isoIdentifier: '12346'
                  credentialsOnFile:
                    paymentInitiator: ACCOUNTHOLDER
                    credentialsOnFileType: RECURRING
                    sourceEntityParams:
                      params:
                        - name1: value1
                        - name2: value2
                      multiMerchantRecurringLinkId: '12345'
                  transactionInformation:
                    customId: 330d4c38-7904-47cf-be8e-0972a93f7386
                    orderNumber: '652367'
                    softDescriptor: ABC Company
                    originalPaymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    externalReferenceId: 1749af67-40ff-436d-940a-a7ad3ff74059
                  additionalAmount:
                    - amountType: SURCHARGE
                      amountValue: 3.65
                  riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
              Apple Pay with Encrypted Payment Data:
                description: Apple Pay with Encrypted Payment Data
                value:
                  entityId: 1325691045
                  paymentType:
                    applePay:
                      encryptedData:
                        data: >-
                          6b2xlM8Lh/dSF+9jBqel7A6sdh6B2NJjp6wLbt/jMdLzbnCSKdWPwlSDaKR9j472IpEIijjkKAh+9ynMlS4=
                        ephemeralPublicKey: >-
                          MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGRNcOcPdTxd4GKiSMvyngGf31Hx3V
                        publicKeyHash: lRY9u8sMTf5Ezb4LoqSV6+70Q2fxbLZjFhJ/Lk+PgWI=
                        transactionId: dbb972ab5b3eab30072d886b1ef415f92a814204
                        signature: >-
                          MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhk
                        version: EC_v1
                      card:
                        network: Visa
                        category: credit
                        displayName: Visa 0224
                  transactionType: AUTH_ONLY
                  amount: 123.65
                  accountHolder:
                    accountHolderName: John Smith
                    ipAddress: 10.101.101.101
                    billing:
                      address:
                        addressLine1: 123 Smith Ave
                        addressLine2: Suite 201
                        postalCode: '11201'
                    registeredUserIndicator: 'YES'
                    lastRegisteredDate: 05/20/2025
                  payfac:
                    payfacId: '7213'
                    payfacName: ABC
                    subMerchant:
                      name: Prep School
                      id: '341334'
                      address:
                        city: Omaha
                        stateCode: NE
                        countryCode: USA
                        postalCode: '68102'
                      emailAddress: test@abc.com
                      phoneNumber: '4021234567'
                    acceptor:
                      address:
                        addressLine1: 123 Smith Ave
                      phoneNumber: '4021234569'
                      customerServicePhoneNumber: '4021234568'
                    isoIdentifier: '12346'
                  credentialsOnFile:
                    paymentInitiator: ACCOUNTHOLDER
                    credentialsOnFileType: RECURRING
                    sourceEntityParams:
                      params:
                        - name1: value1
                        - name2: value2
                      multiMerchantRecurringLinkId: '12345'
                  transactionInformation:
                    customId: 330d4c38-7904-47cf-be8e-0972a93f7386
                    orderNumber: '652367'
                    softDescriptor: ABC Company
                    originalPaymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    externalReferenceId: 1749af67-40ff-436d-940a-a7ad3ff74059
                  additionalAmount:
                    - amountType: SURCHARGE
                      amountValue: 3.65
                  riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
              Apple Pay with NPS Token:
                description: Apple Pay with NPS Token
                value:
                  entityId: 1325691045
                  paymentType:
                    applePay:
                      token: 4NTSIT839d9b1234
                      card:
                        expiration: '1227'
                  transactionType: AUTH_ONLY
                  amount: 123.65
                  accountHolder:
                    accountHolderName: John Smith
                    ipAddress: 10.101.101.101
                    billing:
                      address:
                        addressLine1: 123 Smith Ave
                        addressLine2: Suite 201
                        postalCode: '11201'
                    registeredUserIndicator: 'YES'
                    lastRegisteredDate: 05/20/2025
                  payfac:
                    payfacId: '7213'
                    payfacName: ABC
                    subMerchant:
                      name: Prep School
                      id: '341334'
                      address:
                        city: Omaha
                        stateCode: NE
                        countryCode: USA
                        postalCode: '68102'
                      emailAddress: test@abc.com
                      phoneNumber: '4021234567'
                    acceptor:
                      address:
                        addressLine1: 123 Smith Ave
                      phoneNumber: '4021234569'
                      customerServicePhoneNumber: '4021234568'
                    isoIdentifier: '12346'
                  credentialsOnFile:
                    paymentInitiator: ACCOUNTHOLDER
                    credentialsOnFileType: RECURRING
                    sourceEntityParams:
                      params:
                        - name1: value1
                        - name2: value2
                      multiMerchantRecurringLinkId: '12345'
                  transactionInformation:
                    customId: 330d4c38-7904-47cf-be8e-0972a93f7386
                    orderNumber: '652367'
                    softDescriptor: ABC Company
                    originalPaymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    externalReferenceId: 1749af67-40ff-436d-940a-a7ad3ff74059
                  additionalAmount:
                    - amountType: SURCHARGE
                      amountValue: 3.65
                  riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    AccountValidationResult:
      type: object
      properties:
        responseCode:
          type: string
          description: >-
            Account validation return code which indicates if ACH validation was
            performed.
          example: '1'
        thirdPartyResponseCode:
          type: string
          description: >-
            The third-party return code, which provides additional information
            about the validation response.
          example: '2'
        bankName:
          type: string
          description: The name of the bank received in the validation response.
          example: UB Bank
    AchResponseData:
      type: object
      properties:
        token:
          type: string
          description: NPS defined token.
          example: 4NTSIT839d9b1234
        bankAccount:
          $ref: '#/components/schemas/BankAccountResponseData'
          description: Bank account related information.
    BankAccountResponseData:
      type: object
      properties:
        lastFour:
          type: string
          description: Last 4 digits of an account number.
          example: '9999'
    CardResponseData:
      type: object
      properties:
        expiration:
          type: string
          description: |2
                The card expiration date with a two-digit month and two-digit year.

                Format Type: Numeric

                Date Format: MMYY
          example: '1227'
        lastFour:
          type: string
          description: Last 4 digits of an account number or PAN.
          example: '1224'
        network:
          type: string
          description: |2
                The card payment network.

                Format type: String

                e.g. VISA
          example: VISA
        category:
          type: string
          description: |2
                Card category.

                Format type: String

                e.g.

                CREDIT

                DEBIT
          example: credit
        isInternational:
          type: boolean
          description: Indicates if this is international relative to US.
          example: false
    CreditCardResponseData:
      type: object
      properties:
        token:
          type: string
          description: NPS defined token.
          example: 4NTSIT839d9b1234
        card:
          $ref: '#/components/schemas/CardResponseData'
          description: Card related information.
    PaymentResponse:
      type: object
      properties:
        responseCode:
          type: string
          description: |2
                Response code defined by NPS indicating status of request.

                Format Type: Alphanumeric

                Length: 4 to 5
          example: A100
          maxLength: 5
          minLength: 4
        responseMessage:
          type: string
          description: The text description of the response code.
          example: Approved
        paymentTransactionId:
          type: string
          description: |2
                Unique transaction identifier. This value is used when sending a subsequent transaction such as a Capture or Refund.

                Format Type: UUID

                Length: 36
          example: 80503dc9-15f8-430a-8622-3cff38124bbd
          maxLength: 36
          minLength: 36
        paymentType:
          $ref: '#/components/schemas/PaymentTypeResponse'
          description: Indicates the type of payment.
        accountValidationResult:
          $ref: '#/components/schemas/AccountValidationResult'
          description: >-
            The ACH account validation return code, which indicates if ACH
            validation was performed.
        processorResponse:
          $ref: '#/components/schemas/ProcessorResponseData'
          description: Response returned by processor.
        riskResponse:
          $ref: '#/components/schemas/RiskResponse'
          description: >-
            Response returned by the Risk Service if the service was invoked
            during processing the payment.
      title: Payment Response
    PaymentTypeResponse:
      type: object
      properties:
        ach:
          $ref: '#/components/schemas/AchResponseData'
          description: Used to identify the ACH payment type.
        creditCard:
          $ref: '#/components/schemas/CreditCardResponseData'
          description: Used to identify the credit card payment type.
        applePay:
          $ref: '#/components/schemas/CreditCardResponseData'
          description: Used to identify the Apple Pay payment type.
    ProcessorResponseData:
      type: object
      properties:
        responseCode:
          type: string
          description: |2
                Response code returned by processor indicating status of request.

                Format Type: Alphanumeric
          example: A0000
        responseMessage:
          type: string
          description: |2
                Response message returned by processor indicating status of request.

                Format Type: String
          example: Success
        authorizationCode:
          type: string
          description: |2
                The authorization code returned by the processor for the transaction.

                Format Type: Alphanumeric
          example: TAS890
        avsResultCode:
          type: string
          description: |2
                The Address Verification Service (AVS) result code.

                Format Type: String
          example: Z
        cvvResultCode:
          type: string
          description: |2
                The card security code verification (CVV2) response returned by the processor.

                Format Type: Alphanumeric
          example: M
        processedAmount:
          type: number
          description: |2
                The dollar amount of the transaction that was processed by the processor. This amount can be different than the amount that was sent in the request.

                Format Type: BigDecimal
          example: 123.65
        processorTransactionId:
          type: string
          description: The processor-generated unique identifier for a transaction.
          example: '49510555'
        processorTransactionType:
          type: string
          description: The transaction type sent to the processor.
          example: Sale
    RiskResponse:
      type: object
      properties:
        responseCode:
          type: string
          description: |2
                Format Type: Alphanumeric

                Length: 1 to 5
          example: '0'
          maxLength: 5
          minLength: 1
        riskId:
          type: string
          description: Unique ID returned by the Risk Service.
          example: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
        data:
          $ref: '#/components/schemas/RiskResponseData'
          description: Additional details on risk scoring functionality.
    RiskResponseData:
      type: object
      properties:
        thirdPartyId:
          type: string
          description: Unique ID returned by third party provider.
          example: 12e3cdacd347-4564-ba1f305e5e1e8ded
        riskScore:
          type: integer
          format: int32
          description: |2
                Risk score, on a scale from 0 (low risk) to 100 (high risk).

                Type: Number
          example: 50
          maximum: 100
          minimum: 0
        tags:
          type: array
          description: List of all rules triggered by the Risk Service.
          items:
            $ref: '#/components/schemas/Tag'
    Tag:
      type: object
      properties:
        action:
          type: string
          description: |2
                The action related to the rule.

                Type: String

                Example: cancelled, queued, monitored, approved
          example: approved
        name:
          type: string
          description: |2
                Name of the tag(rule/label) that is triggered.

                Type: String

                Example: Billing Country = RU Fails
          example: MaxTransactionAmt=>100
        type:
          type: string
          description: |2
                Source of the tag.

                Type: String

                Examples: rule, label, queue, workflow
          example: rule
        state:
          type: string
          description: |2
                The name of the rule set.

                Type: String

                Example: Global Rule Set
          example: Override Rule Set
    AcceptorAddressData:
      type: object
      properties:
        addressLine1:
          type: string
          description: |2
                The street address at the acceptor (sub-merchant) should include street number, street name, and other identifiers of the precise location, such as a building or unit number.

                Format Type: Alphanumeric, allows limited special characters: `A-Zaz0-9 @$+!-{}[]'\"?|-~`*()/`.

                Length: 25
          example: 123 Smith Ave
          maxLength: 25
          minLength: 1
    AcceptorData:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AcceptorAddressData'
          description: This contains address fields of the acceptor (sub-merchant).
        phoneNumber:
          type: string
          description: |2
                The business phone number of the acceptor (sub-merchant).

                Format Type:

                Alphanumeric, allowed characters: 0-9 A-Z a-z

                Length: 16
          example: '4021234569'
          maxLength: 16
          minLength: 1
        customerServicePhoneNumber:
          type: string
          description: |2
                The customer service phone number of the acceptor (sub-merchant) to use for cardholder transaction inquiries.

                Format Type:

                Alphanumeric, allowed characters: 0-9 A-Z a-z

                Length: 16
          example: '4021234568'
          maxLength: 16
          minLength: 1
    AccountHolderData:
      type: object
      properties:
        accountHolderName:
          type: string
          description: |2
                Name of the cardholder or payees' name on the ACH payment.

                Format Type: Alphanumeric

                Length: 2 to 30
          example: John Smith
          maxLength: 30
          minLength: 2
        accountHolderId:
          type: string
          description: |2
                ID representing employee or customer. Required field on ACH payments for `standardEntryCode`: `ARC`, `BOC` and `POP`.

                    Format Type:
                    - Alphanumeric for `standardEntryCode`: `CCD`, `PPD`, `TEL` and `WEB`.
                    - Numeric for `standardEntryCode`: `ARC`, `BOC` and `POP`.

                Length:
                - 15 for `standardEntryCode`: `CCD`, `PPD`, `TEL`, `ARC`, `BOC` and `WEB`.
                - 9 for `standardEntryCode`: `POP`
          example: '134267'
        ipAddress:
          type: string
          description: >-
            IP address of the account holder performing the transaction. Provide
            if the transaction is an internet payment.
          example: 10.101.101.101
        billing:
          $ref: '#/components/schemas/BillingData'
          description: >-
            The account holder's billing address and ZIP Code used for Address
            Verification Service (AVS) requests.
        registeredUserIndicator:
          type: string
          description: >-
            Indicates if the account holder is a registered user of the
            merchant's system. The indicator should be provided for Discover
            transactions.
          enum:
            - 'YES'
            - 'NO'
          example: 'YES'
        lastRegisteredDate:
          type: string
          description: |2
                The date when the account holder last voluntarily changed their registered/stored profile and not due to a merchant change policy. Required if `registeredUserIndicator` is Yes.

                Date format: MM/DD/YYYY
          example: 05/20/2025
    AchRequestData:
      type: object
      properties:
        token:
          type: string
          description: >-
            Allows the merchant to send a payment on a token instead of an
            account number or PAN (required for card payments).
          example: 4NTSIT839d9b1234
        bankAccount:
          $ref: '#/components/schemas/BankAccountRequestData'
          description: Bank account related information.
    AdditionalAmountData:
      type: object
      properties:
        amountType:
          type: string
          description: Indicates type of additional amount.
          enum:
            - SURCHARGE
          example: SURCHARGE
        amountValue:
          type: number
          description: Amount in BigDecimal.
          example: 3.65
    AddressData:
      type: object
      properties:
        addressLine1:
          type: string
          description: |2
                First line of address.

                Length: 200
          example: 123 Smith Ave
          maxLength: 200
          minLength: 1
        addressLine2:
          type: string
          description: |2
                Second line of address (if present).

                Length: 200
          example: Suite 201
          maxLength: 200
          minLength: 1
        postalCode:
          type: string
          description: |2
                ZIP Code.

                Format Type: Alphanumeric, space, hyphen

                Length: 2 to 15
          example: '11201'
          maxLength: 15
          minLength: 2
    ApplePayCardData:
      type: object
      properties:
        network:
          type: string
          description: |2
                The card payment network. Required for Apple Pay payment.

                Format type: String
          example: Visa
        category:
          type: string
          description: |2
                The card product category. Required for Apple Pay payment.

                Format type: String
          example: credit
        displayName:
          type: string
          description: |2
                Identifies the card the user selected from their wallet for the Apple Pay transaction. The display name for credit and debit cards often includes the card brand and the last four digits of the credit card.

                However, there is no standard format for the content of the display name.

                Format type: String
          example: Visa 0224
        expiration:
          type: string
          description: |2
                The card expiration date with a two-digit month and two-digit year.

                Format Type: Numeric

                Date Format: MMYY
          example: '1227'
    ApplePayEncryptedData:
      type: object
      properties:
        data:
          type: string
          description: |2
                Format type: Payment data dictionary, Base64 encoded as a string.

                Length: 8000
          example: >-
            6b2xlM8Lh/dSF+9jBqel7A6sdh6B2NJjp6wLbt/jMdLzbnCSKdWPwlSDaKR9j472IpEIijjkKAh+9ynMlS4=
          maxLength: 8000
          minLength: 1
        ephemeralPublicKey:
          type: string
          description: |2
                Ephemeral public key bytes. EC_v1 only.

                Format type: X.509 encoded key bytes, Base64 encoded as a string as returned by Apple
          example: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGRNcOcPdTxd4GKiSMvyngGf31Hx3V
        publicKeyHash:
          type: string
          description: |2
                Hash of the X.509 encoded public key bytes of the merchant's certificate.

                Format type: SHA-256 hash, Base64 encoded as a string
          example: lRY9u8sMTf5Ezb4LoqSV6+70Q2fxbLZjFhJ/Lk+PgWI=
        transactionId:
          type: string
          description: |2
                Transaction identifier generated on the device.

                Format type: A hexadecimal identifier, as a string
          example: dbb972ab5b3eab30072d886b1ef415f92a814204
        signature:
          type: string
          description: |2
                Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.

                Format type: Detached PKCS #7 signature, Base64 encoded as string
          example: MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhk
        version:
          type: string
          description: |2
                Version information about the payment token. The token uses EC_v1 for ECC-encrypted data and RSA_v1 for RSA-encrypted data.

                Format type: String
          example: EC_v1
      required:
        - data
        - ephemeralPublicKey
        - publicKeyHash
        - signature
        - transactionId
        - version
    ApplePayRequestData:
      type: object
      properties:
        encryptedData:
          $ref: '#/components/schemas/ApplePayEncryptedData'
          description: Encrypted payment data fields returned by Apple.
        token:
          type: string
          description: >-
            Allows the merchant to send a payment on a token instead of an
            account number or PAN (required for card payments).
          example: 4NTSIT839d9b1234
        card:
          $ref: '#/components/schemas/ApplePayCardData'
          description: Card payment information.
    BankAccountRequestData:
      type: object
      properties:
        accountNumber:
          type: string
          description: |2
                The bank account number for the payee.

                Format Type: Alphanumeric

                Length: 17
          example: 459887746321Z
          maxLength: 17
          minLength: 1
        routingNumber:
          type: string
          description: |2
                The bank routing number for the payee.

                Format Type: Numeric
          example: '021000021'
        accountType:
          type: string
          description: The type of bank account.
          enum:
            - CHECKING
            - SAVINGS
          example: CHECKING
    BillingData:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressData'
          description: >-
            This group contains fields used to request Address Verification
            Service (AVS).
    CardData:
      type: object
      properties:
        expiration:
          type: string
          description: |2
                The card expiration date with a two-digit month and two-digit year.

                Format Type: Numeric

                Date Format: MMYY
          example: '1227'
        cardVerificationValue:
          type: string
          description: |2
                The three- or four-digit security code printed on the credit card.

                Format Type: Numeric

                Length: 4
          example: '123'
          maxLength: 4
          minLength: 3
      required:
        - expiration
    CredentialsOnFileData:
      type: object
      properties:
        paymentInitiator:
          type: string
          description: The initiator of the transaction.
          enum:
            - ACCOUNTHOLDER
            - MERCHANT
          example: ACCOUNTHOLDER
        credentialsOnFileType:
          type: string
          description: The stored credential transaction type.
          enum:
            - RECURRING
          example: RECURRING
        sourceEntityParams:
          $ref: '#/components/schemas/SourceEntityParamsData'
          description: >-
            This field is used to group a set of recurring transactions
            together. You can provide any name/value pairs as needed.
    CreditCardRequestData:
      type: object
      properties:
        token:
          type: string
          description: >-
            Allows the merchant to send a payment on a token instead of an
            account number or PAN (required for card payments).
          example: 4NTSIT839d9b1234
        card:
          $ref: '#/components/schemas/CardData'
          description: Card payment information.
    PayfacData:
      type: object
      properties:
        payfacId:
          type: string
          description: |2
                The card brand-assigned identifier representing the payment facilitator (required for PayFac transactions).

                Format Type: Numeric

                Length: 1 to 20
          example: '7213'
          maxLength: 20
          minLength: 1
        payfacName:
          type: string
          description: |2
                The payment facilitator's name registered with the card brand (required if `payfacId` is provided).

                Length: 1 to 12
          example: ABC
          maxLength: 12
          minLength: 1
        isoIdentifier:
          type: string
          description: |2
                The card brand-assigned identifier representing the ISO. Contact NPS Client Services before sending information in this field.

                Length: 1 to 11
          example: '12346'
          maxLength: 11
          minLength: 1
        subMerchant:
          $ref: '#/components/schemas/SubMerchantData'
          description: >-
            Information about the sub-merchant. All sub-merchant fields are
            required if `payfacId` is provided.
        acceptor:
          $ref: '#/components/schemas/AcceptorData'
          description: >-
            Acceptor (sub-merchant) information. All acceptor fields are
            recommended if `payfacId` is provided.
    PaymentRequest:
      type: object
      properties:
        entityId:
          type: integer
          format: int64
          description: A unique ID assigned by NPS that represents the client.
          example: 1325691045
        paymentType:
          $ref: '#/components/schemas/PaymentType'
          description: Indicates the type of payment. Only one type of payment is allowed.
        transactionType:
          type: string
          description: Indicates the type of transaction.
          enum:
            - AUTH_ONLY
            - CAPTURE
            - SALE
            - REFUND
            - VERIFY
            - VOID
            - CANCEL
            - ACH_DEBIT
            - ACH_CREDIT
            - ACH_CANCEL
            - ACH_PRENOTE_CREDIT
            - ACH_PRENOTE_DEBIT
          example: AUTH_ONLY
        amount:
          type: number
          description: Amount of the transaction in BigDecimal.
          example: 123.65
        accountHolder:
          $ref: '#/components/schemas/AccountHolderData'
          description: Account holder details.
        transactionInformation:
          $ref: '#/components/schemas/TransactionInformationData'
          description: Additional information about the transaction.
        payfac:
          $ref: '#/components/schemas/PayfacData'
          description: >-
            Information about the payment facilitator. Contact NPS Client
            Services before sending information in this field.
        credentialsOnFile:
          $ref: '#/components/schemas/CredentialsOnFileData'
          description: >-
            Information for stored card transactions. Required to be sent only
            for recurring transactions.
        additionalAmount:
          type: array
          description: >-
            Additional amount that is added to the amount of the cardholder's
            original transaction.
          items:
            $ref: '#/components/schemas/AdditionalAmountData'
        riskId:
          type: string
          description: A unique ID returned by the Risk Service.
          example: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
        processingMode:
          type: string
          description: |2
                Mandatory for ACH transactions.

                For transactions where the merchant sets the `processingMode` field value to `SYNCHRONOUS`, we will process these transactions in real-time using existing flows.

                For transactions where the merchant sets the `processingMode` field value to `ASYNCHRONOUS`, we will process these transactions asynchronously.

                We will queue the transaction for processing later.

                Format Type: String
          enum:
            - SYNCHRONOUS
            - ASYNCHRONOUS
          example: SYNCHRONOUS
      required:
        - entityId
        - paymentType
        - transactionType
      title: Payment Request
    PaymentType:
      type: object
      properties:
        ach:
          $ref: '#/components/schemas/AchRequestData'
          description: Used to identify the ACH payment type.
        creditCard:
          $ref: '#/components/schemas/CreditCardRequestData'
          description: Used to identify the credit card payment type.
        applePay:
          $ref: '#/components/schemas/ApplePayRequestData'
          description: >-
            Used to identify the Apple Pay payment type. Either `encryptedData`
            or `token` needs to be provided.
    SourceEntityParamsData:
      type: object
      properties:
        params:
          type: array
          items:
            description: Array of name/value pairs.
            example:
              - name1: value1
              - name2: value2
        multiMerchantRecurringLinkId:
          type: string
          description: |2
                Identifier for a recurring payment series involving multiple merchants.

                **Required** if the series spans multiple merchants.

                Currently supported only when `paymentType` is `applePay`.
          example: '12345'
    SubMerchantAddressData:
      type: object
      properties:
        city:
          type: string
          description: |2
                The sub-merchant's city.

                Length: 1 to 50
          example: Omaha
          maxLength: 50
          minLength: 1
        stateCode:
          type: string
          description: |2
                The sub-merchant's state code.

                Format: ISO 3166-2
          example: NE
        countryCode:
          type: string
          description: |2
                The sub-merchant's country code.

                Format: ISO 3166-1 alpha-2 or alpha-3
          example: USA
        postalCode:
          type: string
          description: |2
                The sub-merchant's ZIP Code.

                Length: 2 to 15
          example: '68102'
          maxLength: 15
          minLength: 2
    SubMerchantData:
      type: object
      properties:
        name:
          type: string
          description: |2
                The sub-merchant's name.

                Length: 1 to 25
          example: Prep School
          maxLength: 25
          minLength: 1
        id:
          type: string
          description: |2
                A unique sub-merchant identifier.

                Format Type: Numeric

                Length: 1 to 15
          example: '341334'
          maxLength: 15
          minLength: 1
        address:
          $ref: '#/components/schemas/SubMerchantAddressData'
          description: The sub-merchant's address.
        emailAddress:
          type: string
          description: |2
                The sub-merchant's email address.

                Length: 6 to 128
          example: test@abc.com
          maxLength: 128
          minLength: 6
        phoneNumber:
          type: string
          description: |2
                The sub-merchant's phone number.

                Format Type: Numeric

                Length: 4 to 15
          example: '4021234567'
          maxLength: 15
          minLength: 4
    TransactionInformationData:
      type: object
      properties:
        customId:
          type: string
          description: |2
                A value the merchant can set to uniquely identify the transaction on screens and reports.

                ACH Customers: If you are enabled to use the ACH Duplicate Check option, this field is required.

                Length: 2 to 100
          example: 330d4c38-7904-47cf-be8e-0972a93f7386
          maxLength: 100
          minLength: 2
        orderNumber:
          type: string
          description: |2+
                The transaction invoice or order number for a card payment.

                Note: Although this element is not required, it is preferred to send. Some processors require this field for card-not-present transactions.

                Length: 2 to 30

          example: '652367'
          maxLength: 30
          minLength: 2
        softDescriptor:
          type: string
          description: |2
                The descriptive text on the cardholder's statement that identifies the transaction or describes the purchase or merchant. Contact NPS Client Services before submitting this field.

                Format Type: Alphanumeric, allowed special characters: `@()/.':$,*-`

                Length: 1 to 25
          example: ABC Company
          maxLength: 25
          minLength: 1
        externalReferenceId:
          type: string
          description: |2
                A unique identifier representing the transaction in the processor's system.

                Format Type: Alphanumeric/non-ASCII characters are not allowed.

                Length: 2 to 100
          example: 1749af67-40ff-436d-940a-a7ad3ff74059
          maxLength: 100
          minLength: 2
        originalPaymentTransactionId:
          type: string
          description: >+
            Identifies the original transaction being referenced. The
            requirement for this field depends on the `transactionType`.


            #### Card Transactions

            - **Required** when `transactionType` is `CAPTURE`, `CANCEL`, or
            `VOID`:

            Use the `paymentTransactionId` from the original card transaction.

            - **Recommended** when `transactionType` is `REFUND`:

            Use the `paymentTransactionId` from the original card transaction if
            available.


            #### ACH Transactions

            - **Required** when `transactionType` is `ACH_CREDIT`:

            Use the `paymentTransactionId` from the original `ACH_DEBIT`
            transaction.

            - **Required** when `transactionType` is `ACH_CANCEL`:

            Use the `paymentTransactionId` from the original transaction being
            cancelled.

          example: 80503dc9-15f8-430a-8622-3cff38124bbd
        description:
          type: string
          description: |2
                A brief description of the ACH payment that will post to the payees' statement.

                Format Type: String/non-ASCII characters are not allowed.

                Length: 10
          example: tuition
          maxLength: 10
          minLength: 1
        companyName:
          type: string
          description: |2
                The merchant's company name for the ACH payment. Because this value is limited to 16 characters, it may be the truncated version of the merchant's company name.

                Format Type: String/non-ASCII characters are not allowed.

                Length: 16
          example: College Prep
          maxLength: 16
          minLength: 1
        companyDiscretionaryData:
          type: string
          description: |2
                Additional information about the merchant's company. Information entered in this field will not appear on the payees' statement.

                Format Type: String/non-ASCII characters are not allowed.
          example: Test1234
        originalTransactionType:
          type: string
          description: >-
            When the `transactionType` is set to `ACH_CANCEL`, this must be the
            `transactionType` of `originalPaymentTransactionId`.
          example: ACH_CREDIT
        additionalPaymentInformation:
          type: string
          description: |2
                Additional information about the ACH payment. Information entered in this field will be given to the payees' bank.

                Format Type: Alphanumeric

                Length: 80

                Note: Optional for `standardEntryCode` `CCD`, `PPD` and `WEB`. Must be blank for `ARC`, `BOC` and `TEL`.
          example: U00102
          maxLength: 80
          minLength: 1
        standardEntryCode:
          type: string
          description: >-
            The type of authorization for the merchant's payment from the
            client. Required field for ACH payments.
          enum:
            - ARC
            - BOC
            - CCD
            - PPD
            - TEL
            - WEB
            - POP
          example: WEB
        terminalCity:
          type: string
          description: |2
                A four-character name or abbreviation of the terminal city location for an ACH payment. This field is required for `standardEntryCode` `POP`.

                Format Type: Alphanumeric

                Length: 4
          example: MPLS
          maxLength: 4
          minLength: 1
        terminalState:
          type: string
          description: |2
                A two-character abbreviation of the terminal state location for an ACH payment. This field is required for `standardEntryCode` `POP`.

                Format Type: Alphanumeric

                Length: 2
          example: MN
          maxLength: 2
          minLength: 1
        discretionaryData:
          type: string
          description: >-
            If you are using `standardEntryCode` `TEL` or `WEB`, either `S`
            indicating a single debit or `R` representing a recurring debit ACH
            payment. For all other `standardEntryCode` values and credit
            `transactionType`, this data must be omitted.
          enum:
            - S
            - R
          example: R
        effectiveEntryDate:
          type: string
          description: |2
                The date the transaction should be settled. The effective date should not be a Saturday, Sunday, or banking holiday. Contact NPS Client Services before submitting this field.

                Format Type: String/Date format of YYMMDD

                Length: 6
          example: '250110'
          maxLength: 6
          minLength: 6
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        '*/*':
          schema:
            type: string
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              responseCode:
                type: string
                example: '500'
              responseMessage:
                type: string
                example: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      description: Bearer Authentication Token for /payments endpoint
      scheme: bearer
      bearerFormat: JWT
