Sync & Data Import
uPayments uses a background worker (hosted on Railway) to sync data from your NMI gateway.How Syncing Works
- Every 15 minutes, the worker checks each NMI account
- Queries NMI for transactions modified since the last sync (
start_dateparameter) - Upserts transactions into the database (safe to re-run — deduplicates by NMI transaction ID)
- After transactions, extracts customers from email addresses
- 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
Sync shows 'Cannot decrypt API key'
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.Sync is stuck at 'Running'
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.
Transaction count doesn't match NMI
Transaction count doesn't match NMI
uPayments deduplicates by NMI transaction ID. If NMI shows more, some may be duplicate entries or internal settlement records (source=internal).