Merchant onboarding

Use this runbook to onboard a merchant through Onboarding in the Support Portal at support.peakpos.co. The pipeline is the durable record for the job. Do not create the organization, first store, and owner invite as unrelated operations unless an approved recovery procedure requires it.

Boundary and ownership

The Support Portal calls management-api. It does not bypass service authorization:

• support users and agents must have mgmt.orgs.read to view pipelines and mgmt.orgs.write to change them;
• agent sessions are restricted to their assigned portfolio and product sale floor;
• Gateway operations require their own management permission in addition to the onboarding permission;
• organization activation is rejected by the backend while product-readiness blockers remain.

The merchant owns business facts and the operating configuration. Peak Support owns staff-only changes, secret-bearing Gateway work, final readiness review, activation, and safe escalation.

Preflight

Business and account

Confirm the following with the merchant:

• legal business name and nine-digit EIN;
• business email and phone;
• primary owner first name, last name, email, and phone;
• owning agent;
• store operating model;
• requested products: POS, Gateway, invoicing, services, and/or Age Verify.

Search both the onboarding queue and the client list before starting. If the business, EIN, owner email, or intended Gateway location already exists, stop and reconcile the existing record instead of creating a duplicate.

Organization, location, and tax

For a location-based product, collect the first store's street address, city, state, and ZIP. POS, Gateway, and invoicing selections require a street address and ZIP in the current pipeline.

The pipeline validates and stores the EIN, but it does not configure every store tax rate or customer exemption. Record who will verify tax configuration in the Retail Portal before trading begins. Do not invent rates or tax IDs on a merchant's behalf.

Staff and access

Confirm the intended owner email before creating the client. The owner invite is deliberately deferred until the organization is active. Collect any additional staff list and store assignments for a later access handoff; the onboarding pipeline creates only the primary owner handoff.

Catalog, terminals, and payments

Before marking configuration complete, identify:

• the catalog source and who will verify categories, products, prices, barcodes, inventory, and age restrictions;
• each terminal's destination store, display name, model, manufacturer, and serial number when the managed model requires one;
• the intended payment mode and device arrangement;
• Gateway DBA and contact email when Gateway is selected;
• the approved TransIT MID, TID/device ID, user ID, merchant ZIP, and four-digit MCC when Support will activate Gateway.

Never paste payment credentials into a ticket, this page, or general notes. Enter them only in the credential fields provided by the Support Portal.

Start the pipeline

1. Open Onboarding.
2. Select New Client.
3. Continue in the created pipeline.

The current step sequence is:

1. Business Information
2. Owner Information
3. Create Client
4. Payment Location — shown only when Gateway or invoicing requires it
5. Review Setup
6. Activation Readiness

Completed steps show Done. A step whose prerequisites are incomplete remains waiting. Business and owner intake can be edited until Create Client completes.

1. Business Information

Enter the business name, EIN, business email, optional phone, owning agent, operating model, address, and the Gateway contact/DBA fields when applicable.

The operating model selects the base product set and Gateway industry. The current base combinations include POS and Gateway for most storefronts, services for service/QSR models, Age Verify for regulated retail, and a Gateway-plus-invoicing option for online merchants. Optional products can be changed later in Review Setup.

Select Save & Continue only after the displayed base products and address requirements are correct. The organization slug is generated from the business name and pipeline ID; do not create or edit one manually.

2. Owner Information

Enter the primary owner's first name, last name, email, and optional phone, then select Save & Continue.

This records intake data only. It does not send an invitation or account setup email.

3. Create Client

Review the business, owner, agent, product, address, and Gateway summary, then select Create Client once.

The operation creates the organization and first store, records the owner, associates the owning agent, creates and verifies a Gateway location when required, saves plan settings, enables the selected entitlements, and records the organization/store IDs in the pipeline. It requests deferOwnerInvite: true; no owner welcome email is sent at this stage.

If the portal says the client was created but a later plan, entitlement, or Gateway verification step failed:

1. search for the organization and first store;
2. inspect the pipeline's recorded IDs and progress message;
3. correct the failed downstream setup;
4. retry from the same pipeline.

Do not create another pipeline for the same merchant.

4. Payment Location

This step appears only when Gateway setup is required. Confirm that the displayed Gateway location belongs to the new organization and first store.

