Payments Overview

What is a Payment?

A payment is a financial transaction where a customer pays an invoice for work that has been completed or services that have been rendered. Payments are HomeGuild's mechanism for collecting revenue, tracking cash flow, and managing accounts receivable.

Key Characteristics

• Invoice-Based: Every payment must be linked to a submitted invoice
• Multiple Payment Methods: Cash, check, and card payments supported
• Home Guild Payments: Integrated card processing (credit and debit)
• Search-Only Agent: Payment agent handles search for security; invoice agent handles payment recording
• Payment Tracking: Complete payment history with audit trail
• Automatic AR Updates: Invoice status and balance due update automatically

Payment Methods

HomeGuild supports two categories of payment methods:

Manual Payment Recording (Cash & Check)

Cash Payments:

• Recorded manually by provider after receiving cash
• Enter payment amount
• No additional fields required
• Provider responsible for depositing cash

Check Payments:

• Recorded manually by provider after receiving check
• Enter payment amount
• Enter check number for reference
• Provider responsible for depositing check

Recording Process:

1. Navigate to invoice view
2. Click "Record Payment" button
3. Select payment method (cash or check)
4. Enter amount and check number (if applicable)
5. Payment recorded instantly
6. Invoice status updates automatically

Card Payments (Credit & Debit)

Home Guild Payments:

• Integrated card processing solution
• White-labeled payment processor
• Processes credit and debit cards
• PCI-compliant and secure
• No other payment processors supported

Card Payment Flow:

1. Provider submits invoice to customer
2. Payment link generated automatically
3. Customer receives invoice with payment link
4. Customer clicks "Pay Now" (via link, app, or portal)
5. Customer redirected to payment processor site
6. Customer enters card information
7. Payment processed in real-time
8. Customer returned to app (if paying via app)
9. Payment confirmation and receipt option
10. Invoice automatically marked as paid

Payment Experience:

• Mobile app and web app: Same experience
• Payment link or in-app: Same processor flow
• Customer enters card details on secure processor site
• Customer can provide email for receipt
• Real-time payment success/failure notification

Financial Data Security

Important: HomeGuild does not store or handle any financial data (card numbers, CVV, bank accounts, etc.). All financial information is managed exclusively by the payment processor. HomeGuild only stores:

• Payment amount
• Payment date
• Payment method type (card, check, cash)
• Check number (for checks)
• Last 4 digits of card (for cards, from processor)
• Transaction reference/ID

Payment Lifecycle

1. Invoice Submission Requirement

Before Payment:

• Invoice must be created and submitted to customer
• Cannot record payment against draft invoice
• Cannot record payment before invoice exists

Payment Link Generation:

• Automatic when invoice submitted
• One payment link per invoice submission
• Withdrawing submission deletes link
• New link generated if invoice resubmitted

Payment Link Validity:

• Valid for up to one year
• Extends well past invoice due date
• Cannot be reused after payment
• Secure and unique per invoice

2. Payment Recording

Card Payments (Automatic):

• Customer initiates payment via link or app
• Processor handles transaction
• HomeGuild receives webhook notification
• Payment record created automatically
• Invoice status updated automatically

Cash/Check Payments (Manual):

• Provider receives payment from customer
• Provider manually records payment in app
• Enter amount and check number (if applicable)
• Payment record created instantly
• Invoice status updated automatically

Who Can Record Payments:

• Providers: Can manually record cash/check payments
• Invoice Agent: Can record payments via natural language
• Payment Agent: Cannot record payments (search-only for security)
• Customers: Trigger card payments through payment processor

3. Invoice Status Updates

Automatic Status Changes:

• Paid: Total payments equal or exceed invoice total
• Partially Paid: Some payments recorded but balance remains (future enhancement)
• Status updates happen instantly when payment recorded

Balance Due Calculation:

• Formula: Invoice Total - Sum of Payments
• Calculated automatically
• Displayed on invoice view
• Used for AR tracking

4. Payment Confirmation

Customer Notifications:

• Real-time success/failure message in payment flow
• Optional email receipt (customer provides email at checkout)
• Receipt includes payment details and invoice reference

Provider Notifications:

• Not currently implemented (coming soon)
• Future: Real-time notifications when payments received

Payment Information

Required Fields

