Merchant dashboard

The Xaalis Merchant Dashboard (/dashboard/*) allows merchants and their teams to monitor balances, track payments and payouts, manage subscriptions and invoices, configure webhooks, rotate API keys, and manage team members.

Authentication & Access

Access to the merchant dashboard is passwordless and invitation-only:

1. No Public Sign-Up: Dashboard users are provisioned by an operator (via POST /admin/merchants/{id}/dashboard-memberships) or invited by an existing account Owner.
2. Magic Links: Sign in by entering your email at /dashboard/login. You will receive a secure magic link (POST /dashboard/auth/sign-in/magic-link).
3. Session Cookie: Clicking the emailed link establishes a secure HttpOnly session cookie (credentials: "include"). No tokens or credentials are saved in client storage (localStorage or sessionStorage).

Roles & Permissions

Every team member has an assigned role on each merchant account:

Feature / Action	Owner	Developer	Viewer
View balances, transactions & invoices	✓	✓	✓
View webhook deliveries & payload logs	✓	✓	✓
Create test payments & simulate outcomes	✓	✓	—
Create new subscriptions & advance cycles (test)	✓	✓	—
Initiate real or test payouts	✓	—	—
Cancel subscriptions (immediate or period-end)	✓	—	—
Manage API keys (create, roll, revoke)	✓	—	—
Update live webhook URL	✓	—	—
Invite or remove team members	✓	—	—

Test Mode vs. Live Mode

The top navigation bar features a clear toggle between Mode Test and Mode En direct (Live):

• When in Test Mode, a distinctive 32px amber stripe is visible across the top of the interface. All displayed data, transactions, and balances belong strictly to the test: ledger.
• Actions executed in Test Mode (e.g. creating test payments, simulating approvals/failures, rolling test keys) will never touch real money or provider rails.
• You can switch seamlessly between modes at any time; your permissions remain identical across both modes.

Balance & Payouts (Solde & Virements)

Balance strip

The dashboard prominently displays two figures at the top:

• Disponible (Available): Funds settled and cleared into your merchant account, ready for immediate payout.
• Virements en cours (In transit): Funds reserved for payouts currently being processed by the provider connector.

Initiating a payout

1. Click Virer les fonds from the balance strip or the Payouts page.
2. Select your mobile provider (Wave or Orange Money).
3. Enter the recipient mobile number (validated in the Senegalese standard format: +2217XXXXXXXX).
4. Enter the amount in integer XOF (must be $\le$ Available balance minus the fee).
5. Review the payout summary and fee before confirming.
6. The request is dispatched with an automatic, unique Idempotency-Key header to prevent duplicate transfers.

Payments & Test Simulation

• Overview: Real-time table displaying transaction date, customer details, client reference, gross amount, and fee.
• Status Filters: Filter payments by succeeded, processing, requires_payment_method, failed, or expired.
• Detail Drawer: Click any payment row to open a full slide-over panel displaying the exact Xaalis payment ID, customer info, fee breakdown, net payout amount, and direct link to the customer’s hosted checkout.
• Simulation: In Test Mode, payments in processing or requires_payment_method can be simulated as succeeded or failed directly from the drawer to test your webhook integrations.

Subscriptions & Invoicing (Abonnements & Factures)

The Subscriptions section enables management of recurring customer billing:

• Creating Subscriptions: Configure recurring plans with intervals (weekly, monthly, quarterly, semi_annually, yearly), billing cycles, customer details, and payment grace periods (days_until_due).
• Invoices: Every cycle generates an invoice with a dedicated customer checkout URL (hosted_invoice_url). Invoices display clear statuses: draft, open, paid, overdue, or uncollectible.
• Cancellation:
  • At period end (at_period_end: true): The current billing period remains active and payable; no subsequent renewals will be scheduled.
  • Immediate (at_period_end: false): Immediately cancels the subscription. If a payment is currently processing with a provider, it settles cleanly while future recurring billing ceases.
• Testing Cycle Advances: In Test Mode, developers can trigger an immediate cycle advance to test recurring renewal notifications and invoice generation.

Developer Settings & Security

Located under /dashboard/developers, this section is tailored for engineering teams:

API Keys

• Lists all active and scheduled-for-revocation keys for the current mode.
• Only safe identifiers (key_...), display prefixes (sk_test_... or sk_live_...), and creation dates are shown.
• New Key Generation: Secret keys are displayed exactly once in a secure modal with a 1-click copy action. Secret keys are never persisted in the browser or accessible again via API.
• Rolling Keys: Zero-downtime rotation allows configuring a grace period between 1 and 72 hours (default 24h). The existing key remains valid until scheduled_revoke_at, giving you ample time to update production server configurations.
• Immediate Revocation: Allows revoking compromised keys immediately.

Webhook Endpoints & Delivery Logs

• Endpoint Configuration: Configure and test the HTTPS webhook URL receiving events (payment.succeeded, payout.failed, etc.).
• Delivery Log: Real-time log of the latest 50 webhook attempts, including HTTP status codes, execution duration, and full delivery attempt history.
• Payload Inspector: Click on any delivery to inspect the exact signed JSON payload delivered to your server.

Team Settings

Account Owners can navigate to /dashboard/settings to:

• Review the merchant’s legal business profile and fee terms.
• View all active team memberships.
• Send invitations to new team members with either Developer or Viewer roles.
• Remove team members when they leave the organization.