Payment Processing

Payment Processing Guide

Doc status: Stripe (Live); PayPal (Partial); Dwolla (Connect-only). PCI SAQ A-EP is a target and pending formal assessment. See Reality Index: reality.md.

Guide to accepting payments in the Notarial system and syncing with your preferred accounting software.

Platform Philosophy

The Notarial platform focuses on core notary business functions - client management, document handling, and appointment scheduling. For comprehensive accounting, bookkeeping, and financial reporting, we integrate with leading accounting SaaS platforms rather than rebuilding these capabilities.

Payment Overview
Payment Methods
Payment Recording
Accounting Integrations
Payment Gateway Setup
Refunds and Adjustments
Data Sync to Accounting

Payment Overview

What are Payments?

Payments are monetary transactions from clients for notary services. The system handles:

Payment acceptance and recording
Basic payment tracking
Invoice generation
Data export for accounting systems

Payment Workflow

Service Provided → Invoice Created → Payment Accepted → Data Exported to Accounting System

Our Focus vs Accounting Software

Our Platform: Payment acceptance, invoicing, basic tracking
Accounting Software: Comprehensive bookkeeping, financial reports, tax preparation

Payment Methods

Accepted Payment Types

Cash Payments

In-Person: Collect at appointment
Receipt Required: Issue receipt immediately
Security: Secure cash handling procedures
Deposit: Daily bank deposits recommended

Check Payments

Business Checks: Preferred for B2B
Personal Checks: Accept with verification
Certified Checks: For large amounts
Hold Period: Bank hold for clearance

Credit Card Payments

In-Person: Card terminal or swiper
Online: Payment gateway integration
Phone: Virtual terminal
Recurring: Automatic monthly charges

ACH Transfers

Direct Deposit: Bank-to-bank
E-Check: Electronic check processing
Wire Transfers: For large amounts
Batch Processing: Multiple payments

Other Methods

PayPal: Online payment processor
Venmo/Cash App: Mobile payment apps
Zelle: Bank-to-bank instant transfer
Cryptocurrency: If accepted

Payment Method Configuration

Go to Settings → Payment Methods
Enable/disable methods:
- Check the methods you accept
- Set fees for each method
- Configure processing rules
Add merchant accounts:
- Credit card processors
- ACH provider details
- PayPal integration
Set default methods for clients

Recording Payments

Understanding Payments and Orders

Important: Payments are received for ORDERS, not invoices. An invoice is simply a billing document that groups orders together.

Order ──────┐
            │
            ├────> Payment  (money is for orders)
            │
            └────> Invoice  (invoice is a document)

Key Rules:

One payment can cover multiple orders from the same company
Orders can be paid without being invoiced
The payment amount is allocated to specific orders
The system tracks these relationships through the payment_orders junction table

Manual Payment Entry

Navigate to Payments → Record Payment
Select order(s) to apply payment to
Enter payment details:
- Payment date
- Payment amount
- Payment method
- Reference number
- Notes
Verify payment allocation:
- Specify amount for each order
- Handle partial payments
- Handle overpayments
Save payment record

From Order

Navigate to Orders → View Order
Click "Record Payment"
Payment auto-populates:
- Order amount due
- Client information
- Service dates
Enter payment details
Apply to order
Send receipt to client

Batch Payment Recording

Select multiple unpaid orders
Click "Record Payment"
Enter total amount
Set allocation rules:
- Proportional distribution across orders
- Oldest orders first
- Manual allocation per order
Record batch payment

Partial Payments

One order can receive multiple partial payments
The system tracks paid vs. outstanding amounts
Each payment can be split across multiple orders
Outstanding orders appear in the payments dashboard

Payment Fields

Required Fields

Payment Date: When payment was made
Payment Amount: Amount received
Payment Method: How payment was made
Order(s): Which orders to apply payment to

Optional Fields

Reference Number: Check number, transaction ID
Client PO: Purchase order number
Notes: Payment details or issues
Receipt Number: For receipt tracking

Data Sync to Accounting

Automatic Sync Features

Real-Time Updates: Payments sync instantly to accounting software
Invoice Matching: Automatic invoice-payment reconciliation
Category Mapping: Custom category assignments
Tax Handling: Automatic tax calculation support
Multi-Entity: Support for multiple business entities

Sync Frequency Options

Immediate: Real-time data transfer
Hourly: Regular batch updates
Daily: End-of-day consolidation
Manual: On-demand synchronization
Scheduled: Custom timing preferences

