Skip to main content

​
Connecting Your NMI Gateway

uPayments connects to your NMI gateway using API security keys. Here’s how to find them and set up the connection.

​
Finding Your NMI Credentials

​
Step 1: Log into your NMI Gateway

Go to your NMI merchant control panel. The URL depends on your processor:
  • NMI Direct: https://secure.nmi.com
  • ECS Payments: https://ecspayments.transactiongateway.com
  • Other resellers: Check with your payment processor

​
Step 2: Navigate to Security Keys

Go to Settings → Security Keys (or Gateway Options → Security Keys on some gateways). You’ll see two types of keys:

​
Private Security Keys (API Keys)

These are used for server-to-server communication — querying transactions, processing payments, and syncing data.
Private keys should never be shared publicly or stored in client-side code. uPayments encrypts your private key at rest using AES-256-GCM.
What to look for: Find or create a key with API source. Copy the full key string.

​
Public Security Keys (Tokenization Keys)

These are used with Collect.js for secure card tokenization on payment pages. What to look for: Find or create a key with Tokenization source. This is needed if you want to use uPayments payment pages.
If you don’t see a tokenization key, click Add a New Public Key in your NMI dashboard, select Tokenization as the source, and give it a description like “uPayments”.

​
Gateway URL

Your gateway URL is the base domain where your NMI API is hosted:
ProcessorGateway URL
NMI Directhttps://secure.nmi.com
ECS Paymentshttps://ecspayments.transactiongateway.com
OtherCheck with your processor — it’s the domain in your API endpoint
If your full API URL is https://ecspayments.transactiongateway.com/api/query.php, the gateway URL is just https://ecspayments.transactiongateway.com. The system adds /api/query.php and /api/transact.php paths automatically.

​
Adding Credentials in uPayments

  1. Go to Merchants → [Your Merchant] → Gateway & Sync
  2. Click Add NMI Account (or edit existing)
  3. Enter:
    • Account Name — A label for this gateway connection
    • Private Security Key — Your API key from the Private Security Keys section
    • Tokenization Key — Your Collect.js key (optional, needed for payment pages)
    • Gateway URL — The base domain of your NMI gateway
  4. Click Test & Connect — this validates your credentials and pulls your merchant profile
  5. If successful, your business details are pre-filled from NMI

​
What Gets Synced

Once connected, the background worker automatically syncs:
DataMethodFrequency
TransactionsNMI Query APIEvery 15 minutes
Customer Vaultreport_type=customer_vaultEvery 15 minutes
Subscriptionsreport_type=recurringEvery 15 minutes
Additionally, uPayments enriches synced data with:
  • Customer extraction — Creates customer records from transaction emails
  • Subscription detection — Identifies recurring patterns from transaction history
  • Card BIN lookup — Identifies debit vs credit, issuer, and country from card BIN
  • Decline reason mapping — Maps NMI response codes to human-readable decline reasons

​
Troubleshooting

  • Verify your Private Security Key is correct (copy-paste from NMI, no extra spaces)
  • Make sure the key has API source enabled
  • Check that the gateway URL matches your NMI login domain
  • Check that your NMI account has transaction history
  • Verify the key has permission to query transactions
  • Check the sync logs on the Gateway & Sync tab for errors
  • The key must have Tokenization source (not API or Cart)
  • It must be a Public key, not a Private key
  • Create a new public key in NMI with Tokenization source if needed