Introduction

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, create new users, 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.

🚧

Under Construction

The complete V4 API documentation is available HERE. The pages in the v4 section are under construction and may change.

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 video tutorial shows you how to create and obtain security keys.

Response Code Table

Successful Response Codes

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.

Unsuccessful Response Codes

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://secure.nmi.com/api/v4/merchants/reports/123?maxResults=50",
        "last": "https://secure.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50",
        "next": "https://secure.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50",
        "previous": "https://secure.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://secure.nmi.com/api/v4/merchants/reports/123?offset=50&maxResults=50
Headers:
  Authorization: {{your v4 api key}}