Data Mapping

Income Categories: Map to correct income accounts
Expense Tracking: Categorize payment processing fees
Client Accounts: Link to customer records
Project Tracking: Associate with specific jobs
Tax Codes: Automatic tax categorization

Export Options

For accounting platforms without direct integration:

CSV Export: Universal format compatibility
Excel Templates: Pre-formatted spreadsheets
PDF Reports: Printable payment summaries
API Access: Custom integration development
Scheduled Reports: Automated email delivery

Payment Gateway Setup

Integrated Payment Gateways

The platform integrates with leading payment gateways for secure online payment processing. Current status: Stripe (Live), PayPal (Partial), Dwolla (Connect-only). Availability may be controlled by feature flags.

Stripe

Overview: Stripe is a leading payment processor known for its developer-friendly API and excellent fraud protection.

Key Features:

Accept all major credit cards (Visa, Mastercard, Amex, Discover)
Built-in fraud prevention with Radar
Support for Apple Pay and Google Pay
Recurring billing support
Real-time payment status via webhooks
Automatic retry for failed payments

Setup Steps:

Create Stripe Account
- Go to stripe.com and sign up
- Complete your business profile
- Verify your email and business information
Get API Keys
- Navigate to Developers → API keys
- Copy your Publishable key (for frontend)
- Copy your Secret key (for backend)
- Note: Use Test keys for setup, switch to Live for production
Configure in Platform
- Go to Settings → Payment Gateways
- Select "Stripe" from the gateway dropdown
- Enter your API keys
- Enable webhook endpoint (auto-configured)
- Save configuration
Configure Webhooks
- Stripe webhooks notify your platform of payment events
- Platform URL: https://yourdomain.com/api/payments/webhooks/stripe
- Required events: payment_intent.succeeded, payment_intent.failed
- Webhook signing secret automatically configured

Idempotency:

All Stripe payments include idempotency keys
Prevents duplicate charges from network retries
Automatic retry on transient failures

PayPal (Partial)

Overview: PayPal is a widely trusted payment platform with millions of active users worldwide.

Key Features:

Accept PayPal account payments
Accept credit/debit cards through PayPal
Buyer protection for eligible purchases
Support for PayPal Credit (Buy Now, Pay Later)
Mobile-optimized checkout
International payment support

Setup Steps (when enabled):

Create PayPal Developer Account
- Go to developer.paypal.com
- Log in with your PayPal business account
- Access the Dashboard
Create REST API App
- Navigate to Your Credentials → Create App
- Name your app (e.g., "Notary Platform")
- Select sandbox for testing, live for production
- Copy Client ID and Client Secret
Configure in Platform
- Go to Settings → Payment Gateways
- Select "PayPal" from the gateway dropdown
- Enter Client ID and Client Secret
- Set mode (Sandbox/Live)
- Save configuration
Configure Webhooks
- Platform URL: https://yourdomain.com/api/payments/webhooks/paypal
- Required events: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED

Sending Payment Links

Send secure payment links to clients for online payment collection.

From Invoice (Stripe; PayPal when enabled)

Open any unpaid invoice
Click "Send Payment Link"
Select payment gateway (Stripe; PayPal when enabled)
Confirm email recipient
Client receives email with secure payment URL

From Order (Stripe; PayPal when enabled)

Open any order
Click "Send Payment Link"
Invoice is automatically created (if needed)
Payment link is generated and sent

From OnTheGo (Stripe)

Open any order in OnTheGo mobile view
Tap "Send Payment Link"
Link is sent to client's email or phone

Payment Flow

Client Receives Link
- Email with secure payment URL
- Link includes invoice amount and details
- Link expires after 7 days
Client Pays Online
- Client clicks link in email
- Redirected to secure payment page (Stripe/PayPal)
- Completes payment with card or PayPal account
- Redirected back to platform confirmation page
Automatic Recording
- Webhook notifies platform of payment
- Invoice automatically marked as paid
- Payment recorded in system
- Receipt emailed to client

Payment Link Security

Unique Links: Each link is unique to the invoice
Expiration: Links expire after 7 days
One-Time Use: Links can only be used once
Amount Locked: Payment amount is fixed
HTTPS Only: All transactions encrypted
Webhook Verification: All webhooks are verified

Testing Payments

Stripe Test Mode

