---
updatedAt: 2026-08-10T17:48:35.000Z
agentTools:
  projectIndex: https://docs.nmi.com/llms.txt
---

# Overview

NMI offers the ultimate white-label, embedded payment experience. The payment gateway’s real-time v4 API is a complete API that allows you to build any payment features found in your NMI Partner Portal. You are able to run reports, board merchants, make updates to your settings, and so much more. The v4 is only limited by what you can do in the current NMI Partner Portal.

All URLs in this document are NMI-branded, but custom domains work as well.

# Content-Type

Requests must include a Content-Type header indicating that the content is JSON data. This header should always be:

```JavaScript
Content-Type: application/json
```

# Authentication

Log into your partner portal and go to Settings → Security Keys. Create a new key for your username with `“v4 API”` permissions. This key will be used in the header to authenticate all requests. [This](https://vimeo.com/200899701) video tutorial shows you how to create and obtain security keys.

# Response Code Table

**<span style={{ color: "green" }}>Successful Response Codes</span>**

Successful requests will always return one of the HTTP codes below in the response:

| Code | Description                                          |
| :--- | :--------------------------------------------------- |
| 200  | Successful request.                                  |
| 204  | Successful request, but there isn't a response body. |

**<span style={{ color: "red" }}>Unsuccessful Response Codes</span>**

The following HTTP status codes will be returned in the event of various errors:

| Code | Description                                                                     |
| :--- | :------------------------------------------------------------------------------ |
| 400  | Bad Request - The request is not correct. Parse error.                          |
| 401  | Unauthorized - a missing API Key or an invalid API Key was sent in the request. |
| 404  | Not Found - The resource (Gateway ID / Processor ID) provided was not found.    |
| 405  | Method Not Allowed - The HTTP method is not allowed for this request.           |
| 406  | Not Acceptable.                                                                 |
| 415  | Invalid Content Type - Invalid JSON.                                            |
| 500  | Internal Server Error.                                                          |
| 503  | Service Unavailable.                                                            |

If an error occurs, a JSON response that includes the error `type` and an error `message` is returned. For example, an improperly formatted field may result in a `500` response code (Internal Server Error) with the following JSON:

```JavaScript
HTTP 500
{
    "type":"invalid_field",
    "message":"payment_type field is formatted incorrectly."
}
```

# Paging Through Results

All API methods that return data also support paging through results. Most will support a `maxResults` argument that you can use to set the number of results per page as well. Paging only exists for reports and searches. For endpoints that are report or search endpoints, you will get back a report `objectType`, which includes the report ID and how to page through it with links.

**How to Page Through Results**

To page through results, you simply need to perform a GET request using one of the “links” provided at the top of the response. Here’s an example response with multiple pages:

```JavaScript
{
    "objectType": "report",
    "reportId": 123,
    "offset": 0,
    "maxResults": 50,
    "totalResults": 320,
    "hasMore": true,
    "links": {
        "first": "https://sandbox.nmi.com/api/v4/merchants/reports/123?maxResults=50",
        "last": "https://sandbox.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50",
        "next": "https://sandbox.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50",
        "previous": "https://sandbox.nmi.com/api/v4/merchants/reports/123?offset=0&maxResults=50"
    },
    "results": […]
}
```

A few things to note:

1. The `hasMore` value will remain `true` until you get to the end of the list.
   * If you’re doing a loop to continue querying until you have all the results, you can wait for `"hasMore": false` to return, since at that point you’ve reached the end of results.
2. We provide links to the first, last, next, and previous pages of results, and you can use whichever one suits your needs.

You do still need to authenticate, so make sure to include the Authorization header element with your API key in the GET request.

For example:

```JavaScript
GET: https://sandbox.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50
Headers:
  Authorization: `{{your v4 api key}}`
```