# Response Format

This document defines the shared response envelope used across all Nelnet Payment Services (NPS) APIs.

## Overview

All NPS APIs return `HTTP 200` for both success and failure outcomes. Always branch logic on `responseCode`. Never use `responseMessage` for conditional logic.

| Field | Present | Purpose |
|  --- | --- | --- |
| `responseCode` | Yes | Reserved — source of truth for outcome |
| `responseMessage` | Yes | Reserved — informational only |
| `responseDetails` | No | Reserved — per-error detail, multiple errors only |
| `<API-specific fields>` | No | Defined by each API endpoint |


`responseMessage` is informational only. Its format is not guaranteed and should not be parsed programmatically. Do not build application logic that depends on its content.

## Response Codes

`responseCode` always begins with a prefix that indicates the category of the outcome.

| Prefix | Category | Description |
|  --- | --- | --- |
| `A` | Success | Request completed successfully |
| `E` | Error | Input validation or processing error occurred |


Each API defines its own set of response codes within these prefix categories. Refer to the individual API reference for the full list of valid `responseCode` values.

## Response Envelope

### Success


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

> Additional fields vary by endpoint. Refer to the individual API reference for the full response schema.


### Single Error

When only one error occurs, it is represented at the top level. `responseDetails` is omitted.


```json
{
  "responseCode": "E410",
  "responseMessage": "Invalid length for field 'accountNumber'"
}
```

### Multiple Errors

When multiple errors occur, the first error populates the top-level `responseCode` and `responseMessage`. Additional errors are listed in `responseDetails`.


```json
{
  "responseCode": "E410",
  "responseMessage": "Invalid length for field 'accountNumber'",
  "responseDetails": [
    { "responseCode": "E409", "responseMessage": "Invalid format for field 'amount'" },
    { "responseCode": "E405", "responseMessage": "TransactionType is required" }
  ]
}
```

`responseDetails` is never an empty array. If there is only one error, `responseDetails` is omitted entirely and the error is represented at the top level.