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

# Sync & Data Import

> How transaction syncing works and how to configure it

# Sync & Data Import

FinMI uses a background worker (hosted on Railway) to sync data from your NMI gateway.

## How Syncing Works

1. **Every 15 minutes**, the worker checks each NMI account
2. Queries NMI for transactions modified since the last sync (`start_date` parameter)
3. Upserts transactions into the database (safe to re-run — deduplicates by NMI transaction ID)
4. After transactions, extracts customers from email addresses
5. Optionally detects subscriptions from payment patterns

## Sync Types

| Type              | When                    | What It Does                                                                                 |
| ----------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| **Incremental**   | Every 15 min (auto)     | Fetches only new/modified transactions since last sync                                       |
| **Manual Sync**   | Click "Sync" button     | Same as incremental but immediate                                                            |
| **Full Backfill** | Click "Backfill" button | Re-syncs ALL transaction history. Also backfills descriptions, decline reasons, and BIN data |

## What Gets Synced

| Field               | Source                                                               |
| ------------------- | -------------------------------------------------------------------- |
| Transaction ID      | `transaction_id`                                                     |
| Amount              | `amount`                                                             |
| Status              | Mapped from `condition` (pending, complete, failed, canceled)        |
| Type                | Mapped from `action.action_type` (sale, refund, auth, capture, void) |
| Customer name/email | `first_name`, `last_name`, `email`                                   |
| Card details        | `cc_type`, card last 4, BIN                                          |
| Description         | `order_description`                                                  |
| Decline info        | `action.response_code`, `action.response_text`                       |
| Source              | `action.source` (api, virtual\_terminal, recurring, etc.)            |
| Entry mode          | Keyed, Swiped, etc.                                                  |

## Sync History

View sync history on the **Merchants → \[Merchant] → Gateway & Sync** tab. Each entry shows:

* Sync type (incremental/backfill)
* Status (completed/failed/running)
* Records processed (transactions, customers, subscriptions)
* Duration
* Timestamp

## Performance

* Processes \~1,000 transactions per minute
* Initial backfill of 10,000 transactions takes \~10 minutes
* Incremental syncs typically complete in under 30 seconds
* Sequential processing (one account at a time) to avoid connection limits

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sync shows 'Cannot decrypt API key'">
    The encryption key on the worker doesn't match the one used to encrypt the API key. Verify `ENCRYPTION_KEY` matches between Vercel and Railway.
  </Accordion>

  <Accordion title="Sync is stuck at 'Running'">
    A stale job from a previous deployment. The worker automatically cleans up jobs that haven't updated in 10 minutes.
  </Accordion>

  <Accordion title="Transaction count doesn't match NMI">
    FinMI deduplicates by NMI transaction ID. If NMI shows more, some may be duplicate entries or internal settlement records (source=internal).
  </Accordion>
</AccordionGroup>