Overview
Stripe is the payment processor that powers card payments in Salon Assistant. Once connected, your salon can accept payments at checkout, receive real-time payment confirmations, handle failed transactions gracefully, and issue refunds. This guide walks you through connecting your Stripe account, enabling payment processing, and understanding how payments flow through the system.
Prerequisites
- Role required: Admin or Manager
- Before you start: You need a Stripe account. If you do not have one, Stripe will guide you through creating one during the connection process. Your salon must be fully set up in the system (see First Login & Setup).
Connect Your Stripe Account
Navigate to Settings in the left sidebar, then click the Payments tab. Click the Connect with Stripe button.
What you'll see: The system redirects you to Stripe's secure onboarding page. Stripe asks you to log in or create an account. You will enter your business details, bank account information, and verify your identity. This is a one-time setup.
After completing the Stripe onboarding, you are redirected back to Salon Assistant. A success message confirms your account is connected.
| Capability | Meaning |
|---|---|
| Charges Enabled | Your salon can accept card payments |
| Payouts Enabled | Stripe can deposit funds into your bank account |
Enable Payment Processing
Once connected, payments are enabled automatically. When a client checks out, the system uses your connected Stripe account to process the charge.
Go to Settings > Payments to verify your connection status. Confirm that both "Charges Enabled" and "Payouts Enabled" show as active.
What you'll see: The account status page displays your Stripe account ID, connection status, and the date of last sync. A "Disconnect" button is available if you ever need to remove the connection.
Understanding Payment Notifications
When a client completes a payment, the system updates automatically. You do not need to take any manual action.
| Event | What Happens in Salon Assistant |
|---|---|
| Client completes checkout | Payment status changes to Completed |
| Checkout session expires | Payment status changes to Cancelled |
| Payment is confirmed | Payment record is updated with a confirmation ID |
| Tip is included | Tip amount is recorded and marked as distributed |
What you'll see: On the Payments page, each transaction shows a color-coded status badge. Green means completed. Yellow means pending. Red means failed or cancelled.
Handling Failed Payments
Sometimes a payment does not go through. Common reasons include insufficient funds, an expired card, or a declined transaction.
What you'll see: The payment status changes to Failed. An error message describes why the payment did not succeed.
What to do:
- Navigate to Payments in the sidebar.
- Find the failed transaction (it will have a red "Failed" badge).
- Review the error reason shown in the payment details.
- Ask the client to try a different payment method.
- Create a new payment for the appointment.
| Failure Reason | What It Means |
|---|---|
| Card declined | The issuing bank rejected the charge |
| Insufficient funds | The card does not have enough balance |
| Expired card | The card's expiration date has passed |
| Incorrect details | The card number or CVV was entered wrong |
Managing Refunds
You can issue full or partial refunds for completed payments. Refunds are processed through Stripe and the status updates automatically.
- Navigate to Payments in the sidebar.
- Find the completed payment you want to refund.
- Click the payment to open its details.
- Click Refund and choose Full Refund or Partial Refund.
- For partial refunds, enter the amount to refund.
- Confirm the refund.
| Refund Type | Status Badge | Details |
|---|---|---|
| Full refund | "Refunded" (gray badge) | Entire amount returned to client |
| Partial refund | "Partially Refunded" (orange badge) | Refunded amount shown alongside original total |
Viewing Payment History
Track all your salon's payments from the Payments page. Use the filters to narrow results by date range, status, or client name. Click any payment to view its full details.
What you'll see: A list of all payments with columns for date, client name, amount, payment method, and status. Each payment links to its associated appointment. You can also view payment summaries on the Dashboard and in Reports > Revenue Report.
Tips & Best Practices
- Verify your Stripe account promptly. Complete any requested verification to avoid payment delays.
- Check your connection status weekly. Go to Settings > Payments to confirm both capabilities remain active.
- Process refunds within 90 days. Stripe allows refunds up to 90 days after the original charge.
- Keep your bank details current. Update payout details in your Stripe Dashboard if you change banks.
- Review failed payments daily. Address failures quickly so clients can rebook or retry.
- Use the Revenue Report for reconciliation. Compare Salon Assistant records with your Stripe Dashboard.
- Never share your Stripe credentials. Only Admins and Managers can access Stripe settings.
Common Issues
| Issue | Solution |
|---|---|
| "Charges Enabled" shows as inactive | Stripe needs additional verification. Check your email for instructions from Stripe and complete the required steps. |
| Payment stuck in "Pending" status | The payment confirmation has not arrived yet. Wait a few minutes. If it persists beyond 30 minutes, check your Stripe Dashboard. |
| Client says they were charged but status shows "Failed" | The charge may have been captured then reversed. Check your Stripe Dashboard for the transaction details. |
| Cannot find the "Connect with Stripe" button | You may not have Admin or Manager permissions. Ask your salon administrator to connect the account. |
| Refund button is not available | Refunds can only be issued on payments with "Completed" status. Verify the payment was fully processed first. |
| Stripe redirects to an error page during setup | Clear your browser cache and try again. Ensure pop-ups are not blocked, as Stripe uses redirects. |
| Payouts not appearing in your bank | Stripe typically takes 2–7 business days for the first payout. Subsequent payouts follow your configured schedule. |
| "Account disconnected" message appears | Your Stripe account was disconnected. Reconnect by clicking "Connect with Stripe" again in Settings. |
Related Journeys
- Processing a Payment — Take a payment during the checkout flow
- Creating and Sending an Invoice — Send an invoice for services rendered
- Running Reports and Exporting Data — View revenue reports and export financial data
- Configuring Salon Settings — Manage all salon configuration options
For Developers
Stripe Connect Integration
The OAuth flow uses these endpoints:
GET /api/stripe/connect— Generates the OAuth URL (Admin/Manager)GET /api/stripe/callback— Handles the OAuth redirect (public)GET /api/stripe/account— Returns account statusPOST /api/stripe/disconnect— Disconnects the account
Webhook Endpoint
Payment events are received at /api/webhooks/stripe. The route uses express.raw({ type: 'application/json' }) middleware because Stripe signature verification requires the raw request body as a Buffer.
Handled Event Types
| Stripe Event | Action |
|---|---|
checkout.session.completed | Marks payment as completed, records tip |
checkout.session.expired | Marks payment as cancelled |
payment_intent.succeeded | Confirms payment via PaymentIntent flow |
payment_intent.payment_failed | Marks payment as failed, stores error |
charge.refunded | Updates to refunded or partially_refunded |
account.updated | Syncs charges/payouts enabled flags |
account.application.deauthorized | Marks salon as disconnected |
invoice.payment_succeeded | Resets membership usage cycle |
customer.subscription.updated | Syncs membership period dates |
customer.subscription.deleted | Cancels membership subscription |
Response Format
The webhook returns { received: true, eventId } with status 200 immediately. Processing happens asynchronously via setImmediate. Verification failure returns 400 with code WEBHOOK_VERIFICATION_FAILED.