Skip to main content

Editing Merchants

Learn how to edit merchant information, including the FinMatch ID, and understand the validation rules.

Legacy Flow Reference

The primary editing flow is now inline on the merchant detail page.
See Merchant Page Editing for the current UX and controls.

Accessing the Edit Form​

  1. Navigate to the Merchants page in the Admin Dashboard
  2. Find the merchant you want to edit in the table
  3. Click the "⋯" (three dots) button in the Actions column
  4. Select "✏️ Edit" from the dropdown menu
  5. The "Edit Merchant" modal will open

Form Fields​

FinMatch ID​

  • Display: Shows the current FinMatch ID (e.g., M290756 or legacy FM-0294-8617-5039)
  • Editable: Yes, but with restrictions
  • Validation:
    • Must match one of:
      • Current format: MXXXXXX (6 digits)
      • Legacy format: FM-XXXX-XXXX-XXXX (backward-compatible)
    • Cannot overwrite an existing FinMatch ID - If you try to change to an ID that already exists, you'll receive an error
    • If left unchanged, the original ID is preserved
  • Saved to: merchants.json → profiles[merchantId].finmatchId
  • Purpose: Unique identifier for the merchant across all FinMatch systems
FinMatch ID Changes

Changing a FinMatch ID can break integrations and references. Only change it if absolutely necessary, and ensure all systems are updated accordingly.

Company Name *​

  • Required: Yes
  • Editable: Yes
  • Saved to: merchants.json → profiles[merchantId].merchantName and profiles[merchantId].companyName
  • Purpose: The merchant's company name displayed throughout the system

Domain *​

  • Required: Yes
  • Editable: Yes
  • Format: Enter host only (recommended), e.g. merchant.com
  • Auto-normalization:
    • protocol is optional at input
    • www. is removed
    • path/query fragments are removed
    • saved as canonical https://merchant.com
  • Validation: Must be a valid domain or URL
  • Saved to:
    • merchants.json → profiles[merchantId].domain
    • merchant-router.json → [merchantId].domain (if changed)
  • Purpose: The merchant's website domain used for routing and snippet deployment

Testing domain​

  • Required: No
  • Editable: Yes
  • Format: Enter host only (recommended), e.g. merchant.com
  • Auto-normalization: Same canonicalization rules as Domain
  • Saved to:
    • merchants.json → profiles[merchantId].testing_domain
    • merchant-router.json → [merchantId].testing_domain
  • Purpose: Optional test/sandbox domain for validation, CORS, and routing metadata

Company Number​

  • Required: No
  • Editable: Yes
  • Saved to: merchants.json → profiles[merchantId].companyNo
  • Purpose: UK company registration number for CreditSafe integration

Environment​

  • Required: No
  • Editable: Yes
  • Options:
    • Production (p) - Live merchant website
    • Staging (s) - Staging/test environment
    • Test (t) - Development/testing
  • Saved to:
    • merchants.json → profiles[merchantId].environment
    • merchant-router.json → [merchantId].environment (automatically synced)
  • Purpose: Determines which environment the merchant uses

What Happens When You Submit​

When you click "Save Changes", the following happens:

  1. Form Validation

    • Company Name and Domain are validated
    • Domain is normalized (https:// added if missing)
    • FinMatch ID format is validated
    • FinMatch ID uniqueness is checked (if changed)

  2. API Request

    • Data is sent to PUT /api/merchants/:id endpoint
    • Merchant API processes the update

  3. Data Updates

    • Merchant profile is updated in merchants.json
    • If environment/domain/testing domain changed, merchant-router.json is updated
    • CORS whitelist is auto-updated for primary + testing domains (including www variants)
    • lastUpdated timestamp is set to current time

  4. Success Response

    • Modal closes
    • Success message displays: "Merchant '[Company Name]' updated successfully!"
    • Merchants table automatically refreshes to show updated information

FinMatch ID Validation​

Format Validation​

  • Must match either:
    • MXXXXXX (6 digits)
    • FM-XXXX-XXXX-XXXX (legacy)
  • Example valid IDs:
    • ✅ M000101
    • ✅ M290756
    • ✅ FM-0294-8617-5039
    • ✅ FM-1000-9999-1234 (legacy)
  • Example invalid IDs:
    • ❌ M12345 (only 5 digits)
    • ❌ M1234567 (7 digits)
    • ❌ MABC123 (contains letters)
    • ❌ FM-294-8617-5039 (first part only 3 digits)
    • ❌ FM-02948-617-5039 (first part 5 digits)
    • ❌ FM-0294-8617 (missing third part)

Uniqueness Validation​

  • Cannot overwrite existing IDs: If you try to change a merchant's ID to one that already exists, the update will fail
  • Error message: "FinMatch ID already exists. Please choose a different ID."
  • Current ID: You can keep the current ID unchanged (no validation needed)

When ID Changes Are Allowed​

  • The new ID must not exist in the system
  • The new ID must match the format pattern
  • All validation passes

Field Mapping Reference​

Form FieldJSON PathRouter PathAuto-Sync
FinMatch IDprofiles[merchantId].finmatchIdN/ANo
Company Nameprofiles[merchantId].merchantName
profiles[merchantId].companyName		N/ANo
Domainprofiles[merchantId].domain[merchantId].domainYes (if changed)
Testing domainprofiles[merchantId].testing_domain[merchantId].testing_domainYes (if changed)
Company Numberprofiles[merchantId].companyNoN/ANo
Environmentprofiles[merchantId].environment[merchantId].environmentYes (if changed)
Last Updatedprofiles[merchantId].lastUpdatedN/AAuto (timestamp)

Router Synchronization​

When you change Environment, Domain, or Testing domain:

  1. Merchant profile is updated in merchants.json
  2. Automatically, router metadata is synced in merchant-router.json
  3. This ensures routing consistency across systems

Code Reference: cloud-run/merchant-api/index.js → PUT /api/merchants/:id

Error Handling​

Common Errors​

"Company name is required"

  • Solution: Enter a company name in the Company Name field

"Domain is required"

  • Solution: Enter a domain in the Domain field

"Domain must be a valid domain or URL (e.g., merchant.com)"

  • Solution: Ensure the domain is a valid host or URL (e.g., merchant.com, https://merchant.com)

"Testing domain must be a valid domain or URL (e.g., merchant.com)"

  • Solution: Use the same valid host/URL format as the primary domain, or leave blank

"FinMatch ID format is invalid"

  • Solution: Ensure the ID matches MXXXXXX (6 digits) or legacy FM-XXXX-XXXX-XXXX

"FinMatch ID already exists"

  • Solution: Choose a different FinMatch ID that doesn't exist in the system

"Merchant not found"

  • Solution: The merchant may have been deleted. Refresh the page and try again.

"Failed to update merchant"

  • Solution: Check network connection, verify API is accessible, check browser console for details

Best Practices​

  1. Preserve FinMatch IDs - Only change FinMatch IDs when absolutely necessary
  2. Verify Domain Changes - Ensure domain changes don't break existing integrations
  3. Use Host-Only Input - Prefer merchant.com; admin handles protocol and www normalization
  4. Test Environment Changes - Verify routing works correctly after environment changes
  5. Document Changes - Note significant changes in merchant records for audit purposes

What Does NOT Happen Automatically​

The following actions are NOT performed automatically when editing a merchant:

  • ❌ Snippet Deployment Re-check - Deployment status is not automatically re-checked after domain changes
  • ❌ Stripe Connection Update - Stripe connections are not affected by merchant edits