• Invoice: Pointer to Invoice entity (required)
• Amount: Payment amount in cents (required)
• Date: Payment date (defaults to current date)
• Method: Payment method (cash, check, card)

Optional Fields

• Check Number: For check payments only
• Reference: Transaction reference/ID from processor
• Notes: Internal notes about payment (future enhancement)

Stored Information

From Processor (Card Payments):

• Last 4 digits of card
• Card brand (Visa, Mastercard, etc.)
• Transaction ID
• Authorization code
• Payment link ID

Manually Entered (Cash/Check):

• Check number
• Amount
• Date
• Method

Audit Trail

Tracked Information:

• Who recorded payment (user)
• When payment recorded (timestamp)
• Payment creation date
• Original values if modified (future enhancement)

Payment Status

Payments can have various statuses depending on their state:

Common Statuses:

• Completed: Payment successfully processed and recorded
• Pending: Payment initiated but not yet completed (rare)
• Failed: Card payment failed (customer may retry)
• Refunded: Payment has been refunded to customer
• Disputed: Payment is under dispute (chargeback)

Payment Operations

Recording Payments

Via Invoice Agent (Natural Language):

• Say: "Record a $500 payment for invoice #12345"
• Say: "Mark invoice for [customer] as paid"
• Say: "Customer paid $1000 by check"
• Agent records payment automatically

Via UI (Manual):

1. Open invoice view
2. Click "Record Payment"
3. Select payment method
4. Enter amount
5. Enter check number (if check)
6. Click "Save"
7. Payment recorded and invoice updated

Card Payments (Customer-Initiated):

• Customer clicks "Pay Now" link
• Redirected to payment processor
• Enters card information
• Payment processed automatically
• Returned to app with confirmation

Searching for Payments

Via Payment Agent (Natural Language):

• Say: "Find payments from last week"
• Say: "Show me cash payments"
• Say: "Search for payments over $1000"
• Say: "Find payments for [customer name]"
• Agent searches and returns results

Via UI (Payments View):

• Navigate to payments list
• Use filters and search
• Filter by customer, amount, date range, method
• Sort by date, amount, customer

Search Capabilities:

• By customer name
• By payment method
• By date range
• By amount range
• By invoice
• By status

Payment Refunds

Card Refunds:

• Processed through payment processor
• Can be initiated from app
• Refund processed back to customer's card
• Refund tracked as reverse payment
• Invoice balance due increases accordingly

Cash/Check Refunds:

• Handled however provider chooses
• Record refund in system
• Provider responsible for returning funds
• Refund tracked in payment history

Refund Process:

1. Identify payment to refund
2. Initiate refund (via app for cards)
3. Refund processed (cards) or tracked (cash/check)
4. Payment status updated to "refunded"
5. Invoice balance due updated
6. Customer notified (for card refunds)

Payment Modification

Editing Payments:

• Payments cannot be edited after creation
• Cannot change amount, date, or method
• Only option is refund and re-record

Why No Editing?:

• Financial integrity and audit trail
• Security and fraud prevention
• Accounting accuracy
• Compliance with financial regulations

Payment Deletion

Deletion Not Supported:

• Payments cannot be deleted
• Can only be refunded
• Maintains complete audit trail
• Ensures financial accuracy

Refund vs. Void:

• No "void" option exists
• Use refund to reverse payment
• Refund creates paper trail
• Original payment remains in history

Payment Agent (Search-Only)

Why Search-Only?

Security & Auditing:

• Payment recording requires human oversight
• Prevents accidental or fraudulent payments
• Maintains clear audit trail
• Reduces AI-related financial errors

Agent Capabilities:

• Can: Search for payments
• Can: Generate payment reports
• Can: View payment history
• Can: Send payment reminders (future)
• Can: Create payment links (future)
• Cannot: Record payments
• Cannot: Process payments
• Cannot: Modify payments
• Cannot: Refund payments

Payment Agent Commands

Search Commands:

• "Find payments from last month"
• "Show me all cash payments"
• "Search for payments over $5000"
• "Find payments for Smith Construction"
• "Show payments from this week"

Report Commands:

• "Give me a payment summary"
• "Show me payment totals by method"
• "What payments were received today?"
• "Generate a payment report for October"

Invoice Agent (Payment Recording)

