# Creating a Payment with a Token

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

div
strong
Key idea:
br

  Tokens represent payment credentials. Payments are created server-side using those tokens.

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.


```http
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.


```json
{
  "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.


```json
{
  "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.

div
strong
Reminder:
ul
li
The JWT authenticates the API key
li
The 
code
entityId
 determines the merchant context
li
Parent-level keys may act on behalf of child merchants
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


```json
{
  "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

| Scenario | Result |
|  --- | --- |
| Invalid or expired JWT | `401 Unauthorized` |
| Missing required fields | Validation error |
| Invalid token | Declined or error response |
| Unauthorized `entityId` | Authorization failure |


## Best Practices

div
strong
Best practices:
ul
li
Generate a new JWT for payment requests
li
Log and store 
code
paymentTransactionId
li
Use idempotency and trace IDs to prevent duplicates
li
Test thoroughly in UAT before going live
## 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