Payments & Stripe

The Billing module supports both manual payment recording and automated payment processing through Stripe Connect. This page covers setting up Stripe, accepting payments, managing payment methods, processing refunds, and the autopay experience.

Payment Overview

Payments in concorbit are recorded against invoices. Each payment tracks:

A single invoice can have multiple payments (partial payments). The invoice is marked as Paid when the total of all payments meets or exceeds the invoice total.

The PaymentLedger as the source of truth

Every settlement (manual mark-paid, Stripe pay-now, autopay finalise, refund, credit-note application, QuickBooks payment sync) flows through PaymentLedgerService (app/Services/Billing/PaymentLedgerService.php). That makes the payments table the single ledger for invoice money movement; invoices.amount_paid is always a materialised sum of the ledger, never a shortcut value.

Concretely:

• A positive settlement writes a payment row with status='succeeded' (or 'completed' from QuickBooks) and a positive amount.

• A refund writes a signed negative row with status='refunded'. Refunds are recorded per-refund-id, not as a cumulative delta, so out-of-order webhook delivery is safe.

• A void writes nothing to the ledger; the existing row's status flips to voided and is excluded from the settled total.

The settled total counts succeeded, completed, and refunded rows (signed). voided, pending, and failed are excluded. Idempotency is two-layered:

1. existingByReference finds a prior row by (payment_source, external_reference) and returns it untouched.

2. A DB partial unique index catches a race where two callers insert at once; the savepoint catches the 23505 and re-reads the winner.

Recording a payment against an AT-governed or QB-governed invoice is refused at the service. AT and QB own the paid state for their rows; a concorbit-side payment would immediately desync on the next sync pull.

Payment sources

payments.payment_source is the canonical vocabulary for who recorded the settlement:

The payment_source value is rendered as a chip on the staff invoice page and the portal invoice page so finance can see at a glance how an invoice was settled. The reconciliation view (/reconciliation) filters by source.

Stripe Connect Setup

Stripe Connect allows your workspace to accept online payments from contacts. concorbit uses Stripe Connect so that payments flow directly to your Stripe account.

Prerequisites

• A Stripe account (create one at stripe.com if you do not have one).

• Workspace admin permissions (settings.tenant).

Connecting Stripe

1. Navigate to Settings > Payments.

2. Click Connect Stripe Account.

3. You are redirected to Stripe's authorisation page.

4. Log in to your Stripe account (or create one).

5. Authorise concorbit to connect to your account.

6. You are redirected back to concorbit. A confirmation message appears.

Once connected, your workspace can:

• Accept online payments on invoices.

• Store payment methods for contacts.

• Process autopay charges for subscriptions.

• Issue refunds.

Refreshing the Connection

If your Stripe connection needs to be refreshed (e.g. after Stripe account changes):

1. Navigate to Settings > Payments.

2. Click Refresh Stripe Connection.

3. Complete the Stripe authorisation flow.

Disconnecting Stripe

To remove the Stripe integration:

1. Navigate to Settings > Payments.

2. Click Disconnect Stripe.

3. Confirm the disconnection.

After disconnecting:

• Online payment links on invoices will no longer work.

• Autopay will stop for all subscriptions.

• Existing payment records are retained.

• You can reconnect at any time.

Accepting Payments

Online Payments via Portal

When Stripe is connected and a contact receives an invoice:

1. The contact receives an invoice email with a link to the client portal.

2. In the portal, the contact sees the invoice details and a Pay Now button.

3. Clicking Pay Now initiates a Stripe payment.

4. The contact enters their payment details (card number, etc.) in a secure Stripe-hosted payment form.

5. On successful payment, the invoice is automatically marked as Paid.

6. The payment is recorded against the invoice with the Stripe payment ID.

Stripe Checkout

For some payment flows, concorbit uses Stripe's embedded checkout experience. The contact completes payment without leaving concorbit, the Stripe PaymentElement is rendered directly in the portal.

Manual Payment Recording

For payments received outside Stripe:

1. Open the invoice.

2. Click Record Payment.

3. Enter:

   • Amount received.

   • Method (bank transfer, cheque, cash, other).

   • Reference (optional).

   • Notes (optional).

   • Date paid.

4. Click Save.

The payment is recorded and the invoice's outstanding balance is reduced. If the total paid meets or exceeds the invoice total, the invoice status changes to Paid.

Payment Methods Per Contact

concorbit stores payment methods (credit/debit cards) at the contact level through Stripe.

Adding a Payment Method

