> ## Documentation Index
> Fetch the complete documentation index at: https://test-docs.upayments.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect NMI Gateway

> How to find your NMI credentials and connect your gateway

# Connecting Your NMI Gateway

FinMI 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.

<Warning>
  Private keys should never be shared publicly or stored in client-side code. FinMI encrypts your private key at rest using AES-256-GCM.
</Warning>

**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 FinMI payment pages.

<Tip>
  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 "FinMI".
</Tip>

## Gateway URL

Your gateway URL is the base domain where your NMI API is hosted:

| Processor    | Gateway URL                                                      |
| ------------ | ---------------------------------------------------------------- |
| NMI Direct   | `https://secure.nmi.com`                                         |
| ECS Payments | `https://ecspayments.transactiongateway.com`                     |
| Other        | Check with your processor — it's the domain in your API endpoint |

<Info>
  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.
</Info>

## Adding Credentials in FinMI

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:

| Data               | Method                       | Frequency        |
| ------------------ | ---------------------------- | ---------------- |
| **Transactions**   | NMI Query API                | Every 15 minutes |
| **Customer Vault** | `report_type=customer_vault` | Every 15 minutes |
| **Subscriptions**  | `report_type=recurring`      | Every 15 minutes |

Additionally, FinMI 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

<AccordionGroup>
  <Accordion title="Connection test fails with 'Invalid credentials'">
    * 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
  </Accordion>

  <Accordion title="Sync runs but shows 0 transactions">
    * 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
  </Accordion>

  <Accordion title="Tokenization key not working for payment pages">
    * 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
  </Accordion>
</AccordionGroup>