Skip to content

POS NMI

Overview

The POS NMI module integrates NMI payment processing into Odoo 18's Point of Sale through two modes:

  • NMI Terminal -- Physical CloudPOS card reader for card-present payments (EMV chip, contactless tap, magnetic stripe)
  • NMI Key-in -- Browser-based Collect.js popup for manual card entry, ideal for phone orders or tablet POS setups

Both modes share the same NMI credentials configured once on the NMI payment provider. All sensitive credentials are injected server-side -- security keys never reach the browser.

Key Features

Feature Terminal Key-in
Sale transactions Yes Yes
Refund by transaction ID Yes Yes
EMV chip / contactless / swipe Yes --
Manual card entry (Collect.js) -- Yes
Tip support Yes Yes
EMV receipt data (AID, CVM, auth code) Yes --
Device registration from Odoo Yes --
PCI-compliant tokenization -- Yes

Installation & Dependencies

Requirements

Requirement Details
Odoo Version 18.0 Community or Enterprise
Dependencies point_of_sale (core), payment_nmi (must be installed and configured first)
NMI Account Active NMI merchant account with API access
For Terminal mode NMI CloudPOS-compatible terminal device
For Key-in mode No additional hardware required

Installation

Install payment_nmi First

The Payment Provider: NMI module must be installed and configured with your Security Key and Tokenization Key before installing POS NMI. See the Payment Provider: NMI documentation.

There are two ways to install the module:

  1. Go to Point of Sale > Configuration > Settings
  2. Scroll to the Payment Terminals section
  3. Enable NMI
  4. Click Save

This automatically installs the pos_nmi module.

  1. Place the pos_nmi module folder in your Odoo addons path
  2. Update the module list: Apps > Update Apps List
  3. Search for "POS NMI" and click Install

Configuration

Prerequisites

Before configuring POS payment methods, ensure:

  1. The Payment Provider: NMI (payment_nmi) module is installed
  2. The NMI payment provider is configured with your Security Key and Tokenization Key
  3. The provider state is set to Enabled or Test Mode

See the Payment Provider: NMI -- Configuration section for details on obtaining and entering your API keys.

NMI Terminal Setup (CloudPOS)

The NMI Terminal mode routes transactions to a physical CloudPOS card reader device. Customers present their card on the terminal (chip insert, contactless tap, or magnetic swipe) to complete the payment.

Step 1: Create the Payment Method

  1. Go to Point of Sale > Configuration > Payment Methods
  2. Click New
  3. Enter a name (e.g., "NMI Terminal" or "NMI Terminal - Register 1")

  4. Important: Make sure Online Payment is unchecked

    Online Payment Must Be Unchecked

    If the Online Payment toggle is enabled, the Journal field is hidden and the terminal integration options will not appear. Always leave this unchecked for POS terminal payment methods.

  5. Set the Journal to a Bank type journal

    Bank Journal Required

    The "Use a Payment Terminal" dropdown only appears when the journal type is Bank. This is a core Odoo requirement, not specific to NMI.

  6. Under Integration, set Integrate with to NMI Terminal

  7. Select your NMI Payment Provider from the dropdown

Step 2: Register the Terminal Device

Before the terminal can process transactions, it must be registered with NMI:

  1. Power on your CloudPOS terminal and connect it to the internet
  2. The terminal will display a Registration Code on its screen (this code rotates periodically)
  3. On the payment method form in Odoo, enter the Device Registration Code from the terminal
  4. Click Register Device

Once registration succeeds, the following fields will populate automatically:

Field Description
Device ID The POI device UUID assigned by NMI -- used to route transactions to this terminal
Serial Number The physical serial number of the terminal
Registration Status Current registration status (e.g., "REGISTERED")

Registration Code Expiration

The registration code displayed on the terminal rotates periodically. If registration fails, check that the code is still current on the terminal screen and try again with the updated code.