Recording Commands:

• "Record a $500 payment for invoice #12345"
• "Mark invoice as paid"
• "Customer paid $1000 by check"
• "Record payment of $750 by cash"

Payment Management:

• Invoice agent handles payment recording
• Uses record_payment intent
• Validates invoice exists and is submitted
• Records payment and updates invoice
• Provides confirmation message

Common Workflows

Workflow 1: Card Payment (Customer-Initiated)

1. Pro submits invoice to customer
2. Payment link generated automatically
3. Customer receives invoice with "Pay Now" link
4. Customer clicks "Pay Now"
5. Redirected to payment processor site
6. Customer enters card details
7. Payment processed in real-time
8. Customer sees success message
9. Customer provides email for receipt (optional)
10. Customer returned to app (if paying via app)
11. Payment recorded automatically in HomeGuild
12. Invoice marked paid automatically
13. Customer receives receipt via email (if provided)

Workflow 2: Check Payment (Provider-Recorded)

1. Pro completes work and submits invoice
2. Customer receives invoice
3. Customer writes and mails check
4. Pro receives check in mail
5. Pro opens invoice in app
6. Pro clicks "Record Payment"
7. Pro selects "Check" as method
8. Pro enters amount and check number
9. Pro saves payment
10. Invoice marked paid automatically
11. Pro deposits check at bank

Workflow 3: Cash Payment (Provider-Recorded)

1. Pro completes work and submits invoice
2. Pro collects cash from customer on-site
3. Pro opens invoice in app
4. Pro clicks "Record Payment"
5. Pro selects "Cash" as method
6. Pro enters amount
7. Pro saves payment
8. Invoice marked paid automatically
9. Pro deposits cash at bank

Workflow 4: Payment Refund (Card)

1. Payment already recorded on invoice
2. Customer requests refund (e.g., unsatisfied)
3. Pro reviews refund request
4. Pro opens payment record
5. Pro clicks "Refund Payment"
6. Refund processed through payment processor
7. Funds returned to customer's card
8. Payment status updated to "refunded"
9. Invoice balance due increased accordingly
10. Customer receives refund notification

Workflow 5: Payment Search (Agent)

1. Pro wants to find specific payments
2. Pro opens payment agent or asks dashboard
3. Pro asks: "Find payments from last week"
4. Agent searches payment records
5. Agent returns results with payment list
6. Pro reviews payment details
7. Pro can tap payment to view full details

Workflow 6: Payment via Invoice Agent

1. Customer pays outside app (cash/check)
2. Pro wants to record payment quickly
3. Pro asks invoice agent: "Record $500 payment for Smith invoice"
4. Agent identifies invoice
5. Agent prompts for payment method
6. Pro responds: "Check, number 1234"
7. Agent records payment
8. Invoice updated automatically
9. Agent confirms: "Payment recorded successfully"

Integration Points

Invoices

Invoice-Payment Relationship:

• Each payment must link to one invoice
• One invoice can have multiple payments (future enhancement)
• Payment amount cannot exceed invoice balance due
• Invoice status updates based on payment total

Balance Due Calculation:

• Invoice Total - Sum of Payments = Balance Due
• Calculated automatically
• Displayed on invoice view
• Updates in real-time

Invoice Status Updates:

• Paid: Total payments >= invoice total
• Partially Paid: Payments received but balance remains (future)
• Status changes automatically when payment recorded

Accounts Receivable

AR Impact:

• Payments reduce AR immediately
• AR = Sum of unpaid invoice balances
• Payment recording reduces AR automatically
• AR aging reports reflect payment status

Cash Flow Tracking:

• Payments represent actual cash received
• Track payment timing vs. invoice due dates
• Identify fast-paying vs. slow-paying customers
• Forecast future cash flow based on payment patterns

Customers

Customer Payment History:

• All payments for customer viewable (future: a future update)
• Payment method preferences tracked
• Payment timing patterns visible
• Payment reliability assessment

Customer Portal:

• Customers can pay invoices via portal
• Customers see payment history
• Customers can download receipts (future: a future update)
• Customers can request receipt re-send

Jobs

Job-Payment Relationship:

• Payments linked to jobs via invoices
• Track job revenue and cash collection
• Job profitability includes payment timing
• Job completion may depend on payment

