# API Standards

This document defines the **shared standards and conventions** used across all Nelnet Payment Services (NPS) APIs.

It is intended for **technical integrators** and describes how NPS APIs behave consistently, regardless of the specific service (Payments, Tokenization, Risk, Notifications, etc.).

## Design Principles

div
strong
Key idea:
br

  NPS APIs favor consistency and predictable behavior to make integrations easier to build and maintain.

Across all services, you can expect:

- REST-oriented endpoints
- JSON request and response bodies
- Explicit, documented field names
- Stable response structures
- Clear separation between authentication, context, and behavior


## Base URLs & Environments

All production API traffic is sent to:


```
https://api.nelnetpay.com
```

A non-production environment is available for testing:


```
https://api.uat.nelnetpay.com
```

## Required HTTP Headers

All API requests must include the following headers.

| Header | Description |
|  --- | --- |
| `Content-Type: application/json` | Required for all requests with a body |
| `Authorization: Bearer <JWT>` | JWT created using API keys |


## Authentication Model

- NPS APIs use **Bearer token authentication**
- JWTs are created server-to-server using API keys
- JWTs are passed in the `Authorization` header


div
strong
Reminder:
br

  Session tokens are used only by browser-based SDKs and must never be sent to backend APIs.

## HTTP Methods

| Method | Usage |
|  --- | --- |
| `GET` | Retrieve resources |
| `POST` | Create resources or initiate actions |
| `PUT` | Replace an existing resource |
| `PATCH` | Partially update a resource |
| `DELETE` | Remove a resource |


## HTTP Status Codes

| Status Code | Meaning |
|  --- | --- |
| `200 OK` | Request succeeded |
| `401 Unauthorized` | Authentication failed |
| `403 Forbidden` | Insufficient permissions |
| `404 Not Found` | Resource not found |
| `500 Internal Server Error` | Unexpected server error |


## Response Format

All NPS APIs use a shared response envelope across success, validation errors, and payment declines.


```json
{
  "responseCode": "A100",
  "responseMessage": "Approved"
}
```

`responseCode` is the authoritative field for programmatic decision making. Always branch logic on `responseCode`, never on `responseMessage`.

→ See [Response Format](/docs/response-format) for full details and examples.

## Field & Data Type Conventions

### Dates & Times

| Type | Format |
|  --- | --- |
| Date | `YYYY-MM-DD` |
| DateTime | ISO 8601 UTC |


### Numeric Values

| Type | Convention |
|  --- | --- |
| Currency | Decimal (no floats) |
| Percentages | Decimal |
| IDs | Integer or string |


### Enums

- Uppercase snake case
- Clients should tolerate new values


## Versioning

- API URLs do not include a version by default
- Versioning is explicit when required
- Strategy is evolving and will be communicated ahead of changes


## Summary

- Consistent REST conventions across services
- Canonical error response structure
- Predictable field formats
- Explicit authentication model