Creating a Payment with a Token

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide walks through how to create a payment using a token generated by the Nelnet Payment Services (NPS) tokenization flow.

By the time you reach this page, you should already be able to:

• Authenticate using JWTs
• Create a tokenization session
• Collect a payment token using the hosted iframe or SDK

This document focuses on the first backend payment request that actually moves money.

High-Level Flow

The flow looks like this:

1. Browser tokenizes payment details using the hosted iframe
2. Your backend receives a payment token
3. Your backend submits a payment request to the Payments API
4. NPS processes the transaction and returns a result

Payments API Endpoint

All payment requests are sent to the Payments API root endpoint.

POST https://api.nelnetpay.com/payments
Authorization: Bearer <JWT>
Content-Type: application/json
nps-trace-uuid: <uuid>

• Authentication uses a JWT in the Authorization header
• Each request must include a unique nps-trace-uuid header for tracing

Required Fields for a Basic Payment

At a minimum, a payment request requires:

• entityId
• paymentType (with a token)
• transactionType
• amount (required for most transaction types)

All other fields are optional or conditional.

Example: Credit Card Sale Using a Token

This example shows a simple credit card sale using a token generated by the tokenization iframe.

{
  "entityId": 1325691045,
  "paymentType": {
    "creditCard": {
      "token": "4NTSIT839d9b1234",
      "card": {
        "expiration": "1227"
      }
    }
  },
  "transactionType": "SALE",
  "amount": 123.65,
  "accountHolder": {
    "accountHolderName": "John Smith",
    "ipAddress": "10.101.101.101"
  },
  "transactionInformation": {
    "orderNumber": "652367",
    "customId": "330d4c38-7904-47cf-be8e-0972a93f7386"
  }
}

Notes:

• The token comes from the tokenization step
• Card data beyond expiration is never sent to your backend
• entityId controls which merchant the payment is processed for

ACH Payments Using a Token

ACH payments can also be created using a tokenized bank account.

{
  "entityId": 1325691045,
  "paymentType": {
    "ach": {
      "token": "4NTSIT839d9b1234"
    }
  },
  "transactionType": "ACH_DEBIT",
  "amount": 123.65,
  "accountHolder": {
    "accountHolderName": "John Smith",
    "accountHolderId": "134267"
  },
  "transactionInformation": {
    "standardEntryCode": "WEB",
    "description": "tuition",
    "companyName": "College Prep"
  }
}

ACH-specific requirements (such as standardEntryCode) are covered in more detail in the ACH documentation.

Acting on Behalf of a Merchant

Payments are processed in the context of the entityId provided in the request.

This allows platform or marketplace integrations to use centralized credentials.

Handling the Payment Response

A successful payment returns a 200 OK response with a payment result.

Example: Approved Card Payment Response

{
  "responseCode": "A100",
  "responseMessage": "Approved",
  "paymentTransactionId": "80503dc9-15f8-430a-8622-3cff38124bbd",
  "paymentType": {
    "creditCard": {
      "token": "4NTSIT839d9b1234",
      "card": {
        "lastFour": "1224",
        "network": "visa"
      }
    }
  },
  "processorResponse": {
    "authorizationCode": "TAS890",
    "processedAmount": 123.65
  }
}

Important fields to store:

• paymentTransactionId (used for refunds, captures, voids)
• responseCode and responseMessage

Risk and Fraud Evaluation

If risk services are enabled:

• Fraud analysis runs automatically during payment processing
• Results are returned in the riskResponse object
• Payments may be approved, declined, or queued based on risk rules

The riskId returned during tokenization can be passed into the payment request to correlate risk events.

Common Errors

Best Practices

Summary

• Payments are created server-side using tokens
• Tokens come from the hosted iframe or SDK
• entityId controls merchant context
• The Payments API handles authorization, processing, and risk
• Responses include identifiers for the full payment lifecycle