Configure merchant keys and environments
Keep browser tokenization, server processing and merchant routing separate.
Two keys serve different purposes
The tokenization key identifies the merchant for browser-side payment collection. The private merchant API key authorizes server-side operations. Treat the pair as belonging to a specific merchant and environment; do not accept a private key or arbitrary merchant identifier from a browser request. Credential Location Purpose Public tokenization key NmiPayments tokenizationKey prop Collect a payment method for the intended merchant Private API key Server secret store or server-only environment variable Authorize a gateway payment request Application session Your own authenticated application Establish who may pay or manage an order
Configure the correct host
Sandbox requests use sandbox.nmi.com. Production online examples use secure.nmi.com. Keep host and credentials in the same environment configuration. A deployment must fail safely when a required secret is absent; do not silently fall back to production or a different merchant. NMI_BASE_URL=https://sandbox.nmi.com NMI_PRIVATE_KEY=<sandbox-private-key> # Browser configuration contains only the public tokenization key.
Send the private key without a scheme
The REST Payments API expects the entire Authorization value to be the merchant private API key. Do not prefix it with Bearer or ApiKey. Classic integrations use a security_key form parameter instead, so authentication must change when switching request families. POST /api/v5/payments/sale HTTP/1.1 Host: sandbox.nmi.com Authorization: <sandbox-private-key> Content-Type: application/json
Protect tenant boundaries
In a multi-merchant application, choose the merchant configuration from trusted server-side order ownership. A public tokenization key is not permission to access a merchant’s customers or transactions. Keep customer vault IDs, payment IDs and order IDs scoped to their merchant and environment. Store a merchant-to-credential reference in server configuration, not in client-controlled request fields. Authorize the current user against the order and merchant before creating or refunding a payment. Redact Authorization, tokens and sensitive response fields from diagnostics. When rotating credentials, verify a controlled test and retire the old credential through the approved account process.
Diagnose authentication failures
Check the environment first, then the header value, account permissions and intended merchant. Remove accidental quotation marks, whitespace or a Bearer prefix. Capture a redacted timestamp, HTTP status and provider reference ID for support; never copy the private key into a ticket.