Reporting & Analytics

Payment Reports

Available Reports:

• Total payments by period (day, week, month, year)
• Payments by method (cash, check, card breakdown)
• Payments by customer
• Payment timing analysis (invoice submit to payment)
• Failed payment report (cards only)

Report Generation:

• Ask payment agent: "Show me payments this month"
• Ask payment agent: "What's my total revenue from payments?"
• Ask payment agent: "Give me a payment summary"
• Use filters in payments view

Payment Analytics

Key Metrics:

• Total payments received
• Average payment amount
• Payment method distribution
• Days to payment average
• Payment success rate (cards)
• Card payment failure rate

Trend Analysis:

• Payment volume over time
• Seasonal payment patterns
• Customer payment behavior trends
• Payment method preferences shifting

Home Guild Payments

Payment Processor

What is Home Guild Payments?:

• White-labeled payment processing solution
• Contracted wholesale processor
• PCI-compliant and secure
• Handles all card transactions
• Processor involvement not advertised to customers

Supported Cards:

• Credit cards (Visa, Mastercard, Amex, Discover)
• Debit cards (Visa, Mastercard)
• All major card brands supported

Processing Fees:

• Fees paid by provider (not passed to customer)
• Provider should budget for processing fees
• Competitive wholesale rates
• No monthly minimums or hidden fees

Security & Compliance

PCI Compliance:

• Payment processor handles all PCI compliance
• HomeGuild never sees or stores card data
• Customer enters card info on processor site
• Secure, encrypted transmission

Data Protection:

• No card numbers stored in HomeGuild
• Only last 4 digits retained (from processor)
• No CVV or expiration dates stored
• Transaction IDs tracked for reference

Payment Links

Link Generation:

• Automatic when invoice submitted
• Unique per invoice
• Secure and encrypted
• Valid for up to one year

Link Behavior:

• One-time use (cannot reuse after payment)
• Expires after one year
• Deleted if invoice submission withdrawn
• New link generated if invoice resubmitted

Future Enhancements

The following features are planned for future releases:

Partial Payments (a future update)

• Currently: One payment for full invoice amount (cards)
• Future: Multiple partial payments against one invoice
• Enables payment plans and installments

Payment Plans

• Currently: No payment plan support
• Future: Set up scheduled payment plans
• Example: 3 monthly installments
• Automatic payment reminders

Customer Payment History (a future update)

• Add payment history to customer view
• Show payment method preferences
• Display payment reliability metrics
• Track customer payment patterns

Provider Payment Notifications (a future update)

• Real-time notifications when payments received
• Email and push notifications
• Configurable notification preferences
• Payment summary digests

Payment Receipt Generation (a future update)

• Generate and download payment receipts
• Professional PDF format
• Provider branding customization
• Batch receipt generation

Payment Dispute Tracking (a future update)

• Track chargebacks and disputes in app
• Dispute notifications and alerts
• Evidence upload and management
• Resolution tracking

Accounting Integration (a future update)

• Export payments to QuickBooks, Xero
• Sync payment data automatically
• Bank reconciliation helpers
• Tax reporting support

Bank Reconciliation (a future update)

• Import bank statements
• Auto-match deposits to payments
• Identify discrepancies
• Reconciliation reports

Gratuity/Tips (a future update)

• Add tips during card payment
• Track tips separately from revenue
• Distribute tips among team
• Tip reporting

FAQs

Payment Basics

Q: How do I record a payment? A: For cash or check payments, open the invoice and click "Record Payment". Select the payment method, enter the amount (and check number if applicable), and save. For card payments, customers initiate payment through the payment link or app, and the payment is recorded automatically.

Q: Can customers pay with a credit card? A: Yes! HomeGuild supports credit and debit card payments through Home Guild Payments. Customers can pay via payment link, mobile app, or web app. All card processing is handled securely by our payment processor.

Q: Do I need to create an invoice before accepting payment? A: Yes, absolutely. Every payment must be linked to a submitted invoice. You cannot record a payment without first creating and submitting an invoice to the customer.

Q: What payment methods are supported? A: HomeGuild supports three payment methods:

1. Credit/debit cards (processed through Home Guild Payments)
2. Checks (recorded manually with check number)
3. Cash (recorded manually)

