Adding New Merchants

Learn how to add new merchants to the FinMatch platform using the Add Merchant form.

Accessing the Form

1. Navigate to the Merchants page in the Admin Dashboard
2. Click the "+ Add Merchant" button in the top right corner of the merchants table
3. The "Add New Merchant" modal will open

Form Fields

Company Name *

• Required: Yes
• Purpose: The merchant's company name
• Saved to: merchants.json → profiles[merchantId].merchantName and profiles[merchantId].companyName
• Example: "Acme Corporation"

Domain *

• Required: Yes
• Purpose: The merchant's website domain
• Format: Enter host only (recommended), e.g. merchant.com
• Auto-normalization:
  • https:// / http:// is optional in input
  • www. is stripped
  • path/query fragments are removed
  • saved format is canonical https://merchant.com
• Validation: Must be a valid domain or URL
• Saved to: merchants.json → profiles[merchantId].domain
• Example:
  • Enter: merchant.com → Saved as: https://merchant.com
  • Enter: https://www.merchant.com/shop → Saved as: https://merchant.com

Testing domain

• Required: No
• Purpose: Optional test/sandbox domain for this merchant
• Format: Enter host only (recommended), e.g. merchant.com
• Auto-normalization: Same normalization rules as Domain
• Saved to:
  • merchants.json → profiles[merchantId].testing_domain
  • merchant-router.json → [merchantId].testing_domain
• CORS behavior: When set, this domain is auto-whitelisted alongside the primary domain

Domain Validation

The form shows https://example.com as a placeholder (in grey text). This is just a hint - you can enter:

• example.com (will be normalized to https://example.com)
• https://example.com (used as-is)
• http://example.com (used as-is, though HTTPS is recommended)

If the domain doesn't match the validation pattern, you'll receive an error message: "Domain must be a valid URL starting with http:// or https://"

Company Number

• Required: No
• Purpose: UK company registration number
• Saved to: merchants.json → profiles[merchantId].companyNo
• Example: "12345678"

Environment

• Required: No (defaults to Production)
• Purpose: Determines which environment the merchant uses (Test, Staging, or Production)
• 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
• Default: Production (p)

What Happens When You Submit

When you click "Add Merchant", the following happens:

1. Form Validation

   • Company Name and Domain are validated
   • Domain is normalized (https:// added if missing)
   • Domain format is validated against regex pattern

2. API Request

   • Data is sent to POST /api/merchants endpoint
   • Merchant API processes the request

3. Merchant ID Generation

   • A unique FinMatch ID is generated using the current format: M****** (6 digits)
   • Current format example: M290756
   • Legacy format (still supported for existing merchants): FM-XXXX-XXXX-XXXX
   • Legacy format example: FM-0294-8617-5039

4. Data Storage

   • Merchant profile is added to merchants.json in Google Cloud Storage
   • Merchant entry is added to merchant-router.json for domain routing
   • Primary domain and optional testing domain are synced to router metadata
   • CORS whitelist is updated automatically for both domains (base + www origins)
   • Status is set to pending by default

5. Success Response

   • Modal closes
   • Success message displays: "Merchant '[Company Name]' created successfully! ID: M******"
   • Merchants table automatically refreshes to show the new merchant

6. Merchant User Provisioning (Auth)

   • Admin flow also provisions/repairs a merchant auth user in auth-credentials.json
   • Provisioned user is role merchant with api:finance_assistant permission and a generated API key
   • If provisioning fails, merchant creation may still have succeeded; the UI shows an explicit reconciliation warning

Field Mapping Reference

Form Field	JSON Path	Router Path	Notes
Company Name	profiles[merchantId].merchantName profiles[merchantId].companyName	N/A	Stored in both fields
Domain	profiles[merchantId].domain	[merchantId].domain	Canonical https://host
Testing domain	profiles[merchantId].testing_domain	[merchantId].testing_domain	Optional, same normalization
Company Number	profiles[merchantId].companyNo	N/A	Optional field
Environment	profiles[merchantId].environment	[merchantId].environment	Default: 'p'
FinMatch ID	profiles[merchantId].finmatchId	N/A	Auto-generated
Status	profiles[merchantId].status	N/A	Default: 'pending'
Created At	profiles[merchantId].createdAt	N/A	ISO timestamp
Last Updated	profiles[merchantId].lastUpdated	N/A	ISO timestamp

What Does NOT Happen Automatically

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

• ❌ Snippet Deployment Check - The monitor service does NOT automatically check if the snippet is deployed. Deployment status is checked when you view the merchants page or manually trigger a check
• ❌ Stripe Connection - No Stripe customer is automatically linked. You must manually link a Stripe customer after creation

Merchant ID Change Safety (Critical)

Merchant ID edits are migration operations, not normal field edits.

• The old ID and new ID must be reconciled across:
  • merchants.json profile keys
  • merchant-router.json mapping keys
  • environment finmatch-merchant-config.json merchant entries
  • merchant auth-user mappings (merchantId + username)
• If any required env config update fails, the ID change should be treated as failed and rolled back where possible.
• Never manually edit only one location for an ID change; this causes config drift and can orphan lender settings.

Merchant History / Audit Requirements

All merchant profile updates must write a merchant history event.

• Required event actor metadata:
  • actor_type: admin_user or automation
  • actor_id / actor_name
  • change_source and endpoint context
  • timestamp and (when available) correlation ID
• This applies to both dashboard edits and automated sync/ingestion jobs.

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: Enter a valid host or URL (e.g., merchant.com, https://merchant.com)

"Failed to create merchant"

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

Best Practices

1. Use Full Domains - Enter complete domain names (e.g., example.com not just example)
2. Verify Domain Format - Ensure domains are valid URLs before submitting
3. Set Correct Environment - Use Test/Staging for development, Production for live merchants
4. Add Company Number When Available - Helps with merchant identification and CreditSafe integration
5. Link Stripe After Creation - Create the merchant first, then link the Stripe customer

Next Steps

After creating a merchant:

1. Edit the Merchant - Update any fields or link a Stripe customer
2. View Merchant Details - See full merchant information
3. Check Deployment Status - Verify if the FinMatch snippet is deployed
4. Link Stripe Customer - Connect billing information

Related Documentation

• Merchant Creation Architecture - Developer guide to what happens behind the scenes
• Editing Merchants - How to update merchant information
• Managing Merchants - General merchant management guide
• Merchant Users And Finance Assistant Keys - Identity/key lifecycle and reconciliation rules