Resource/URL Patterns

All NPS API resources are organized around REST using predictable and intuitive URL patterns. This is commonly expressed as:

https://domain.com/{Resource}/{ID}}
domain.com - The API base URL specific to the environment.
{Resource} - The name of the resource.
{ID} - The identifier of the item.

Supported

Resources are plural nouns, for example books.
IDs are a non-DB bound ID, for example 123456.
Nested resources are limited to significant sub resources, for example customer/1234/paymentMethod/1.

Unsupported

Verbs are not allowed in URLs either as the resource or the ID, for example getCustomer/123. Actions are implied by the HTTP methods used.
Resources are not singular nouns, for example book.
Multiple IDs are not allowed, for example getBooks/multiple with the IDs in the body.
Long paths are avoided, for example resource/123/subResource/456/subResource/789.

HTTP Methods

NPS APIs supports a limited number of HTTP methods to help perform clear and precise actions on resources.

HTTP Method	Description
GET	Get a single object. Describe a single object. Retrieve a list of objects.
POST	Create a single object.
PUT	Create or update many objects.
PATCH	Update a single object.
DELETE	Remove a single object.

HTTP Status Codes

NPS APIs support a limited number of HTTP response codes.

HTTP Code	Description
200	OK This is a good request. A successful request can still contain application-level errors.
400	Bad Request (Note: This response code will be deprecated.) The server couldn't process the request due to an apparent client error. For instance, the request may have invalid data. Check the response body for details. The request should not be retried until the data is corrected.
401	Unauthorized The authentication failed or invalid credentials were sent in the request. Check the key name and passphrase.
403	Forbidden The authenticated user is attempting a prohibited action or does not have permission to access the requested resource.
404	Resource Not Found The requested resource could not be found.
429	Too Many Requests The client has sent too many requests in a given amount of time. This mechanism of asking the client to slow down the rate of requests is commonly referred to as rate limiting.
500s	Server Error A 500 or Internal Server Error is a generic error message related to server issues. Otherwise, a more specific 5xx-level error code is given.

Error Format and Codes

NPS APIs provide a common error format across the entire payment ecosystem.

{
  "result": {
    "status": enum
  },
  "error": {
    "code": int,
    "messages": [
      {
        "message": string
      },
    ]
  }
}

Pagination

NPS APIs provide a page-based pagination set with two parameters, page and size.

Request Examples

curl -X GET 'https://api.nelnetpay.com/service/item' 
curl -X GET 'https://api.nelnetpay.com/service/item?page=2&size=10'

Result Example

{
  "results": {...},
  "pagination": {
   "total_records": 100,
   "current_page": 1,
   "total_pages": 10,
   "next_page": 2,
   "prev_page": null
 }
}

Versioning

By default, there is no version number in the URL, such as: https://docs.nelnetpay.com/.
When necessary, a simple URL versioning standard will apply. This means that the version number is added after the service. Some examples include: http://nps.com/payments/v2 (where v2 could be 2 or 2.1, etc.).