Peak Support may then:

• enter the TransIT fields and select Activate Gateway Now;
• select an active credential profile, re-enter the required TransIT fields, and select Use Existing Profile and Activate; or
• select Delay Activation when credentials are not ready and assign the blocker to a named owner.

Saved profiles do not reveal TID/device ID or user ID secrets, so those values must be entered again. A delayed step is not evidence that payment readiness is complete.

5. Review Setup

Review the embedded plan and every setup card selected by the operating model:

• Point of Sale — store settings, catalog ownership, terminal plan, and payment configuration;
• Invoicing — billing terms, invoice/payment-link access, and finance handoff;
• Payments Gateway — location state, store binding, settlement context, and payment-device readiness;
• Services & Booking — service catalog, availability, booking, and deposit setup;
• Age Verify — regulated-retail policy and staff handoff.

Use Open Client Tools, Review Billing, or Open Gateway to complete the underlying work. Optional products can be changed in the embedded plan.

Select Mark Configuration Complete only when each applicable item has evidence or a documented post-activation owner. The button records completion; it does not prove that catalog, tax, terminal, or payment configuration is correct.

6. Activation Readiness

1. Load Product readiness and read every blocker and warning.
2. Review Provisioning tasks. Retry a failed task only after correcting its cause.
3. Confirm every required Gateway, catalog, tax, access, terminal, and operational handoff has an owner.
4. When the backend reports Ready, select Activate Client.
5. Confirm the page reports Client is active.
6. Select Send Welcome Email & Complete.

The last action completes the pipeline and queues the owner welcome/setup email. Use Resend Welcome Email only after activation when the owner needs a fresh setup or password-reset link.

Operator handoff

Work	Merchant	Agent	Peak Support
Confirm business, owner, location, tax, catalog, and operating facts	Owns the facts	May collect and enter them	Verifies before activation
Start and progress an assigned pipeline	Supplies decisions	Allowed within assigned portfolio and permissions	Allowed with management permissions
Select plan/products	Approves	Limited by agent sale floor	May configure approved products
Create or assign a Gateway credential profile	Supplies approved credentials through the secure process	Escalates when not permitted	Performs secret-bearing setup with Gateway permission
Configure merchant staff, store membership, IAM groups, and roles	Owns after access	Assists only within assigned scope	Diagnoses; does not invent access
Configure catalog, tax, terminals, and payment devices	Owns operational acceptance	Coordinates the handoff	Verifies readiness and staff-only steps
Activate the client and send the deferred owner welcome email	Confirms readiness	May see remaining blockers	Owns final support review and handoff
Merge/delete duplicates or perform destructive repair	Provides confirmation	Escalates	Uses a separate approved recovery procedure

Completion evidence

Record evidence, not just button clicks:

• pipeline status is completed and the organization is active;
• organization, first store, owning agent, EIN, address, operating model, and selected products match the merchant's approval;
• product readiness has no blockers;
• applicable provisioning tasks are completed; no failed task is being ignored;
• the first store has a tax and catalog owner, and their review is complete or explicitly scheduled;
• Gateway location, credential profile, store binding, and payment-device state are correct when payments are enabled;
• each planned terminal is assigned to the correct store and has a named provisioning owner;
• the owner welcome email was queued to the intended address;
• the owner accepted the latest invitation and can see the correct organization in portal.peakpos.co.

Failure handling

Activation remains blocked

Use the backend readiness cards as the source of truth. Resolve the named product blocker, refresh readiness, and retry. A direct API call cannot bypass the gate.

Owner invite is missing

Confirm the organization is active and Send Welcome Email & Complete was selected. Inspect the owner_invite provisioning task, correct the owner email if necessary, and retry a failed task. Do not expect an invite immediately after Create Client.

Owner accepted but has no organization

Confirm the sign-in email matches the latest invitation and inspect the user's organization membership. Use the user-management runbook to diagnose access; do not add an arbitrary role as a workaround.

Duplicate or partial client

Stop. Preserve the pipeline and both record IDs, do not send more invitations or provision terminals, and escalate for approved reconciliation.

Escalate with the pipeline ID, organization/store IDs, owning agent, failed step, exact backend message, readiness blocker/task ID, and the last action taken. Never include Gateway secrets.