Payout Sync — Xero Fee Recording

Overview

When a processor payout settles (Square's "payout.sent" or Stripe's "payout.paid"), BlueClerk automatically creates a SPEND bank transaction in Xero for the total processing fees. This captures the fee side of your transactions so your bank balance in Xero matches your actual bank deposits. Invoice payments themselves are already recorded at gross via the standard payment sync.

How It Works

Automatic Fee Recording

When a payout settles:

1. BlueClerk creates a Payout record linking all included payments
2. For Xero integrations, a SPEND transaction is created automatically
3. The transaction amount equals the total processing fees for that payout
4. Posted to "Merchant Service Fees" expense account (auto-created if needed)
5. Transaction date matches payout arrival date

FreshBooks Limitation

FreshBooks integration currently skips payout sync because their expense API requires category ID lookups that aren't yet wired. If you use FreshBooks:

• Payouts are marked SKIPPED with an error message
• You'll need to manually record fees as expenses in FreshBooks
• The error message tells you the exact amount and date

What Gets Synced

Xero Bank Transaction Details

• Type: SPEND (money out)
• Bank account: Your primary bank account in Xero
• Expense account: "Merchant Service Fees" (code 404, auto-created)
• Amount: Total processing fees from the payout
• Date: Payout arrival date (or expected arrival if not yet arrived)
• Reference: Processor payout ID

Why This Matters

Without fee recording, your Xero bank balance would be higher than your actual bank balance by the amount of fees. This sync ensures:

• Bank reconciliation works - Xero balance matches real bank balance
• Accurate profit tracking - Fees are properly expensed
• Complete audit trail - Every payout has a corresponding fee transaction

Troubleshooting

Payout Marked SKIPPED

If a payout shows "SKIPPED" status:

• Check your integration - Only Xero supports automatic fee sync currently
• For FreshBooks users - Manually create an expense for the fee amount shown in the error message
• Contact support if you're using Xero and payouts are being skipped

Missing Merchant Service Fees Account

If the "Merchant Service Fees" account doesn't exist in Xero:

• BlueClerk creates it automatically on first payout sync
• Account code 404 is used by default
• Type: EXPENSE - properly categorized for reporting

Duplicate Fee Transactions

Payout sync is idempotent - safe to run multiple times:

• Each payout syncs once - tracked by xeroBankTxnId
• Re-running sync won't create duplicates
• Webhook retries are handled automatically

Questions

Q: Do I need to do anything to enable this? A: No - if you have Xero connected, fee recording happens automatically when payouts settle.

Q: What if I use FreshBooks? A: FreshBooks payout sync isn't available yet. You'll see SKIPPED payouts with instructions to manually record fees as expenses.

Q: Can I customize the expense account? A: Not currently - fees always post to "Merchant Service Fees" (code 404). Contact support if you need different account mapping.

Q: What about Square vs Stripe? A: Both work the same way - when the payout webhook fires (Square "payout.sent" or Stripe "payout.paid"), the fee transaction is created in Xero.

Q: How do I see which payouts have synced? A: Check the Payouts list under Finance - synced payouts show a Xero transaction ID and "SYNCED" status.