Merchant Accounts Page

Manage NMI security key mappings for PayArc Merchant IDs (MIDs) to enable automatic chargeback linkage and processing.

Overview

The Merchant Accounts page provides a simple interface to map PayArc Merchant IDs (MIDs) to NMI Transaction API security keys. This mapping is critical for the chargeback processor to:

Receive PayArc dispute webhook (contains MID)
Look up corresponding NMI security key
Query NMI Transaction API for original transaction details
Link dispute to order in middleware database

Without proper MID → NMI key mapping, chargebacks cannot be automatically linked to orders.

Access: GSM Middleware → Merchant Accounts (menu position 11)

Permission Required: manage_options

Interface Overview

Title: "NMI Merchant Accounts"

Description:

Manage the NMI security key mappings used to process PayArc chargebacks. Each Merchant ID (MID) must have a corresponding NMI security key so disputes can be linked to the originating NMI transaction.

MID Location Tip:

Where to find the MID: The MID appears in the mid field of PayArc webhook payloads (e.g. "567000000016287").

Accounts Table

Columns:

Column	Description	Example
Merchant ID (MID)	PayArc MID (numeric)	`567000000016287`
Label	Friendly name (optional)	`GSM Live`
NMI Security Key	Masked key display	`••••••••••••`
Actions	Edit / Delete buttons	Edit \| Delete

Empty State:

No merchant accounts configured. Click "Add Account" to create one.

Add Account Button

Location: Below table

Button text: "Add Account"

Style: Primary (blue)

Action: Opens Add Merchant Account modal

Managing Accounts

Adding a New Account

Goal: Configure NMI key for a new PayArc MID

Steps:

Click "Add Account" button at bottom of table
Modal opens: "Add Merchant Account"
Fill in form fields:

Merchant ID (MID) Required
- Type: Numeric string
- Example: 567000000016287
- Where to find: PayArc webhook payload (mid field)
- Placeholder: 567000000016287
Label Optional
- Type: Text
- Example: GSM Live, GSM Beta, Site A Production
- Purpose: Friendly name to identify account
- Placeholder: e.g. GSM Live, GSM Beta
NMI Security Key Required
- Type: Password (hidden when typing)
- Format: Alphanumeric string (varies by NMI account)
- Where to find: NMI Gateway → Settings → Security Keys
- Placeholder: Enter NMI security key
Click "Save Account" button
Success: Modal closes, table refreshes with new account row
Verify: New MID appears in table with label and masked key

Success message:

✅ Merchant account for MID 567000000016287 added successfully.

Editing an Account

Goal: Update label or NMI key for existing MID

Steps:

Locate account in table by MID or label
Click "Edit" button in Actions column
Modal opens: "Edit Merchant Account"
Form pre-populated with:
- Merchant ID (MID) — Read-only (cannot change MID itself)
- Label — Current value
- NMI Security Key — Blank (for security, must re-enter to update)
Update fields as needed:
- Change label: Type new friendly name
- Change NMI key: Enter new security key
- Leave NMI key blank to keep existing key unchanged
Click "Save Account" button
Success: Modal closes, table refreshes with updated values

Success message:

✅ Merchant account for MID 567000000016287 updated successfully.

Deleting an Account

Goal: Remove MID → NMI key mapping when no longer needed

Steps:

Locate account to delete in table
Click "Delete" button in Actions column
Confirmation prompt:

⚠️ Are you sure you want to delete the merchant account for MID 567000000016287? This action cannot be undone.
Click "OK" to confirm deletion
Success: Row removed from table

Success message:

✅ Merchant account deleted successfully.

Warning: If chargebacks are received for this MID after deletion, they will fail to link to orders (no NMI key available for transaction lookup).

Form Field Details

Merchant ID (MID)

Purpose: Unique identifier for PayArc merchant account

Format:

Numeric string (typically 15 digits)
Example: 567000000016287

Where to find:

PayArc webhook payload:

{
  "api_response": {
    "mid": "567000000016287"
  }
}

PayArc dashboard: Account → Merchant Info → MID
Ask PayArc support if unsure

Validation:

Required field
Should be numeric (letters/symbols invalid)
Must be unique (cannot add same MID twice)

Label

Purpose: Human-friendly name to identify account

Format:

Text (any characters allowed)
Max 100 characters
Example: GSM Live, Site A Production, Beta Testing Account

