Merchant Onboarding Guide
Overview
This guide walks through the complete merchant onboarding journey — from signing up for SalesArck to processing the first real transaction with rewards flowing to a consumer wallet.
Onboarding Sequence
Step-by-Step Walkthrough
Step 1 — Register & Authenticate
Navigate to the Merchant Portal and enter your business phone number. You'll receive a one-time passcode (OTP) via SMS. Enter it to authenticate.
What happens behind the scenes:
- Phone number is normalized (E.164 format) and looked up
- Supabase Auth generates and delivers the OTP via SMS
- OTP windows and retry limits are enforced by Supabase Auth
- On successful verification, short-lived access token + refresh session are issued
Step 2 — Create Your Tenant
Fill in your business name and category. This creates your Tenant record, which is the top-level container for your merchants, consumers, and loyalty data.
Your JWT is re-issued with the tenantId claim embedded. All subsequent API calls are scoped to your tenant automatically.
Step 3 — Connect Your POS
Click Connect Square (or Clover) in the portal. You'll be redirected to the POS provider's OAuth consent screen. After granting permissions, you'll be sent back to SalesArck.
Permissions requested (Square):
MERCHANT_PROFILE_READ
PAYMENTS_READ
ORDERS_READ
PAYMENTS_WRITE (for future refund support)
After successful OAuth:
- Supabase session tokens are managed by the client SDK
- SalesArck registers a webhook subscription with Square for your merchant ID
- Connection status becomes Active in the portal
Step 4 — Configure Reward Rules
Navigate to Rewards → Rules and create your first rule. Example configuration:
| Field | Value | Meaning |
|---|---|---|
| Type | Points per dollar | Standard earn rule |
| Points per $1 | 10 | Consumer earns 10 pts per dollar spent |
| Minimum spend | $5.00 | No points on transactions < $5 |
| Active days | All days | Points every day |
| Multiplier | 1.0× | No bonus multiplier |
Most merchants start with a simple "10 points per dollar" rule and add promotional multipliers later.
Step 5 — Verify with a Test Transaction
Run a test payment through your Square terminal or use the Square sandbox. Within a few seconds, you should see a transaction appear in your SalesArck dashboard and verify that the consumer's wallet was credited.
Before going live, run a test in the Square sandbox environment. SalesArck supports both sandbox and production POS credentials — configure the environment in the portal settings.
Checklist
□ Phone number registered and Supabase OTP verified
□ Business tenant created (tenantId visible in settings)
□ Square (or Clover) connected — status shows Active
□ Webhook test received and processed (check Transaction Log)
□ At least one reward rule active
□ Test transaction processed — consumer wallet shows correct points
□ Team members invited (optional, Phase 2)
Common Issues
| Issue | Likely Cause | Resolution |
|---|---|---|
| OTP not received | Wrong phone number, carrier filtering, or Supabase delivery issue | Check number format; try resend |
| Square connection fails | OAuth scope not granted | Re-initiate OAuth, grant all requested permissions |
| No transactions showing | Webhook not reaching SalesArck | Check Square webhook dashboard for delivery failures |
| Wrong points amount | Rule configuration — check minAmount, multiplier | Edit rule and re-check |
| Consumer says balance is wrong | Consumer may have multiple wallets across tenants | Admin lookup by phone in admin console |