Adding New Merchants

Open Merchants → Add Merchant. Add New Merchant opens. The form section is Merchant Information. Cancel closes without creating.

Fill the form

Field	What to enter
**Company Name ***	Required.
**Domain ***	Host only. Placeholder: merchant.com. https:// / http:// is optional; www. and path/query are stripped; saved as https://host.
Testing domain	Optional. Same placeholder and normalization as Domain. When set, it is CORS-whitelisted with the primary domain.
Company Number	Optional UK company number.
Environment	Production (p, default), Staging (s), or Test (t).
FCA status (optional)	Not specified (default), Authorised, or Not authorised. Create never requires this. Only Not authorised changes live copy. Merchant FCA status.

Submit

1. Click Add Merchant at the bottom of the form (not the toolbar button that opened it).
2. Client checks first: Company name is required. / Domain is required. / Form elements not found.
3. If the name is ≥80% similar to an existing merchant, or the domain matches exactly (protocol / www. ignored), Potential Duplicate Merchant opens on top of the form. It does not open before you submit. Potential duplicate.
4. If there is no duplicate hit, the submit button shows Adding... until POST /api/merchants finishes.

Success: toast Merchant "name" created successfully! ID: plus the new M****** id. The form closes and the table reloads. A create with no Stripe customer shows Suspended (billing inactive). Linking Stripe typically moves it to Pending until FinMatch and at least one lender are approved. Status is computed (merchantStatus); it is not a stored status field and does not take the snippet offline.

The create also provisions a merchant auth user. If that step fails after the profile exists: Merchant id was created, but merchant user provisioning failed: plus the reason, then Run "Sync Merchant API Keys" in Users to reconcile. Users. When provision succeeds, auth-api writes the Finance Assistant key to Cloudflare KV once credentials are configured — operators do not paste that pair by hand. Merchant users & FA keys.

If the company was previously terminated: This company was previously terminated and cannot be re-registered. If this is intended, reinstate the existing terminated merchant instead of creating a new one. Merchant Status clicks.

Other create failures: Failed to create merchant. Please try again. or the API reason. Adding... returns to Add Merchant.

Potential duplicate

Potential Duplicate Merchant says We found similar merchants that might be duplicates: then What would you like to do?

• Edit an existing merchant below
• Or proceed to create a new merchant anyway

Name hits: Similar Merchant Name Found plus the similarity percentage. Domain hits: Exact Domain Match Found. Each row shows the company name, id, and domain.

Click	What happens
A match row	Closes the warning and opens that merchant. The new merchant is not created.
Create New Merchant Anyway	Closes the warning and runs the create (Adding...).
Cancel	Closes the warning and returns to Add New Merchant. Nothing is created.

What does not happen

• Creating a merchant does not crawl the domain. Use Check snippet on the merchant page, or wait for the next snapshot.
• No Stripe customer is linked. Use Link Customer after create. Managing Merchants.

Next Steps

1. Edit the Merchant — inline Edit Merchant
2. Merchant Page Editing — Overview cards
3. Check snippet status
4. Link Stripe Customer

Architecture of the write path: Merchant Creation Architecture.