Stripe Setup

ServiceCortex uses Stripe Connect to process online payments for client invoices. Stripe Connect allows you to accept credit card payments directly into your own Stripe account while ServiceCortex handles the payment flow, invoice updates, and bookkeeping. There are two ways to connect: Express onboarding for new Stripe users, and OAuth linking for businesses with an existing Stripe account.

Express onboarding (recommended)

If you do not have an existing Stripe account, or prefer a streamlined setup, use Express onboarding:

1. Navigate to Settings > Integrations > Stripe.
2. Click Connect with Stripe.
3. You will be redirected to a Stripe-hosted onboarding form that is pre-filled with your company name, email, and country from your ServiceCortex account settings.
4. Complete the Stripe onboarding steps, including identity verification, bank account details, and business information.
5. When finished, you are redirected back to ServiceCortex.

Express accounts are fully managed by Stripe and require minimal ongoing maintenance. ServiceCortex creates the account on your behalf and handles all communication with the Stripe API.

Connecting an existing Stripe account

If you already have a Stripe account, you can link it using OAuth:

1. Navigate to Settings > Integrations > Stripe.
2. Click Connect Existing Account.
3. You will be redirected to Stripe to authorize ServiceCortex to access your account.
4. Review the permissions and click Authorize.
5. You are redirected back to ServiceCortex, and the connection is established.

Standard Connect accounts give you full access to the Stripe Dashboard for managing payouts, disputes, and account settings independently.

Checking your connection status

After connecting, the Stripe integration page shows your current status:

• Charges enabled -- your account can accept payments. This is required before clients can pay online.
• Payouts enabled -- funds can be transferred to your bank account.
• Requirements -- if Stripe needs additional information (for example, updated identity documents), the outstanding requirements are listed here. You must resolve them to keep payments active.
• Display name -- the business name shown on payment receipts.

If your Stripe account status shows issues, click Update Account to return to the Stripe onboarding form and provide the missing information.

Enabling online payments

Connecting Stripe alone does not enable online payments on your invoices. After connecting, you need to enable the feature:

1. Go to Settings > Payments.
2. Toggle Online payments to on.
3. Configure your processing fee settings (see below).

Once enabled, invoices sent to clients will include a Pay Now button in the client portal. Clients can click it to pay by credit card without leaving the portal.

Per-invoice control

Each invoice has an Allow online payment toggle. This lets you disable online payments for specific invoices (for example, if a client has agreed to pay by check for a particular job) while keeping the global setting enabled.

Processing fee configuration

In Settings > Payments, you can configure how processing fees are handled:

• Pass fee to customer -- when enabled, the Stripe processing fee is added to the client's payment amount. The invoice shows the original amount, and the fee is displayed separately during checkout.
• Fee percentage -- the percentage portion of the fee (for example, 2.9% for standard Stripe pricing).
• Fixed fee amount -- a flat amount added per transaction (for example, $0.30).
• Allow partial payments -- let clients pay less than the full invoice balance. When disabled, clients must pay the full amount in one transaction.
• Minimum payment amount -- set a floor for payment amounts to avoid processing very small charges.

Testing your setup

Before sending invoices to real clients, verify that everything works:

1. Create a test invoice for a small amount.
2. Open the invoice in the client portal using the portal link.
3. Click Pay Now and use a Stripe test card number (4242 4242 4242 4242 with any future expiration date and any CVC).
4. Confirm the payment completes successfully and the invoice status updates to Paid.
5. Check the payment record in Billing > Payments to verify the amount, method, and allocation.

If you are using Stripe's test mode, payments will not move real money. Switch to live mode in your Stripe Dashboard when you are ready to accept real payments.

Disconnecting Stripe

If you need to disconnect your Stripe account:

1. Go to Settings > Integrations > Stripe.
2. Click Disconnect.
3. For Standard Connect accounts, the OAuth authorization is revoked automatically.

Disconnecting disables online payments immediately. Existing payment records and history are preserved. You can reconnect at any time by starting the onboarding process again.

Troubleshooting

Payments are not working

• Verify that Charges enabled shows as active on the Stripe integration page.
• Check that Online payments is toggled on in Settings > Payments.
• Ensure the specific invoice has Allow online payment enabled.
• Review any outstanding Stripe requirements that may be blocking charges.

Client sees an error during payment

• The most common cause is an expired or declined card. Ask the client to try a different payment method.
• If the error mentions the connected account, check your Stripe Dashboard for account-level issues.
• Verify that the payment amount meets the minimum payment threshold if one is configured.

Refunds are failing

• Stripe refunds can fail if the original charge is too old (beyond Stripe's refund window) or if the connected account has insufficient balance.
• Check the Stripe Dashboard for detailed error information.

What to do next

• Record payments and manage your payment history.
• Create invoices and send them to clients with the Pay Now button.