Q: Can I accept payments from other processors like Square or PayPal? A: No, only Home Guild Payments is supported for card processing. Cash and check payments can be recorded manually regardless of how you receive them.

Card Payments

Q: How do customers pay with a card? A: After you submit an invoice, customers receive a payment link. They click "Pay Now" and are redirected to the payment processor's secure site to enter their card information. After payment, they're returned to the app (if paying via app) with a confirmation message.

Q: Does HomeGuild store credit card information? A: No! HomeGuild does NOT store or handle any card information. All card data is managed exclusively by our payment processor. We only store the payment amount, date, method, and last 4 digits (provided by the processor).

Q: What happens if a card payment fails? A: The customer sees a failure message and can try again as many times as needed. Providers are not notified of failed attempts - the invoice simply remains unpaid. Customers can use the same payment link to retry.

Q: How long are payment links valid? A: Payment links are valid for up to one year, well past invoice due dates. However, they can only be used once. After a successful payment, the link cannot be reused.

Q: What if I withdraw an invoice submission? A: Withdrawing an invoice submission deletes the payment link. If you resubmit the invoice, a new payment link will be generated.

Recording Payments

Q: Can I record a payment before submitting the invoice? A: No, the invoice must be submitted to the customer before you can record a payment against it. Draft invoices cannot have payments recorded.

Q: Can I record future-dated payments? A: No, payments are recorded with the date they are received. You cannot record a payment with a future date (e.g., "customer will pay on Friday").

Q: Can I edit a payment after recording it? A: No, payments cannot be edited once recorded. This protects financial integrity and audit trails. If you made an error, you must refund the incorrect payment and record a new one.

Q: Can I delete a payment? A: No, payments cannot be deleted. You can only refund payments. This maintains a complete audit trail and ensures financial accuracy.

Q: What information is tracked with each payment? A: HomeGuild tracks: payment amount, date, method, check number (for checks), last 4 card digits (for cards), transaction ID, who recorded the payment, and when it was recorded.

Cash & Check Payments

Q: How do I record a check payment? A: Open the invoice, click "Record Payment", select "Check" as the method, enter the payment amount and check number, then save. The invoice will update automatically.

Q: What if I lose a check before depositing it? A: If you recorded the payment but lost the check, you'll need to contact the customer for a replacement check. The payment record in HomeGuild remains as-is since you intended to receive that payment.

Q: Do I need to upload a photo of the check? A: No, check photo upload is not currently supported. Just enter the check number for reference.

Q: How do I record a cash payment? A: Open the invoice, click "Record Payment", select "Cash" as the method, enter the payment amount, and save. No additional fields are required for cash.

Multiple Payments & Partial Payments

