Overview
Security keys let a merchant’s website, app or software connect to the NMI gateway. NMI has two kinds of key, private and public, and each one belongs in a different place. Use this article to help merchants pick the right key for their integration, create it in the Merchant Portal and fix common setup errors.
What Are Security Keys?
A security key is a unique code that allows software to securely connect to a merchant’s NMI account. It identifies the account associated with each request and determines what actions the software can perform, such as processing transactions or collecting payment information. The most commonly used type is a private key with API (Application Programming Interface) permissions, often referred to as an API key.
NMI splits keys into two types:
| Key type | Where it lives | What it can do | Safe to expose? |
|---|---|---|---|
| Private key | The merchant’s server | Process transactions and read account data | No. Never show it to customers |
| Public key | The merchant’s web page or app | Start a secure payment flow, such as turning card details into a payment token | Yes. Built to be visible |
Most online integrations use one of each. The public key collects payment details in the browser, and the merchant’s server sends the transaction with a private API key.
Why It Matters for Partners
If a merchant picks the wrong key, one of two things happens:
- The integration fails to authenticate. Transactions don’t go through, and the merchant may lose sales until the key is fixed.
- Credentials that can move money get exposed. A private key placed in a web page lets anyone who views the page source process transactions or read account data.
As a partner, you can help merchants by:
- Confirming which integration they use before they create a key
- Making sure private keys stay on the server and out of browser code
- Helping them rotate a key right away if it’s exposed
Prerequisites and Access Requirements
Before a merchant creates a key, make sure they have:
- Merchant Portal access with a user that can open Settings > Security Keys
- A user with the right permissions to assign to the key. Each key inherits the permissions of the user it’s assigned to. For example, if the user can’t process sales, the key can’t either.
Private Keys
Private keys should only be used in parts of your software that are inaccessible to outside parties like your customers. These keys allow for processing transactions and querying on account data, so make sure these are kept secret.
Private Keys
| Permission | Used with |
|---|---|
| API | Payment API (formerly Direct Post), REST API, Payment Device SDK for Windows/Linux, Payment Device SDK for iOS/Android, Customer-Present Cloud, Direct Connect SDK, Three Step Redirect and Query APIs. This is the same key type used to set up card terminals |
| Cart | QuickClick |
| V4 API | Authentication to the V4 API |
⚠️ Warning: If a private key is ever exposed, delete it from the Security Keys page and create a new one right away. Then update the merchant’s server configuration with the new key.
Public Keys
Public keys are designed to be used in places where a customer might be able to see them. For example, using these keys in the HTML on your website is the expected use case for these keys.
Public Keys
| Permission | Used with |
|---|---|
| Tokenization | Collect.js and the Payment Component. Turns the card or bank details a customer types into a one-time payment token. The server then submits the token with a private API key to process the payment |
| Checkout | Collect Checkout (NMI’s hosted payment page) and Gateway.js add-ons such as 3-D Secure and Kount fraud screening |
Which Keys Does the Integration Need?
The keys a merchant needs depend on how their software takes payment details. Check with the developer, or the software’s setup guide, to confirm which of these it uses.
| If the software… | Public key | Private key |
|---|---|---|
| Collects payment details itself and sends the transaction from its own server | None | API |
| Shows Collect.js or Payment Component payment fields on its web pages | Tokenization, for the payment fields | API, to submit the token from the server |
| Sends customers to NMI’s hosted payment page (Collect Checkout) | Checkout | API, only if it looks up the transaction result afterwards |
How Tokenization and the API key work together: The Tokenization key turns the card or bank details a customer types into a one-time payment token. The server then submits that token with a private API key to process the payment. The Tokenization key can’t process the payment on its own.
Note: If the merchant already uses card terminals, they’ve likely used a private API key before. Software that sends transactions from a server uses the same key type.
Creating a Key in the Merchant Portal
- Log in to the Merchant Portal and go to Settings > Security Keys.
- Select Add a New Private Key or Add a New Public Key, depending on the key the integration needs.
- Enter a name for the key that shows where it’s used, such as “Web store server” or “Checkout page.”
- Select a user from the Username Associated with Key dropdown. The key inherits that user’s permissions, so choose a user who can perform every action the integration needs, such as processing sales or refunds.
- Select the permission the integration needs from the Key Permission dropdown.
-
Select Create.
⚠️ Warning: If you later change or remove permissions for the assigned user, the key loses them too. This can stop an integration that was working.
Common Questions
I opened Add a New Public Key and don’t see API. Where is it?
API is a private key permission. Public keys only offer Tokenization and Checkout. Go back and create a private key instead.
Can I use one key for several integrations?
You can, but separate keys with clear descriptions make it easier to rotate or delete one without breaking the others.
A plugin asks for a “security key.” Which one does it want?
Most plugins want a private key with the API permission. Check the plugin’s setup guide to confirm.
Is it safe that customers can see my public key?
Yes. Public keys can’t process transactions or read account data on their own.
Need Help?
For additional support, please contact our Support team by Submitting a Ticket.