To set up NMI payments on WooCommerce, you need three things: an active NMI gateway account (directly with NMI or through a provider whose gateway runs on NMI), a WooCommerce payment plugin that supports NMI, and two keys from your gateway account: a private API key and a public tokenization key. You install the plugin, paste the keys, run a test transaction, then switch to live mode.
The whole job usually takes less time than people expect. The parts that cause trouble are almost always small: the wrong key type, test mode left on, a second gateway plugin competing for checkout, or a feature like ACH that is not enabled on the account. This guide walks through each step and the checks that prevent those problems.
What you need before you start
Gather these before you touch any settings. It saves a lot of back and forth.
- An NMI gateway login. If you signed up through a reseller, ISO or bank, your gateway may carry their branding, but it still runs on NMI. Ask your provider for the login if you do not have it.
- Admin access to WordPress with permission to install plugins.
- A current WooCommerce install. Know whether your store uses the block checkout or the classic shortcode checkout, because your plugin must support the one you use.
- A list of what you want to accept: cards only, or cards plus eCheck/ACH. ACH has to be enabled on the NMI account by your provider.
- A decision on charging: charge at checkout, or authorize at checkout and capture later when you ship.
- A staging site or a quiet hour for testing, so real customers are not checking out while you change settings.
Understand the two NMI keys
Most setup problems come from mixing up keys. NMI accounts use different keys for different jobs, and a WooCommerce integration that uses hosted card fields needs both of these:
| Key | What it does | Where it is used | Keep it secret? |
|---|---|---|---|
| Private API key | Authorizes server-side actions: sales, captures, refunds, voids, vault requests | Stored in your plugin settings on the server | Yes. Treat it like a password. |
| Public tokenization key | Loads the hosted card fields in the shopper’s browser and turns card details into a one-time token | Sent to the browser on the checkout page | No, it is designed to be public |
Both keys are created in your gateway account’s security or API key settings. The exact menu name can differ depending on your provider’s version of the portal, so if you cannot find it, ask your provider’s support team where API keys are managed. When you create the private key, give it a clear name such as “WooCommerce store” so you can revoke it later without affecting other integrations.
Never paste the private key into a theme file, a support forum, or an email. If you think it has been exposed, delete it in the gateway and create a new one.
Step by step: connect NMI to WooCommerce
The steps below follow the general pattern for any NMI plugin. Your plugin’s labels may differ slightly.
- Back up your site. A quick backup before installing a payment plugin is cheap insurance.
- Install and activate the gateway plugin from your WordPress dashboard.
- Turn on test or sandbox mode first. Enter test credentials if your provider gave you a separate sandbox account, or use the plugin’s test mode.
- Paste the private API key and public tokenization key into the plugin settings. Check for stray spaces at the start or end.
- Choose the transaction type: sale (charge now) or authorize only (capture later).
- Enable the payment methods you want, such as cards and, if your account supports it, eCheck/ACH.
- Set the checkout title and description customers will see, for example “Credit or debit card”.
- Save, then place a test order on the storefront using your provider’s test card numbers.
- Confirm the transaction appears in the NMI gateway and the WooCommerce order has the right status and transaction ID.
- Switch to live mode, place one small real order, then refund it.
Set up NMI with PaymentDash
If you want the setup done in one place, PaymentDash is a WordPress plugin built for WooCommerce stores on the NMI gateway. It combines a checkout gateway with a payments dashboard inside WordPress. A setup assistant walks you through it, and a built-in guide shows you how to find your NMI keys. You paste the private API key and public tokenization key, tick “Use these keys for my WooCommerce checkout”, and the gateway is ready. Setup takes about ten minutes.
If another NMI gateway plugin is already active, PaymentDash detects it and can leave checkout with that plugin. That lets you use the dashboard first and move checkout over when you are ready, instead of switching everything at once.
Test before you go live
A test order that “goes through” is not the same as a working setup. Run through a short checklist:
- Approved card: the order shows the status you expect for a paid (or authorized only) order and carries a transaction ID.
- Declined card: the customer sees a clear error and the order is not marked paid.
- Refund: issue a refund from the order screen and confirm it shows in the gateway.
- Capture: if you authorize only, capture a test order and confirm the amount.
- Saved card: if you offer card saving, save a card in My account and use it on a second order.
- Mobile: complete one checkout on a phone, since hosted card fields can look different on small screens.
- Emails: confirm order emails go out as expected.
Use only the test card numbers your provider supplies. Never use real card numbers in test mode.
Common setup problems and fixes
Card fields do not appear at checkout
This usually means the public tokenization key is missing or wrong, or a caching or script optimization plugin is blocking the hosted fields script. Exclude the checkout page from caching and script minification, then reload.
“Authentication failed” or similar errors
The private API key is wrong, deleted, or belongs to a different account than the tokenization key. Create a fresh key pair from the same gateway account.
Live orders go to the sandbox
Test mode is still on. Turn it off and place one small live transaction to confirm.
ACH or 3D Secure options do nothing
Both need to be enabled on your NMI account. 3D Secure 2 requires the 3-D Secure service on the account. Ask your provider to switch them on, then retest.
Two gateways show up, or orders are processed twice
Two NMI plugins are active. Choose one for checkout and disable the gateway setting in the other.
Settings worth reviewing after launch
Once live orders are flowing, look at a few settings that affect disputes and customer experience:
- Billing descriptor. A recognizable descriptor on card statements can cut down on disputes from customers who do not recognize a charge. Some processors allow a dynamic descriptor per transaction; check what yours supports.
- Fraud filters. NMI accounts can have fraud and AVS/CVV rules at the gateway level. Review them with your provider so they are strict enough to stop bad orders but not so strict that good customers get declined.
- 3D Secure. Consider it if you see card-testing attacks or fraud disputes, or if you sell to regions where it is expected.
- Payment alerts. Set up notifications for declines, refunds and chargebacks so problems do not sit unnoticed.
Wrapping up
A solid WooCommerce NMI setup comes down to the right two keys, a plugin that supports your checkout type, careful testing, and a quick review of descriptor and fraud settings once you are live. Get those right and your checkout should run quietly in the background.
If you want checkout and a full payments dashboard set up together inside WordPress, see PaymentDash pricing to compare plans, or start with the free NMI gateway plugin.
Frequently asked questions
Do you need a separate merchant account to use NMI with WooCommerce?
NMI is a gateway, so you also need a merchant account with a processor. Many providers bundle both. Check your agreement or ask your provider which processor your account settles through.
Can you test NMI without charging real cards?
Yes. Use your plugin’s test or sandbox mode with the test card numbers your provider supplies. Turn test mode off before taking real orders.
Why does a provider’s gateway look different from NMI’s?
Many providers rebrand the NMI gateway with their own logo and portal address. The keys and integration work the same way, though menu names can vary.