# Process a Payment Request

Perform a request to process a payment. 

This endpoint uses a valid Bearer Authentication API Key ID and HMAC Key for authentication.

Endpoint: POST /payments
Version: 1.0.5
Security: bearerAuth

## Header parameters:

  - `nps-trace-uuid` (string, required)

## Request fields (application/json):

  - `entityId` (integer, required)
    A unique ID assigned by NPS that represents the client.
    Example: 1325691045

  - `paymentType` (object, required)
    Indicates the type of payment. Only one type of payment is allowed.

  - `paymentType.ach` (object)
    Used to identify the ACH payment type.

  - `paymentType.ach.token` (string)
    Allows the merchant to send a payment on a token instead of an account number or PAN (required for card payments).
    Example: "4NTSIT839d9b1234"

  - `paymentType.ach.bankAccount` (object)
    Bank account related information.

  - `paymentType.ach.bankAccount.accountNumber` (string)
    The bank account number for the payee.

    Format Type: Alphanumeric

    Length: 17
    Example: "459887746321Z"

  - `paymentType.ach.bankAccount.routingNumber` (string)
    The bank routing number for the payee.

    Format Type: Numeric
    Example: "021000021"

  - `paymentType.ach.bankAccount.accountType` (string)
    The type of bank account.
    Enum: "CHECKING", "SAVINGS"

  - `paymentType.creditCard` (object)
    Used to identify the credit card payment type.

  - `paymentType.creditCard.card` (object)
    Card payment information.

  - `paymentType.creditCard.card.expiration` (string, required)
    The card expiration date with a two-digit month and two-digit year.

    Format Type: Numeric

    Date Format: MMYY
    Example: "1227"

  - `paymentType.creditCard.card.cardVerificationValue` (string)
    The three- or four-digit security code printed on the credit card.

    Format Type: Numeric

    Length: 4
    Example: "123"

  - `paymentType.applePay` (object)
    Used to identify the Apple Pay payment type. Either  or  needs to be provided.

  - `paymentType.applePay.encryptedData` (object)
    Encrypted payment data fields returned by Apple.

  - `paymentType.applePay.encryptedData.data` (string, required)
    Format type: Payment data dictionary, Base64 encoded as a string.

    Length: 8000
    Example: "6b2xlM8Lh/dSF+9jBqel7A6sdh6B2NJjp6wLbt/jMdLzbnCSKdWPwlSDaKR9j472IpEIijjkKAh+9ynMlS4="

  - `paymentType.applePay.encryptedData.ephimeralPublicKey` (string, required)
    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"

  - `paymentType.applePay.encryptedData.publicKeyHash` (string, required)
    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="

  - `paymentType.applePay.encryptedData.transactionId` (string, required)
    Transaction identifier generated on the device.

    Format type: A hexadecimal identifier, as a string
    Example: "dbb972ab5b3eab30072d886b1ef415f92a814204"

  - `paymentType.applePay.encryptedData.signature` (string, required)
    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"

  - `paymentType.applePay.encryptedData.version` (string, required)
    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"

  - `transactionType` (string, required)
    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"

  - `amount` (number)
    Amount of the transaction in BigDecimal.
    Example: 123.65

  - `accountHolder` (object)
    Account holder details.

  - `accountHolder.accountHolderName` (string)
    Name of the cardholder or payees' name on the ACH payment.

    Format Type: Alphanumeric

    Length: 2 to 30
    Example: "John Smith"

  - `accountHolder.accountHolderId` (string)
    ID representing employee or customer. Required field on ACH payments for : ,  and .

    Format Type:
    - Alphanumeric for : , ,  and .
    - Numeric for : ,  and .

    Length:
    - 15 for : , , , ,  and .
    - 9 for :
    Example: "134267"

  - `accountHolder.ipAddress` (string)
    IP address of the account holder performing the transaction. Provide if the transaction is an internet payment.
    Example: "10.101.101.101"

  - `accountHolder.billing` (object)
    The account holder's billing address and ZIP Code used for Address Verification Service (AVS) requests.

  - `accountHolder.billing.address` (object)
    This group contains fields used to request Address Verification Service (AVS).

  - `accountHolder.billing.address.addressLine1` (string)
    First line of address.

    Length: 200
    Example: "123 Smith Ave"

  - `accountHolder.billing.address.addressLine2` (string)
    Second line of address (if present).

    Length: 200
    Example: "Suite 201"

  - `accountHolder.billing.address.postalCode` (string)
    ZIP Code.

    Format Type: Alphanumeric, space, hyphen

    Length: 2 to 15
    Example: "11201"

  - `accountHolder.registeredUserIndicator` (string)
    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"

  - `accountHolder.lastRegisteredDate` (string)
    The date when the account holder last voluntarily changed their registered/stored profile and not due to a merchant change policy. Required if  is Yes.

    Date format: MM/DD/YYYY
    Example: "05/20/2025"

  - `transactionInformation` (object)
    Additional information about the transaction.

  - `transactionInformation.customId` (string)
    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"

  - `transactionInformation.orderNumber` (string)
    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"

  - `transactionInformation.softDescriptor` (string)
    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"

  - `transactionInformation.externalReferenceId` (string)
    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"

  - `transactionInformation.originalPaymentTransactionId` (string)
    Identifies the original transaction being referenced. The requirement for this field depends on the .