Best practices:

Include environment: GSM Live vs GSM Staging
Include site/brand: Site A Live, Site B Dev
Stay brief: Main Account ✅, This is our primary production merchant account for live transactions ❌

Validation:

Optional field (can leave blank)
Not unique (multiple accounts can have same label)

NMI Security Key

Purpose: API key to authenticate with NMI Transaction API

Format:

Alphanumeric string (varies by NMI configuration)
Typically 20-40 characters
Example: 2F822Rw39fx762MaV7Yy41zU

Where to find:

NMI Gateway dashboard:
- Log in to NMI Merchant Portal
- Settings → Security Keys
- Copy "Transaction API Security Key"
NMI support: Request if lost (cannot retrieve, must regenerate)

Security considerations:

Never share NMI keys publicly (commit to Git, paste in chat)
Stored encrypted in database (not plaintext)
Masked in UI — Shows ••••••••••••, cannot be retrieved via frontend
Password field — Hidden when typing for shoulder surfing protection

Validation:

Required field (when adding new account)
Optional when editing (leave blank to keep existing key)
No format validation (NMI accepts various formats)

Common Workflows

Initial Setup: Configuring First MID

Goal: Add first PayArc merchant account for chargeback processing

Prerequisites:

PayArc account configured and receiving transactions
NMI gateway account with Transaction API access
MID from PayArc account settings

Steps:

Gather information:
- Log in to PayArc dashboard → Account → Copy MID
- Log in to NMI dashboard → Settings → Security Keys → Copy Transaction API key
- Choose label (e.g., "GSM Live")
Navigate to Merchant Accounts page:
- GSM Middleware → Merchant Accounts
Click "Add Account"
Fill form:
- MID: 567000000016287
- Label: GSM Live
- NMI Key: 2F822Rw39fx762MaV7Yy41zU
Save and verify:
- Click "Save Account"
- See success message
- Verify row appears in table
Test chargeback flow:
- Go to Testing Tools page
- Click "Send Test Chargeback Webhook"
- Select MID: 567000000016287
- Submit test
- Check Chargebacks page to verify linkage worked

Expected outcome: Chargeback appears in Chargebacks page with linked order and "Completed" status

Adding Multiple Sites (Multi-MID Setup)

Goal: Configure 5 PayArc accounts for different sites/brands

Scenario: Company operates 5 e-commerce sites, each with own PayArc MID

Steps:

Create spreadsheet:

Site	MID	NMI Key	Label
Site A	567000000016287	2F822Rw39fx762MaV7Yy41zU	Site A Live
Site B	567000000016288	8X931Cv28dy651JbU6Wx32tR	Site B Live
Site C	567000000016289	5Y642Dx17cz540KaT5Vx21sQ	Site C Live
Site D	567000000016290	7Z853Ey06by439LaS4Uy10rP	Site D Live
Site E	567000000016291	4A964Fz95ax328MaR3Tx09qO	Site E Live

For each site, add account:
- Click "Add Account"
- Copy MID from spreadsheet
- Copy label
- Copy NMI key
- Click "Save Account"
- Repeat for next site
Verify all 5 accounts in table
Test each MID:
- Send test chargeback webhook for each MID
- Verify linkage works for all 5

Time estimate: 5-10 minutes for 5 accounts

Credential Rotation: Updating NMI Keys

Goal: Replace compromised or expired NMI keys

Scenario: Security audit requires rotating all NMI API keys

Steps:

Phase 1: Generate new keys in NMI