1. Navigate to the contact's record in the CRM.

2. Open the Payment Methods section.

3. Click Add Payment Method.

4. A Stripe setup form appears.

5. The contact (or you on their behalf) enters their card details.

6. The payment method is securely stored in Stripe and linked to the contact.

concorbit does not store raw card numbers. All card data is held securely by Stripe. concorbit only stores a reference to the Stripe payment method.

Setting a Default Payment Method

Each contact can have multiple payment methods on file. One is marked as the default:

1. Open the contact's payment methods.

2. Click Set as Default on the desired payment method.

The default payment method is used for autopay charges.

Removing a Payment Method

1. Open the contact's payment methods.

2. Click Remove on the payment method.

3. Confirm the removal.

The payment method is removed from Stripe. If it was the default, autopay will not work until a new default is set.

Autopay

Autopay automatically charges a contact's default payment method when a subscription invoice is generated.

Enabling Autopay

Autopay is toggled per contact, not per subscription:

1. Navigate to the contact's record.

2. Open the Payment Methods section.

3. Toggle Autopay on.

The contact must have at least one payment method on file with a default set.

How Autopay Works

1. A subscription's billing date arrives.

2. concorbit generates an invoice for the subscription.

3. Because the contact has autopay enabled, concorbit initiates a Stripe charge for the invoice total against the contact's default payment method.

4. If successful: The payment is recorded, the invoice is marked as Paid, and the contact receives an "Autopay successful" email notification.

5. If failed: The invoice remains unpaid, the payment failure is recorded on the subscription, and the contact receives an "Autopay failed" email notification with instructions to update their payment method.

Autopay Email Notifications

Two system email templates handle autopay notifications:

• Autopay successful: Sent when a charge succeeds. Confirms the amount and invoice.

• Autopay failed: Sent when a charge fails. Includes a link to the portal to update the payment method.

Both templates can be customised from the Email module's system templates section.

Portal Autopay Management

Contacts can manage their own autopay settings through the client portal:

• View stored payment methods.

• Add or remove payment methods.

• Set a default payment method.

• Enable or disable autopay.

This self-service capability reduces the administrative burden on your team.

Refunds

Stripe Refunds

For invoices paid through Stripe:

1. Open the paid invoice.

2. Click Refund.

3. Enter the refund amount (full or partial).

4. Confirm the refund.

5. concorbit initiates a refund through Stripe.

6. The invoice status changes to Refunded.

Stripe processes the refund to the original payment method. Refund processing time depends on the card issuer (typically 5-10 business days).

Manual Refunds

For payments received outside Stripe, refunds must be processed manually through your bank or payment processor. Record the refund in concorbit by:

1. Creating a Credit Note for the refund amount.

2. Noting the refund details in the credit note.

Payment History

Per-Invoice Payment History

Each invoice shows all payments recorded against it, including:

• Payment amount and date.

• Payment method.

• Reference number.

• Stripe payment ID (for online payments).

Per-Contact Payment History

View all payments made by a specific contact through their invoices. On the canvas, the Invoice List panel filters by contact when one is selected, showing all their invoices and payment statuses.

Webhook Configuration

Stripe communicates payment events (successful charges, failed charges, refunds) to concorbit via webhooks. These are configured automatically when you connect Stripe. If you need to troubleshoot payment notifications:

1. Check your Stripe dashboard for webhook delivery status.

2. Verify that the webhook endpoint is active and receiving events.

3. Review the payment and invoice records in concorbit to confirm events were processed.

Security

• PCI compliance: concorbit never stores raw card numbers. All payment data is handled by Stripe's PCI-compliant infrastructure.

• Stripe Connect: Payments flow directly to your Stripe account. concorbit acts as a platform facilitating the connection, not as an intermediary holding funds.

• Encrypted data: Sensitive payment-related fields (like cancellation reasons) are encrypted at rest in concorbit's database.

Troubleshooting

Payment Not Appearing on Invoice

• Check the Stripe dashboard for the payment status.

• Verify that the webhook is active and events are being delivered.

• Confirm that the payment was made against the correct invoice.

Autopay Not Charging

• Verify that the contact has autopay enabled.

• Confirm that a default payment method is set.

• Check the Stripe dashboard for any issues with the payment method (expired card, insufficient funds).

• Review the subscription's payment failure count and last failure date.

Stripe Connection Issues

• Ensure your Stripe account is in good standing.

• Try refreshing the Stripe connection from Settings > Payments.

• If the connection is broken, disconnect and reconnect Stripe.