Nmi

medusa-payment-nmi

A Medusa v2 payment provider for the NMI Gateway — card, ACH/eCheck, and Apple/Google Pay through one provider, collected with NMI's official <NmiPayments> component (@nmipayments/nmi-pay-react). The card PAN / bank number is tokenized in the browser and never touches your server.

You register a single NMI payment method; the customer picks card or bank (or a wallet) inside the payment element, and the provider runs the right lifecycle:

• Card / Apple Pay / Google Pay authorize synchronously — the backend charges the token via the Payment API and knows the result immediately.
• ACH is asynchronous — the backend submits the debit (authorized); a settlement webhook captures it, an ACH return fails it.

Install

npm install medusa-payment-nmi

Or straight from GitHub (the prepare script builds .medusa/server on install):

npm install github:Kaelbroersma/medusa-payment-nmi

Requires: Medusa >= 2.5, Node >= 20.

This package is a standard Medusa plugin built with medusa plugin:build, so it follows the official exports layout — medusa-payment-nmi/providers/nmi resolves the payment module provider.

Configure (medusa-config.ts)

1module.exports = defineConfig({
2  modules: [
3    {
4      resolve: "@medusajs/medusa/payment",
5      options: {
6        providers: [
7          {
8            resolve: "medusa-payment-nmi/providers/nmi",
9            options: {
10              securityKey: process.env.NMI_SECURITY_KEY,
11              tokenizationKey: process.env.NMI_TOKENIZATION_KEY,
12              webhookSecret: process.env.NMI_WEBHOOK_SECRET,
13              captureMethod: "auth",   // card/wallet: "auth" or "sale"
14              secCode: "WEB",          // ACH SEC code (internet-initiated consumer debit)
15              sandbox: process.env.NODE_ENV !== "production",
16            },
17          },
18        ],
19      },
20    },
21  ],
22})

How a payment flows

1. initiatePayment returns { tokenizationKey } to the storefront.
2. <NmiPayments> tokenizes the chosen method → a single-use token; the storefront writes { payment_token, payment_method } onto the payment session and completes the cart.
3. authorizePayment charges the token:
   • card/wallet → auth or sale (per captureMethod) → authorized / captured.
   • ach → sale → authorized (not yet settled).
4. For ACH, the settlement webhook → captured; an ACH return → failed.

Webhooks

Medusa exposes one webhook route for the provider:

• POST https://<your-backend>/hooks/payment/nmi

In NMI Merchant Portal → Settings → Webhooks, add that URL, paste the signing key (your webhookSecret), and subscribe to these events:

The handler verifies the Webhook-Signature HMAC and maps each event to the right action, disambiguating card vs ACH by the event body. NMI requires public HTTPS — for local dev, tunnel (e.g. cloudflared, ngrok) to your backend.

Note on async outcomes: Medusa's built-in payment-webhook subscriber acts on the authorized and captured outcomes. ACH settlement (→ captured) works out of the box. ACH returns and voids are detected and mapped by this provider but, like all failed/canceled webhook outcomes in current Medusa core, do not auto-transition the payment — add your own subscriber on the payment.webhook_received event if you need automated return/void reconciliation.

Storefront

See storefront/README.md for the copy-paste <NmiPayments> component and checkout wiring.

Local development

The repo uses the official Medusa plugin toolchain:

1npm install          # also builds .medusa/server via prepare
2npm run dev          # medusa plugin:develop — watch + publish to the local registry
3npm test             # vitest unit tests

To try local changes inside a Medusa app, use the local plugin workflow:

1# in this repo
2npx medusa plugin:publish
3
4# in your Medusa app
5npx medusa plugin:add medusa-payment-nmi

Not in v1

Saved cards / NMI Customer Vault. The account-holder methods are implemented as no-ops around a synthetic holder; no card is stored. (Easy to add later.)

License

MIT