Overview

BlueClerk integrates with Square to accept payments directly on your invoices. Connect your Square account once, and customers can pay online through secure Square checkout links. Payments are recorded automatically when completed, keeping your books accurate without manual entry.

Setting Up Square

Connect Your Square Account

Go to Settings > Payments
Click "Connect Square" in the Square section
Sign in to Square (or create an account if you don't have one)
Authorize BlueClerk to access your Square account
Select your location where payments should be processed
You're connected - invoices will now show "Pay with Square" buttons

Required Environment

Your BlueClerk administrator must configure Square environment variables:

SQUARE_APPLICATION_ID - Your Square app ID
SQUARE_APPLICATION_SECRET - Your Square app secret
SQUARE_ENVIRONMENT - "production" or "sandbox"
SQUARE_WEBHOOK_SIGNATURE_KEY - For verifying payment webhooks

How Square Payments Work

For You (Contractor)

Create an invoice as usual
Send it to your customer via email
Customer clicks "Pay with Square" on the invoice
They're redirected to Square checkout to enter payment details
Payment completes through Square's secure system
BlueClerk receives a webhook from Square when payment completes
Payment is recorded automatically on the invoice
Invoice status updates to Paid if balance reaches zero

For Your Customer

Receives invoice email with Square payment option
Clicks "Pay with Square" button
Redirected to Square checkout page with invoice details prefilled
Enters card information securely through Square
Completes payment
Redirected back to invoice with success message

Payment Recording

Automatic Recording

When a Square payment completes:

BlueClerk receives a webhook from Square with payment details
Payment is verified using webhook signature
Payment amount is recorded on the invoice
Reference ID is stored as square_{payment_id} to prevent duplicates
Invoice balance updates automatically
Customer sees updated balance on the invoice page

Webhook Security

Square webhooks are verified using HMAC-SHA256 signatures to ensure payments are legitimate and haven't been tampered with.

Disconnecting Square

Remove Square Integration

Go to Settings > Payments
Click "Disconnect Square"
Confirm disconnection
Square data is cleared:
- Merchant ID removed
- Access tokens deleted
- Location ID cleared
- Square payments disabled

Existing invoices with Square payment links will no longer work after disconnecting.

Tips

Connect early - Set up Square before sending your first invoice
Test in sandbox - Use Square's sandbox environment to test before going live
Check payment status - Payments appear on invoices immediately after Square processes them
Accounting sync - Square payments sync to QuickBooks, Xero, or FreshBooks if you have accounting integrations enabled

Questions

Q: What payment methods does Square accept?
A: Square accepts all major credit and debit cards - Visa, Mastercard, American Express, and Discover.

Q: How long does it take for payments to appear?
A: Payments are recorded in BlueClerk immediately when Square processes them, usually within seconds of the customer completing checkout.

Q: Can I accept both Stripe and Square payments?
A: Yes, you can have both Stripe and Square connected. Customers will see both payment options on invoices.

Q: What are Square's fees?
A: Square charges transaction fees for each payment. Check your Square account for current rates - typically 2.9% + $0.30 per transaction for card payments.

Q: What if a payment fails or is refunded?
A: If a payment fails, it won't be recorded in BlueClerk. Refunds must be processed through your Square dashboard - BlueClerk will receive a webhook and can update the invoice accordingly.

Q: Can customers pay partial amounts?
A: The Square checkout link is generated for the full balance due on the invoice. Customers must pay the full amount in one transaction.

Accepting Square Payments