Q: Can a customer make multiple partial payments for one invoice? A: Not yet. Currently, invoices must be paid in full with one payment (for card payments). You can manually record multiple cash or check payments, but partial payment support is a future enhancement (Issue #183).

Q: What if the customer wants to split payment between a check and a card? A: This is not currently supported. To work around it, you could create two separate invoices for the customer - one for each payment method.

Q: Can a customer overpay an invoice? A: For card payments, customers cannot pay more than the invoice total - the payment processor only authorizes the exact amount. For cash or check overpayments, you would handle the refund manually and record it in the system.

Payment Status & Invoice Updates

Q: How does recording a payment update the invoice? A: When a payment is recorded (manually or automatically), the invoice status updates immediately. If the payment total equals or exceeds the invoice total, the status changes to "paid". The balance due is recalculated automatically.

Q: What is balance due and how is it calculated? A: Balance due = Invoice Total - Sum of Payments. This is calculated automatically and displayed on the invoice. When balance due reaches zero, the invoice is marked as paid.

Q: Can I see payment history on the invoice? A: Yes, the invoice view shows all payments recorded against that invoice, including amounts, dates, and methods.

Payment Search & Reporting

Q: How do I search for payments? A: You can search for payments two ways:

1. Ask the payment agent: "Find payments from last week" or "Show me cash payments"
2. Navigate to the payments view and use filters

Q: What can I search for? A: You can search by: customer name, payment method, date range, amount range, invoice reference, and status.

Q: Can I generate payment reports? A: Yes! Ask the payment agent: "Give me a payment summary" or "Show me payment totals by method". You can also filter the payments view and export data.

Q: How do I see a customer's payment history? A: Currently, you can view payment history in the payments view filtered by customer. Adding payment history to the customer view is planned (Issue #195).

Refunds & Disputes

Q: How do I refund a payment? A: For card payments, open the payment record and click "Refund Payment". The refund is processed through the payment processor and funds are returned to the customer's card. For cash/check refunds, record the refund in the system and return funds however you choose.

Q: What's the difference between void and refund? A: There is no "void" option - only refunds. A refund reverses the payment, creates a paper trail, and maintains the original payment in history for audit purposes.

Q: What happens if a customer disputes a card payment (chargeback)? A: Currently, disputes are handled through the payment processor's dashboard. HomeGuild will notify you of disputes, but enhanced dispute tracking within the app is planned (Issue #194).

Q: Can I reverse a payment? A: Only through refunds. You cannot simply delete or reverse a payment - you must issue a refund, which creates a proper audit trail.

Agents & Security

Q: Can the AI agent accept payments for me? A: No! For security and auditing reasons, agents cannot accept or process payments. The payment agent can only search for payments and generate reports. The invoice agent can record payments via natural language commands, but this still requires the provider to initiate and confirm the action.

Q: Why is the payment agent search-only? A: Payment recording requires human oversight to prevent accidental or fraudulent transactions, maintain clear audit trails, and reduce AI-related financial errors. Search functionality is safe, but payment processing needs human control.

Q: Can I ask the invoice agent to record a payment? A: Yes! You can say "Record a $500 payment for invoice #12345" and the invoice agent will record it. The agent validates the invoice, prompts for payment method if needed, and records the payment with your confirmation.

Q: What can the payment agent do? A: The payment agent can:

• Search for payments by customer, date, amount, method
• Generate payment reports and summaries
• View payment history
• Provide payment information and stats It cannot record, process, modify, or refund payments.

Notifications & Receipts

Q: Do I get notified when a customer pays? A: Not yet. Real-time provider notifications for payments are planned (Issue #199). Currently, you need to check the payments list or invoice status.

Q: Do customers get receipts? A: Yes, customers can provide an email address at checkout to receive a payment receipt. The receipt is sent automatically after successful payment.

Q: Can I send a receipt to a customer later? A: Enhanced receipt generation and re-sending is planned (Issue #200). This will allow you to generate and send receipts on demand.

Q: Can customers download receipts from their portal? A: This feature is planned (Issue #200). Customers will be able to download receipts for all their payments.

Integration & Export

Q: Can I export payment data to QuickBooks? A: Accounting software integration is planned (Issue #196). This will allow you to export or automatically sync payment data to QuickBooks, Xero, and other accounting platforms.

Q: How do I reconcile payments with my bank deposits? A: Bank reconciliation tools are planned (Issue #197). These will help you import bank statements and match deposits to HomeGuild payments automatically.

Q: Can I import payments from another system? A: No, payment import is not currently supported.

Processing Fees & Tips

Q: Who pays the card processing fees? A: Processing fees are paid by the provider (you), not the customer. You should budget for these fees as part of your business expenses.

Q: Can customers add tips when paying? A: Not yet. Gratuity/tip support is planned (Issue #198). This will allow customers to add tips during payment, with tips tracked separately from invoice amounts.

Q: What are the processing fees? A: Processing fees are competitive wholesale rates through our payment processor. Contact support for current fee schedules.

Related Features

• Invoices: Create and manage invoices for billing
• Customers: Manage customer information and relationships
• Jobs: Track work projects from lead to completion
• Estimates: Create project estimates with pricing
• Change Orders: Document scope and price changes
• Accounts Receivable: AR tracking and aging reports (future)

Related Issues

• a future update: Payments KB and streaming migration
• a future update: Partial quantity invoicing (enables partial payments)
• a future update: Enhanced payment dispute tracking
• a future update: Customer payment history on customer view
• a future update: Accounting software integration
• a future update: Bank reconciliation and deposit matching
• a future update: Gratuity/tip support
• a future update: Provider payment notifications
• a future update: Payment receipt generation and download

Additional Resources

• Payment Processing Best Practices (future)
• Cash Flow Management (future)
• Agent Command Reference