Use Stripe Test API keys during setup
Use Stripe test card numbers:
- Success: 4242 4242 4242 4242
- Failure: 4000 0000 0000 0002
- Requires CVC: Any 3 digits
- Expiration: Any future date

PayPal Sandbox

Use PayPal Sandbox credentials
Create test buyer accounts in PayPal Dashboard
Test with sandbox payment flow

Switching to Live Mode

Before Going Live:

Replace test API keys with live keys
Verify webhook endpoints point to production URL
Test with a small real payment
Check email notifications are working

Refunds and Adjustments

Refunding Payments

Locate original payment
Click "Process Refund"
Enter refund details:
- Refund amount
- Refund reason
- Refund method
Choose processing:
- Original payment method
- Store credit
- Cash/check refund
Process refund
Send confirmation

Partial Refunds

Partial Amount: Refund portion of payment
Line Item: Refund specific services
Prorated: Calculate based on usage
Fee Adjustment: Modify service fees

Credits and Adjustments

Credit Memos: Client account credits
Write-Offs: Uncollectible amounts
Adjustments: Invoice corrections
Transfers: Move between invoices

Accounting Integrations

Why Integration Matters

Rather than building complex accounting features, we integrate with best-in-class accounting platforms. This approach provides:

Specialized Expertise: Accounting software specializes in financial management
Continuous Updates: Regular updates for tax laws and regulations
Professional Support: Dedicated accounting support teams
Advanced Features: Comprehensive financial reporting and analysis

Supported Accounting Platforms

QuickBooks Online

Data Sync: Automatic invoice and payment sync
Mapping: Custom field mapping
Real-Time: Near real-time updates
Multi-Currency: Support for international transactions
Tax Support: Automatic tax calculations

Xero

Bank Feeds: Direct bank integration
Multi-Currency: Global currency support
Payroll Integration: Employee payroll sync
Inventory: Product/service tracking
Reporting: Advanced financial reports

FreshBooks

Time Tracking: Project-based billing
Expense Tracking: Automatic expense categorization
Client Portal: Client payment portal
Mobile App: On-the-go accounting
Project Management: Project profitability

Wave Accounting

Free Platform: No monthly fees
Invoicing: Professional invoices
Receipt Scanning: Mobile receipt capture
Payroll: Optional payroll service
Bank Connections: Direct bank sync

Data Export Features

CSV Export: Universal data format
Excel Reports: Detailed spreadsheets
API Access: Custom integrations
Scheduled Exports: Automated data transfers
Historical Data: Complete payment history

Basic Payment Tracking

While detailed accounting is handled by integration partners, we provide:

Payment records and status
Invoice generation
Client payment history
Simple payment reports

Payment Security

PCI Compliance

Data Encryption: All card data encrypted
Secure Storage: Limited data storage
Access Control: Restricted access
Regular Audits: Security verification

Fraud Prevention

Address Verification: AVS checks
CVV Validation: Security code checks
Velocity Limits: Transaction limits
IP Tracking: Geographic validation

Best Practices

Secure Handling: Protect payment information
Regular Reconciliation: Daily payment matching
Secure Storage: Lock cash and checks
Background Checks: Verify payment processors

Automation Features

Payment Reminders

Due Date Alerts: Before due date
Overdue Notices: After due date
Escalation: Management alerts
Custom Messages: Personalized reminders

Auto-Charge

Recurring Payments: Regular billing
Stored Cards: Client card storage
Failed Payment: Retry logic
Success Notification: Payment confirmations

Daily Reconciliation

Bank Feeds: Import bank data
Auto-Matching: Match payments
Exception Handling: Manual review needed
Reports: Daily reconciliation

Mobile Payment Features

Mobile Payments

On-Site: Collect at appointments
Card Readers: Mobile card terminals
QR Codes: Quick payment options
Text-to-Pay: SMS payment links

Field Operations

Offline Mode: Record without internet
Sync Later: Update when connected
Receipts: Email or text receipts
Photos: Check images

Integration with Other Modules

Invoices Module

Auto-Application: Apply to invoices
Status Updates: Mark as paid
Partial Payments: Multiple payments
Overpayments: Create credits

Companies Module

Payment History: Client payment record
Credit Limits: Track available credit
Preferred Methods: Client payment preferences
Billing Cycles: Regular payment schedule

Banking Module

Deposits: Record bank deposits
Reconciliation: Match bank statements
Cash Management: Track cash flow
Fees: Processing fee tracking

Best Practices