Step 3: Assign to a POS Config

  1. Go to Point of Sale > Configuration > Settings
  2. At the top of the page, use the POS config selector to choose which register you are configuring (e.g., "Main POS", "Register 1")
  3. Scroll to the Payment section
  4. In the Payment Methods field, add the NMI Terminal payment method you created
  5. Click Save

Deregistering a Terminal

To deregister a terminal device:

  1. Open the payment method form for the terminal
  2. Click Deregister Device
  3. The Device ID, Serial Number, and Registration Status fields will be cleared

After deregistering, the terminal can be registered to a different payment method or NMI account.

NMI Key-in Setup (Collect.js)

The NMI Key-in mode opens a Collect.js popup for manual card number entry directly in the POS. This is ideal for phone orders, mail orders, or any situation where the physical card is not present.

Step 1: Create the Payment Method

  1. Go to Point of Sale > Configuration > Payment Methods
  2. Click New
  3. Enter a name (e.g., "NMI Key-in")
  4. Important: Make sure Online Payment is unchecked
  5. Set the Journal to a Bank type journal
  6. Under Integration, set Integrate with to NMI Key-in
  7. Select your NMI Payment Provider from the dropdown
  8. Click Save

Tokenization Key

The Tokenization Key is automatically pulled from the linked NMI Payment Provider. You do not need to enter it separately on the payment method.

Step 2: Assign to a POS Config

  1. Go to Point of Sale > Configuration > Settings
  2. Select the POS config you want to add key-in to using the config selector at the top
  3. Under Payment > Payment Methods, add the NMI Key-in payment method
  4. Click Save

Multi-Register / Device Registration

If you have multiple POS registers, each with its own physical NMI terminal, you need a separate payment method for each terminal. Each payment method gets its own registered Device ID, linking it to a specific physical terminal.

Example: 3 Registers with 3 Terminals

Step 1 -- Create the payment methods (Point of Sale > Configuration > Payment Methods):

Payment Method Name Device Registration Assigned Device ID
NMI Terminal - Register 1 Register device aaa-111-...
NMI Terminal - Register 2 Register device bbb-222-...
NMI Terminal - Register 3 Register device ccc-333-...

Step 2 -- Assign to POS configs (Point of Sale > Configuration > Settings):

  1. Select Register 1 from the POS config selector at the top
  2. Under Payment > Payment Methods, add "NMI Terminal - Register 1"
  3. Save
  4. Switch to Register 2, add "NMI Terminal - Register 2", save
  5. Switch to Register 3, add "NMI Terminal - Register 3", save

Key-in Doesn't Need Separate Instances

NMI Key-in payment methods do not need separate instances per register since there is no physical device. A single "NMI Key-in" payment method can be shared across all POS configurations.

Shared Credentials

All payment methods share the same NMI Payment Provider (same API credentials). Each terminal just has its own Device ID. When a cashier processes a payment, the transaction is routed to the specific terminal registered on that POS config's payment method.

Transaction Flows

Terminal Sale Flow

POS (Cashier)               Odoo Server                  NMI API              Terminal
     |                           |                           |                    |
     | 1. Click "Payment"        |                           |                    |
     |    Select NMI Terminal    |                           |                    |
     |                           |                           |                    |
     | 2. RPC: sale request ---> |                           |                    |
     |    (amount, order ID)     |                           |                    |
     |                           | 3. POST transact.php ---> |                    |
     |                           |    + security_key         |                    |
     |                           |    + poi_device_id        | 4. Route to -----> |
     |                           |                           |    terminal        |
     |                           |                           |                    |
     |                           |                           | 5. Customer taps / |
     |                           |                           |    inserts / swipes|
     |                           |                           |                    |
     |                           | 6. Response <------------ | <-- result --------|
     | 7. Display result <------ |    (approved/declined)    |                    |
     |    Print receipt          |                           |                    |

Key-in Sale Flow