#### Card Transactions
-  when  is , , or :
Use the  from the original card transaction.
-  when  is :
Use the  from the original card transaction if available.

#### ACH Transactions
-  when  is :
Use the  from the original  transaction.
-  when  is :
Use the  from the original transaction being cancelled.
    Example: "80503dc9-15f8-430a-8622-3cff38124bbd"

  - `transactionInformation.description` (string)
    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"

  - `transactionInformation.companyName` (string)
    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"

  - `transactionInformation.companyDiscretionaryData` (string)
    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"

  - `transactionInformation.originalTransactionType` (string)
    When the  is set to , this must be the  of .
    Example: "ACH_CREDIT"

  - `transactionInformation.additionalPaymentInformation` (string)
    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  ,  and . Must be blank for ,  and .
    Example: "U00102"

  - `transactionInformation.standardEntryCode` (string)
    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"

  - `transactionInformation.terminalCity` (string)
    A four-character name or abbreviation of the terminal city location for an ACH payment. This field is required for  .

    Format Type: Alphanumeric

    Length: 4
    Example: "MPLS"

  - `transactionInformation.terminalState` (string)
    A two-character abbreviation of the terminal state location for an ACH payment. This field is required for  .

    Format Type: Alphanumeric

    Length: 2
    Example: "MN"

  - `transactionInformation.discretionaryData` (string)
    If you are using   or , either  indicating a single debit or  representing a recurring debit ACH payment. For all other  values and credit , this data must be omitted.
    Enum: "S", "R"

  - `transactionInformation.effectiveEntryDate` (string)
    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"

  - `payfac` (object)
    Information about the payment facilitator. Contact NPS Client Services before sending information in this field.

  - `payfac.payfacId` (string)
    The card brand-assigned identifier representing the payment facilitator (required for PayFac transactions).

    Format Type: Numeric

    Length: 1 to 20
    Example: "7213"

  - `payfac.payfacName` (string)
    The payment facilitator's name registered with the card brand (required if  is provided).

    Length: 1 to 12
    Example: "ABC"

  - `payfac.isoIdentifier` (string)
    The card brand-assigned identifier representing the ISO. Contact NPS Client Services before sending information in this field.

    Length: 1 to 11
    Example: "12346"

  - `payfac.subMerchant` (object)
    Information about the sub-merchant. All sub-merchant fields are required if  is provided.

  - `payfac.subMerchant.name` (string)
    The sub-merchant's name.

    Length: 1 to 25
    Example: "Prep School"

  - `payfac.subMerchant.id` (string)
    A unique sub-merchant identifier.

    Format Type: Numeric

    Length: 1 to 15
    Example: "341334"

  - `payfac.subMerchant.address` (object)
    The sub-merchant's address.

  - `payfac.subMerchant.address.city` (string)
    The sub-merchant's city.

    Length: 1 to 50
    Example: "Omaha"

  - `payfac.subMerchant.address.stateCode` (string)
    The sub-merchant's state code.

    Format: ISO 3166-2
    Example: "NE"

  - `payfac.subMerchant.address.countryCode` (string)
    The sub-merchant's country code.

    Format: ISO 3166-1 alpha-2 or alpha-3
    Example: "USA"

  - `payfac.subMerchant.address.postalCode` (string)
    The sub-merchant's ZIP Code.

    Length: 2 to 15
    Example: "68102"

  - `payfac.subMerchant.emailAddress` (string)
    The sub-merchant's email address.

    Length: 6 to 128
    Example: "test@abc.com"

  - `payfac.subMerchant.phoneNumber` (string)
    The sub-merchant's phone number.

    Format Type: Numeric

    Length: 4 to 15
    Example: "4021234567"

  - `payfac.acceptor` (object)
    Acceptor (sub-merchant) information. All acceptor fields are recommended if  is provided.

  - `payfac.acceptor.address` (object)
    This contains address fields of the acceptor (sub-merchant).

  - `payfac.acceptor.address.addressLine1` (string)
    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: *()/`.

    Length: 25
    Example: "123 Smith Ave"

  - `payfac.acceptor.phoneNumber` (string)
    The business phone number of the acceptor (sub-merchant).

    Format Type:

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

    Length: 16
    Example: "4021234569"

  - `payfac.acceptor.customerServicePhoneNumber` (string)
    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"

  - `credentialsOnFile` (object)
    Information for stored card transactions. Required to be sent only for recurring transactions.

  - `credentialsOnFile.paymentInitiator` (string)
    The initiator of the transaction.
    Enum: "ACCOUNTHOLDER", "MERCHANT"

  - `credentialsOnFile.credentialsOnFileType` (string)
    The stored credential transaction type.
    Enum: "RECURRING"

  - `credentialsOnFile.sourceEntityParams` (object)
    This field is used to group a set of recurring transactions together. You can provide any name/value pairs as needed.

  - `credentialsOnFile.sourceEntityParams.params` (array)
    Array of name/value pairs.
    Example: [{"name1":"value1"},{"name2":"value2"}]

  - `credentialsOnFile.sourceEntityParams.multiMerchantRecurringLinkId` (string)
    Identifier for a recurring payment series involving multiple merchants.

     if the series spans multiple merchants.

    Currently supported only when  is .
    Example: "12345"

  - `additionalAmount` (array)
    Additional amount that is added to the amount of the cardholder's original transaction.

  - `additionalAmount.amountType` (string)
    Indicates type of additional amount.
    Enum: "SURCHARGE"

  - `additionalAmount.amountValue` (number)
    Amount in BigDecimal.
    Example: 3.65

  - `riskId` (string)
    A unique ID returned by the Risk Service.
    Example: "12e3cdac-d347-4564-ba1f-305e5e1e8ded"

  - `processingMode` (string)
    Mandatory for ACH transactions.

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

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

    We will queue the transaction for processing later.

    Format Type: String
    Enum: "SYNCHRONOUS", "ASYNCHRONOUS"

## Response 200 fields (application/json):

  - `responseCode` (string)
    Response code defined by NPS indicating status of request.

    Format Type: Alphanumeric

    Length: 4 to 5
    Example: "A100"

  - `responseMessage` (string)
    The text description of the response code.
    Example: "Approved"

  - `paymentTransactionId` (string)
    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"

  - `paymentType` (object)
    Indicates the type of payment.

  - `paymentType.ach` (object)
    Used to identify the ACH payment type.

  - `paymentType.ach.token` (string)
    NPS defined token.
    Example: "4NTSIT839d9b1234"

  - `paymentType.ach.bankAccount` (object)
    Bank account related information.

  - `paymentType.ach.bankAccount.lastFour` (string)
    Last 4 digits of an account number.
    Example: "9999"

  - `paymentType.creditCard` (object)
    Used to identify the credit card payment type.

  - `paymentType.creditCard.card` (object)
    Card related information.

  - `paymentType.creditCard.card.expiration` (string)
    The card expiration date with a two-digit month and two-digit year.

    Format Type: Numeric

    Date Format: MMYY
    Example: "1227"

  - `paymentType.creditCard.card.lastFour` (string)
    Last 4 digits of an account number or PAN.
    Example: "1224"

  - `paymentType.creditCard.card.network` (string)
    The card payment network.

    Format type: String

    e.g. VISA
    Example: "VISA"

  - `paymentType.creditCard.card.category` (string)
    Card category.

    Format type: String

    e.g.

    CREDIT

    DEBIT
    Example: "credit"

  - `paymentType.creditCard.card.isInternational` (boolean)
    Indicates if this is international relative to US.

  - `paymentType.applePay` (object)
    Used to identify the Apple Pay payment type.

  - `accountValidationResult` (object)
    The ACH account validation return code, which indicates if ACH validation was performed.

  - `accountValidationResult.responseCode` (string)
    Account validation return code which indicates if ACH validation was performed.
    Example: "1"

  - `accountValidationResult.thirdPartyResponseCode` (string)
    The third-party return code, which provides additional information about the validation response.
    Example: "2"

  - `accountValidationResult.bankName` (string)
    The name of the bank received in the validation response.
    Example: "UB Bank"

  - `processorResponse` (object)
    Response returned by processor.

  - `processorResponse.responseCode` (string)
    Response code returned by processor indicating status of request.

    Format Type: Alphanumeric
    Example: "A0000"

  - `processorResponse.responseMessage` (string)
    Response message returned by processor indicating status of request.

    Format Type: String
    Example: "Success"

  - `processorResponse.authorizationCode` (string)
    The authorization code returned by the processor for the transaction.

    Format Type: Alphanumeric
    Example: "TAS890"

  - `processorResponse.avsResultCode` (string)
    The Address Verification Service (AVS) result code.

    Format Type: String
    Example: "Z"

  - `processorResponse.cvvResultCode` (string)
    The card security code verification (CVV2) response returned by the processor.

    Format Type: Alphanumeric
    Example: "M"

  - `processorResponse.processedAmount` (number)
    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

  - `processorResponse.processorTransactionId` (string)
    The processor-generated unique identifier for a transaction.
    Example: "49510555"

  - `processorResponse.processorTransactionType` (string)
    The transaction type sent to the processor.
    Example: "Sale"

  - `riskResponse` (object)
    Response returned by the Risk Service if the service was invoked during processing the payment.

  - `riskResponse.responseCode` (string)
    Format Type: Alphanumeric

    Length: 1 to 5
    Example: "0"

  - `riskResponse.riskId` (string)
    Unique ID returned by the Risk Service.
    Example: "12e3cdac-d347-4564-ba1f-305e5e1e8ded"

  - `riskResponse.data` (object)
    Additional details on risk scoring functionality.

  - `riskResponse.data.thirdPartyId` (string)
    Unique ID returned by third party provider.
    Example: "12e3cdacd347-4564-ba1f305e5e1e8ded"

  - `riskResponse.data.riskScore` (integer)
    Risk score, on a scale from 0 (low risk) to 100 (high risk).

    Type: Number
    Example: 50

  - `riskResponse.data.tags` (array)
    List of all rules triggered by the Risk Service.

  - `riskResponse.data.tags.action` (string)
    The action related to the rule.

    Type: String

    Example: cancelled, queued, monitored, approved
    Example: "approved"

  - `riskResponse.data.tags.name` (string)
    Name of the tag(rule/label) that is triggered.

    Type: String

    Example: Billing Country = RU Fails
    Example: "MaxTransactionAmt=>100"

  - `riskResponse.data.tags.type` (string)
    Source of the tag.

    Type: String

    Examples: rule, label, queue, workflow
    Example: "rule"

  - `riskResponse.data.tags.state` (string)
    The name of the rule set.

    Type: String

    Example: Global Rule Set
    Example: "Override Rule Set"

## Response 500 fields (application/json):

  - `responseCode` (string)
    Example: "500"

  - `responseMessage` (string)
    Example: "Internal Server Error"