openapi: 3.1.0
info:
  title: Payments API v3
  description: The Payments API is used to send payment requests to process transactions.
  version: 2025.5.1.0
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: processAchRequest
      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 Doe
                    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 Doe
                    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
                    sourceEntityParam:
                      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=
                        ephimeralPublicKey: >-
                          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 Doe
                    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
                    sourceEntityParam:
                      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 Doe
                    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
                    sourceEntityParam:
                      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'
              examples:
                Ach Response:
                  description: Ach Response
                  value:
                    responseCode: A100
                    responseMessage: Approved
                    paymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    paymentType:
                      ach:
                        token: 4NTSIT839d9b1234
                        bankAccount:
                          lastFour: '9999'
                    riskResponse:
                      responseCode: '0'
                      riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
                      data:
                        thirdPartyId: 12e3cdacd347-4564-ba1f305e5e1e8ded
                        riskScore: 50
                        tags:
                          - action: approved
                            name: MaxTransactionAmt=>100
                            type: rule
                            state: Override Rule Set
                    accountValidationResult:
                      responseCode: '1'
                      thirdPartyResponseCode: '2'
                      bankName: UB Bank
                CC/Apple Pay Success Response:
                  description: CC/Apple Pay Success Response
                  value:
                    responseCode: A100
                    responseMessage: Approved
                    paymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    paymentType:
                      creditCard:
                        token: 4NTSIT839d9b1234
                        card:
                          expiration: '1227'
                          lastFour: '1224'
                          network: visa
                          category: credit
                          isInternational: false
                    processorResponse:
                      responseCode: A0000
                      responseMessage: Success
                      authorizationCode: TAS890
                      avsResultCode: Z
                      cvvResultCode: M
                      processedAmount: 123.65
                      processorTransactionId: '49510555'
                      processorTransactionType: Sale
                    riskResponse:
                      responseCode: '0'
                      riskId: 12e3cdac-d347-4564-ba1f-305e5e1e8ded
                      data:
                        thirdPartyId: 12e3cdacd347-4564-ba1f305e5e1e8ded
                        riskScore: 50
                        tags:
                          - action: approved
                            name: MaxTransactionAmt=>100
                            type: rule
                            state: Override Rule Set
                CC/Apple Pay Failure Response:
                  description: CC/Apple Pay Failure Response
                  value:
                    responseCode: D202
                    responseMessage: Insufficient Funds
                    paymentTransactionId: 80503dc9-15f8-430a-8622-3cff38124bbd
                    paymentType:
                      creditCard:
                        token: 4NTSIT839d9b1234
                        card:
                          expiration: '1227'
                          lastFour: '1224'
                          network: visa
                          category: credit
                          isInternational: false
                    processorResponse:
                      responseCode: D9901
                      responseMessage: Insufficient Funds
                      processedAmount: 123.65
                      processorTransactionType: Sale
                CC/Apple Pay Validation Failure Response:
                  description: CC/Apple Pay Validation Failure Response
                  value:
                    responseCode: E100
                    responseMessage: Invalid Request - Unsupported transaction type
                    paymentType:
                      creditCard:
                        token: 4NTSIT839d9b1234
                        card:
                          expiration: '1227'
                          lastFour: '1224'
                          network: visa
                          category: credit
                          isInternational: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
  /payments2:
    post:
      summary: Process a Payment Request
      operationId: processRealAchRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AcceptorAddressData:
      type: object
      properties:
        addressLine1:
          type: string
          description: |2
                The street address at the acceptor (merchant), which 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-9space@$+!-{}[]'\"?|-~`*()/.

                Length: 25
          example: 123 Smith Ave
          maxLength: 25
          minLength: 1
    AcceptorData:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AcceptorAddressData'
          description: Groups address fields.
        phoneNumber:
          type: string
          description: |2
                Business phone number of the acceptor (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
                Phone number of the acceptor (merchant), which can be used for 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 ACH payment.

                Format Type: Alphanumeric

                Length: 2 to 30

                Applicable type

                Instead of ASCII word check REST encoding
          example: John Doe
          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 POP
          example: '134267'
        ipAddress:
          type: string
          description: >-
            IP address of accountholder performing the transaction. Provide if
            transaction is an internet payment.
          example: 10.101.101.101
        billing:
          $ref: '#/components/schemas/BillingData'
          description: >-
            Accountholder's billing address and zipcode used for Address
            Verification Service (AVS) requests.
        registeredUserIndicator:
          type: string
          description: >-
            Indicates if the accountholder is a registered user of the
            merchant’s system. The indicator should be provided for Discover
            transaction.
          enum:
            - 'YES'
            - 'NO'
          example: 'YES'
        lastRegisteredDate:
          type: string
          description: |2
                The date when the accountholder last changed their registered/stored profile voluntarily 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 merchant to send a payment on token instead of 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
                Zipcode.

                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 ApplePay payment.

                Format type: String
          example: Visa
        category:
          type: string
          description: |2
                The card product category. Required for ApplePay 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. For credit and debit cards, the display name often includes the card brand and the last four digits of the credit card.

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

                Format type: String
          example: Visa 0224
        expiration:
          type: string
          description: |2
                Card expiration in 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
        ephimeralPublicKey:
          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
        wrappedKey:
          type: string
          description: |2
                The symmetric key wrapped using your RSA public key. RSA_v1 only.

                Format type: A Base64 encoded string
          example: FIXME find example
        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
        - ephimeralPublicKey
        - 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 merchant to send a payment on token instead of 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: Type of bank account.
          enum:
            - CHECKING
            - SAVINGS
          example: CHECKING
    BillingData:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressData'
          description: Groups address fields.
    CardData:
      type: object
      properties:
        expiration:
          type: string
          description: |2
                Card expiration in two-digit month and two-digit year.

                Format Type: Numeric

                Date Format: MMYY
          example: '1227'
        cardVerificationValue:
          type: string
          description: |2
                Three- or four-digit security code 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: Initiator of the transaction.
          enum:
            - ACCOUNTHOLDER
            - MERCHANT
          example: ACCOUNTHOLDER
        credentialsOnFileType:
          type: string
          description: FIXME No description provided.
          enum:
            - RECURRING
          example: RECURRING
        sourceEntityParams:
          $ref: '#/components/schemas/SourceEntityParamsData'
          description: |2
                Array of name/value pairs will be utilized to group a set of recurring transactions together.

                Any values can be provided.
    CreditCardRequestData:
      type: object
      properties:
        token:
          type: string
          description: >-
            Allows merchant to send a payment on token instead of 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 Payment Facilitator Identifier. Required for Payment Facilitator transactions.

                Format Type: Numeric

                Length: 1 to 20
          example: '7213'
          maxLength: 20
          minLength: 1
        payfacName:
          type: string
          description: |2
                The Payment Facilitator’s name that is 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
                Unique identifier assigned to the ISO.

                Length: 1 to 11
          example: '12346'
          maxLength: 11
          minLength: 1
        subMerchant:
          $ref: '#/components/schemas/SubMerchantData'
          description: >-
            Sub-merchant information. All submerchant fields are required if
            payfacId is provided.
        acceptor:
          $ref: '#/components/schemas/AcceptorData'
          description: >-
            Acceptor information. All acceptor fields are required 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: Accountholder details.
        transactionInformation:
          $ref: '#/components/schemas/TransactionInformationData'
          description: Additional information about the transaction.
        payfac:
          $ref: '#/components/schemas/PayfacData'
          description: Payment Facilitator information.
        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
        accountAndRoutingRequest:
          type: boolean
      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
          description: Array of name/value pairs.
          example:
            - name1: value1
            - name2: value2
          items:
            type: object
            additionalProperties:
              type: string
        multiMerchantRecurringLinkId:
          type: string
          description: A linkId required for Apple Pay transactions.
          example: '12345'
    SubMerchantAddressData:
      type: object
      properties:
        city:
          type: string
          description: |2
                City.

                Length: 1 to 50
          example: Omaha
          maxLength: 50
          minLength: 1
        stateCode:
          type: string
          description: |2
                State code.

                Format: ISO 3166-2
          example: NE
        countryCode:
          type: string
          description: |2
                Country code.

                Format: ISO 3166-1 alpha-2 or alpha-3
          example: USA
        postalCode:
          type: string
          description: |2
                Zipcode.

                Length: 2 to 15
          example: '68102'
          maxLength: 15
          minLength: 2
    SubMerchantData:
      type: object
      properties:
        name:
          type: string
          description: |2
                Sub-merchant's name, assigned by the Payment Facilitator.

                Length: 1 to 25
          example: Prep School
          maxLength: 25
          minLength: 1
        id:
          type: string
          description: |2
                Unique sub-merchant identifier, assigned by the Payment Facilitator.

                Format Type: Numeric

                Length: 1 to 15
          example: '341334'
          maxLength: 15
          minLength: 1
        address:
          $ref: '#/components/schemas/SubMerchantAddressData'
          description: FIXME No description provided.
        emailAddress:
          type: string
          description: |2
                Email address.

                Length: 6 to 128
          example: test@abc.com
          maxLength: 128
          minLength: 6
        phoneNumber:
          type: string
          description: |2
                Phone number.

                Format Type: Numeric

                Length: 4 to 15
          example: '4021234567'
          maxLength: 15
          minLength: 4
    TransactionInformationData:
      type: object
      properties:
        customId:
          type: string
          description: |2
                Unique identifier on a transaction provided by client.

                Length: 2 to 100
          example: 330d4c38-7904-47cf-be8e-0972a93f7386
          maxLength: 100
          minLength: 2
        orderNumber:
          type: string
          description: |2
                Transaction invoice number for card payment provided by client.

                Length: 2 to 30

                Note: Although this element is not required, it is preferred to send.

                Some processors require this field for card-not-present transactions.
          example: '652367'
          maxLength: 30
          minLength: 2
        softDescriptor:
          type: string
          description: |2
                Text on cardholder's statement that identifies transaction or describes the purchase/merchant.

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

                Length: 1 to 25
          example: ABC Company
          maxLength: 25
          minLength: 1
        externalReferenceId:
          type: string
          description: |2
                Unique id to identify 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: |2
                ID of prior transaction. It’s needed on certain subsequent transactions:

                NOTE:

                When the transactionType is set to CAPTURE or REFUND, this must be included

                When the transactionType is set to ACH_CREDIT, this must be included with a valid paymentTransactionId of the ACH Debit Transaction Type.

                When the transactionType is set to ACH_CANCEL, this must be included with paymentTransactionId of the original ACH transaction.
          example: 80503dc9-15f8-430a-8622-3cff38124bbd
        description:
          type: string
          description: |2
                Brief description of the ACH payment. Will post to payee 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: >
            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 a 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 payment the merchant received from
            the client. Required field for ACH payments.
          enum:
            - ARC
            - BOC
            - CCD
            - PPD
            - TEL
            - WEB
            - POP
          example: WEB
        terminalCity:
          type: string
          description: |2
                A 4-character name or abbreviation of the terminal city location for an ACH payment. This will be displayed on the receiver’s monthly bank statement.

                Format Type: Alphanumeric

                Length: 4

                Note: Required for SEC code POP. Ignored for CCD, PPD, WEB, ARC, BOC, and TEL. In  addition, the available TerminalCity values could vary/work in conjunction with the TerminalState and StandardEntryCode elements.
          example: MPLS
          maxLength: 4
          minLength: 1
        terminalState:
          type: string
          description: |2
                A 2-character abbreviation of the terminal state location for an ACH payment. This will be displayed on the receiver’s monthly bank statement.

                Format Type: Alphanumeric

                Length: 2

                Note: Required for StandardEntryCode POP. Ignored for CCD, PPD, WEB, ARC, BOC, and TEL. In addition, the available TerminalCity values could vary/work in conjunction with the TerminalState and StandardEntryCode elements.
          example: MN
          maxLength: 2
          minLength: 1
        discretionaryData:
          type: string
          description: >-
            If you are using SECs TEL or WEB, either "S" indicating a single
            debit or "R" representing a recurring debit ACH payment. For all
            other SECs and credit transactionType, this data must be omitted.
          enum:
            - S
            - R
          example: R
        effectiveEntryDate:
          type: string
          description: |2
                Allows a user to “Post Date” an ACH transaction.

                Format Type: String/Date format of YYMMDD

                Length: 6
          example: '250110'
          maxLength: 6
          minLength: 6
    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
                Card expiration in 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: 1
        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 credit card 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 result of the address verification (AVS) performed by the issuer on the address submitted in the transactions. This value is returned by the processor.

                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
  responses:
    OK:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  status:
                    type: string
                    example: success
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: object
                properties:
                  status:
                    type: string
                    example: failure
                  error:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: '401'
                        description:
                          type: string
                          example: Unauthorized
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: object
                properties:
                  status:
                    type: string
                    example: failure
                  error:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: '400'
                        description:
                          type: string
                          example: Bad Request
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                type: object
                properties:
                  status:
                    type: string
                    example: failure
                  error:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          example: '500'
                        description:
                          type: string
                          example: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      description: Bearer Authentication Token for /payments endpoint
      scheme: bearer
      bearerFormat: JWT