POS (Cashier)               Collect.js            Odoo Server            NMI API
     |                           |                      |                    |
     | 1. Click "Payment"        |                      |                    |
     |    Select NMI Key-in     |                      |                    |
     |                           |                      |                    |
     | 2. Popup opens ---------> |                      |                    |
     |                           |                      |                    |
     | 3. Enter card details --> |                      |                    |
     |                           | 4. Tokenize          |                    |
     |                           |    client-side        |                    |
     |                           |                      |                    |
     |    payment_token <------- |                      |                    |
     |                           |                      |                    |
     | 5. RPC: token + amount -----------------------> |                    |
     |                           |                      | 6. POST ---------> |
     |                           |                      |    transact.php    |
     |                           |                      |    + security_key  |
     |                           |                      |    + payment_token |
     |                           |                      |                    |
     |                           |                      | 7. Response <----- |
     | 8. Display result <----------------------------- |                    |
     |    Print receipt          |                      |                    |

Refund Flow (Both Modes)

For refunds in either Terminal or Key-in mode:

  1. The cashier initiates a return in POS (negative payment amount)
  2. A popup asks for the original Transaction ID from the initial sale
  3. The refund is processed through NMI against the original transaction
  4. The refund result is displayed and a receipt is printed

Transaction ID Required

Refunds require the original NMI Transaction ID. This can be found on the original POS order receipt or in the Odoo backend under the payment details.

Receipt Information

Successful transactions include the following details on the POS receipt:

Terminal Receipts

Field Description
Transaction ID NMI transaction identifier
Card Type EMV application label (e.g., "Visa Credit")
Last 4 Last four digits of the card
Response Response text (e.g., "SUCCESS")
Auth Code Authorization code from the issuer
CVM Cardholder Verification Method (e.g., "PIN", "Signature")
AID EMV Application ID

Key-in Receipts

Field Description
Transaction ID NMI transaction identifier
Card Type Card brand (e.g., "Visa", "Mastercard")
Last 4 Last four digits of the card
Response Response text
Auth Code Authorization code from the issuer

Troubleshooting

Common Issues

\"No NMI payment provider linked\"

Symptom: Error message when attempting a transaction.

Solution: Open the POS payment method and select an NMI provider in the NMI Payment Provider dropdown. The provider must be in Enabled or Test Mode state.

Device Registration Fails

Symptom: Clicking "Register Device" results in an error.

Solution:

  1. Verify the registration code on the terminal screen is still current (it rotates periodically)
  2. Enter the fresh code and try again
  3. Ensure your NMI Security Key has API permission type
  4. Check that the terminal has an active internet connection
Terminal Not Responding / Transaction Timeout

Symptom: Payment hangs or times out after sending to the terminal.

Solution:

  1. Verify the terminal is powered on and connected to the internet
  2. Terminal transactions can take up to 2 minutes -- ensure a stable internet connection
  3. Check that the Device ID on the payment method matches the physical terminal
  4. Try deregistering and re-registering the device
Collect.js Not Loading (Key-in)

Symptom: The card entry popup does not appear when selecting NMI Key-in.

Solution:

  1. Verify the Tokenization Key is set on the NMI Payment Provider
  2. Ensure the key is a Tokenization type key (not API, Cart, or Checkout)
  3. Check the browser console for errors loading secure.nmi.com
  4. Ensure no ad blockers or browser extensions are blocking the Collect.js script
Authentication Failed (401)

Symptom: Transactions return a 401 authentication error.

Solution:

  1. Go to the NMI Payment Provider and verify the Security Key is correct
  2. Use the Test Credentials button on the provider form
  3. Ensure the key was created with API permission type in the NMI Merchant Portal
Card Validation Error in Key-in Mode

Symptom: Error message about card validation when entering card details.

Solution:

  1. Verify the card number, expiration date, and CVV are entered correctly
  2. Check that the card is not expired
  3. If the error persists, the card may be invalid -- try a different card

NMI Response Codes

Code Meaning POS Action
100 Approved (terminal response) Payment marked as done
1 Approved (Direct Post response) Payment marked as done
2 Declined Payment set to retry
3 Error Payment set to retry
401 Authentication failed Error shown, check credentials
300 Gateway rejection Error shown with message