Log in to each NMI account
Settings → Security Keys
Click "Regenerate Transaction API Key"
Copy new key immediately (NMI only shows once)
Keep old key active for now (don't revoke yet)

Phase 2: Update in GSM Middleware

For each MID in Merchant Accounts table:
- Click "Edit"
- Paste new NMI key
- Click "Save Account"
Repeat for all accounts

Phase 3: Test

Send test chargeback webhook for one MID
Verify chargeback links successfully to order
If successful, proceed to Phase 4
If failed, revert to old key (re-edit, paste old key)

Phase 4: Revoke old keys

Return to NMI gateway
Revoke old Transaction API keys
Confirm revoked keys no longer work (test chargeback should fail with old key)

Rollback plan: If issues occur after rotation, re-enter old keys in Phase 2 before revoking in Phase 4

Troubleshooting Failed Chargeback Linkage

Goal: Diagnose why chargeback not linking to order

Symptoms:

Chargeback appears in Chargebacks page with "Failed" status
Order Number shows "—" (dash)
Error message: "No NMI security key configured for MID 567000000016287"

Steps:

Check if MID configured:
- Navigate to Merchant Accounts page
- Search table for MID from error message
- If not found: MID not configured, proceed to Step 2
- If found: MID exists, proceed to Step 4
Add missing MID:
- Click "Add Account"
- Enter MID: 567000000016287
- Enter label and NMI key
- Save account
Re-process chargeback:
- Go to Testing Tools → Chargeback Testing
- Re-send same chargeback webhook
- Check Chargebacks page for success
Verify NMI key correct:
- Click "Edit" on MID row
- Cannot see key (security), but can test:
- Go to Testing Tools → NMI Connection Test
- Enter MID's NMI key manually
- Click "Test Connection"
- If fails: NMI key invalid, get correct key from NMI dashboard
- If succeeds: NMI key valid, issue elsewhere
Check NMI transaction exists:
- Log in to NMI gateway
- Search for transaction ID from chargeback
- If not found: Transaction doesn't exist in NMI (payment processed elsewhere?)
- If found: Transaction exists, linkage should work

Common causes:

MID not configured (most common)
NMI key typo when originally entered
NMI key expired/revoked
Transaction not in NMI (payment via different gateway)

Security Considerations

NMI Key Protection

Storage:

✅ Keys encrypted before storing in database (WordPress encryption functions)
✅ Keys masked in UI (••••••••••••)
✅ Cannot retrieve keys via frontend (read-only masking)
✅ Cannot view via REST API without authentication

Access control:

⚠️ Requires manage_options capability (WordPress Administrator)
❌ Shop Managers, Editors cannot access
✅ Audit log: All add/edit/delete actions logged in debug.log

Best practices:

Rotate keys annually — Even if not compromised, proactive security
Use separate NMI accounts per environment — Dev, staging, prod should have different keys
Test after rotation — Always verify one chargeback links successfully before revoking old keys
Document MID → Site mapping — Keep spreadsheet outside WordPress for disaster recovery
Limit admin access — Only grant manage_options to trusted admins

Credential Backup

Export/Import support:

✅ Merchant accounts included in Export/Import page
✅ Export includes decrypted keys in JSON (plaintext)
⚠️ Export file must be stored securely (encrypted storage recommended)

Backup strategy:

Export configuration monthly (automated via WP-CLI)
Store encrypted backup off-server (S3 with encryption, 1Password)
Test restore quarterly (import on staging environment)
Keep 3 months of backups (rotate older exports)

Data Storage

Database

WordPress Option: gsm_nmi_merchant_accounts

Structure:

[
    [
        'id' => 1,
        'mid' => '567000000016287',
        'label' => 'GSM Live',
        'nmi_key' => 'encrypted:AES256:base64encodedciphertext...',
    ],
    [
        'id' => 2,
        'mid' => '567000000016288',
        'label' => 'Site A Beta',
        'nmi_key' => 'encrypted:AES256:base64encodedciphertext...',
    ],
]

Encryption method:

Algorithm: AES-256-CBC (via WordPress encryption library)
Key: WordPress AUTH_KEY and SECURE_AUTH_KEY salts
Storage: nmi_key field prefixed with encrypted: indicator

Repository: src/Database/Merchant_Accounts_Repository.php

AJAX Endpoints

Get All Accounts:

Action: wp_ajax_gsm_get_merchant_accounts
Method: POST
Nonce: gsm_merchant_accounts
Response: Array of accounts with masked keys

Add Account:

Action: wp_ajax_gsm_add_merchant_account
Method: POST
Parameters: mid, label, nmi_key
Response: New account ID and success message

Update Account:

Action: wp_ajax_gsm_update_merchant_account
Method: POST
Parameters: id, mid, label, nmi_key (optional)
Response: Success message

Delete Account:

Action: wp_ajax_gsm_delete_merchant_account
Method: POST
Parameters: id
Response: Success message

Troubleshooting

"Merchant ID is required" Error

Cause: MID field left blank

Solution:

Fill in MID field with numeric string
Copy from PayArc webhook or dashboard
Must be numeric only (no letters/special characters)

"NMI security key is required" Error

Cause: NMI key field left blank when adding new account

Solution:

Log in to NMI gateway
Settings → Security Keys
Copy "Transaction API Security Key"
Paste into NMI Security Key field
If key doesn't exist, generate one in NMI first

"Merchant ID already exists" Error

Cause: Attempting to add duplicate MID

Solution:

Check table - MID already configured
If need to update, click "Edit" instead of "Add Account"
If duplicate is error (different account with same MID), verify with PayArc support

Cannot Retrieve Lost NMI Key

Cause: NMI keys cannot be retrieved after initial generation (security feature)

Solution:

If key stored elsewhere: Retrieve from password manager, documentation
If key lost: Must regenerate in NMI gateway:
- Log in to NMI dashboard
- Settings → Security Keys
- Click "Regenerate Transaction API Key"
- Copy new key immediately (only shown once)
- Update in Merchant Accounts page
- Test with chargeback webhook

Chargebacks Still Failing After Adding MID

Cause: NMI key incorrect or transaction not in NMI

Solution:

Verify NMI key:
- Go to Testing Tools page
- Test NMI connection with key
- If fails, regenerate key in NMI and re-enter
Check transaction existence:
- Log in to NMI gateway
- Search for transaction ID from chargeback
- If not found, payment may have processed via different gateway
Check MID match:
- Verify MID in webhook payload matches MID in Merchant Accounts
- Even one digit off causes failure

Edit Button Does Nothing

Cause: JavaScript error or cache issue

Solution:

Check browser console:
- Press F12 → Console tab
- Look for JavaScript errors
- Share error message with support if present
Clear cache:
- Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
- Or clear browser cache completely
Disable conflicting plugins:
- Deactivate other plugins temporarily
- Test if Edit button works
- Re-activate plugins one by one to identify conflict

Chargebacks Page — View and manage disputes
Export/Import — Backup/restore merchant accounts
Testing Tools — Test chargeback flow, NMI connection
Database Schema — Data storage details

Best Practices

Configure all MIDs upfront — Add all merchant accounts during initial setup
Use descriptive labels — Site A Live, Site B Staging vs. generic Account 1
Test after adding — Send test chargeback webhook to verify MID → NMI linkage works
Backup before rotation — Export configuration before updating NMI keys
Test one, apply all — When rotating keys, test one MID first, then update rest
Document mapping — Keep MID → Site → NMI Account spreadsheet for reference
Limit access — Only grant manage_options to trusted administrators
Rotate annually — Proactive security by regenerating NMI keys yearly
Monitor chargeback logs — Check Chargebacks page daily for "Failed" status
Encrypt backups — If exporting merchant accounts, encrypt JSON file

Overview​

Interface Overview​

Page Header​

Accounts Table​

Add Account Button​

Managing Accounts​

Adding a New Account​

Editing an Account​

Deleting an Account​

Form Field Details​

Merchant ID (MID)​

Label​

NMI Security Key​

Common Workflows​

Initial Setup: Configuring First MID​

Adding Multiple Sites (Multi-MID Setup)​

Credential Rotation: Updating NMI Keys​

Troubleshooting Failed Chargeback Linkage​

Security Considerations​

NMI Key Protection​

Credential Backup​

Data Storage​

Database​

AJAX Endpoints​

Troubleshooting​

"Merchant ID is required" Error​

"NMI security key is required" Error​

"Merchant ID already exists" Error​

Cannot Retrieve Lost NMI Key​

Chargebacks Still Failing After Adding MID​

Edit Button Does Nothing​

Related Documentation​

Best Practices​

Overview

Interface Overview

Page Header

Accounts Table

Add Account Button

Managing Accounts

Adding a New Account

Editing an Account

Deleting an Account

Form Field Details

Merchant ID (MID)

Label

NMI Security Key

Common Workflows

Initial Setup: Configuring First MID

Adding Multiple Sites (Multi-MID Setup)

Credential Rotation: Updating NMI Keys

Troubleshooting Failed Chargeback Linkage

Security Considerations

NMI Key Protection

Credential Backup

Data Storage

Database

AJAX Endpoints

Troubleshooting

"Merchant ID is required" Error

"NMI security key is required" Error

"Merchant ID already exists" Error

Cannot Retrieve Lost NMI Key

Chargebacks Still Failing After Adding MID

Edit Button Does Nothing

Related Documentation

Best Practices