PERCH Bootstrap Canvas Draft: ledgering-help

canvas-draft-ledgering-help.md

AGENTS Canvas: #ledgering-help

This channel handles inbound support requests for Ledgering team services: Ledger, Books, Banklin, Payouts, PayBal (Payment Balances), FinancialAccount, Moneysweeper, Settler, Bankc, Adjustments, and related infrastructure.

PERCH Configuration

Review cadence: biweekly Proposals channel: #ledgering-team DRI: @minghua DRI GitHub: minghz Runbook path: squareup/ledgering-team-perch/runbook.md

Channel Scope

This channel is the primary inbound support surface for the Ledgering team. Requestors come from CS, Accounting, Compliance, adjacent engineering teams, and external partners. Common categories: seller transfer/deposit questions, balance adjustments, PR stamps/ACL requests, oncall escalations, and cross-team API questions. The team owns Ledger, Payouts, PayBal, FinancialAccount, Moneysweeper, Settler, Bankc, Banklin, and the Adjustments service.

Oncall

To reach the current oncall engineer, mention @oncall in the channel. The bot will respond with the primary oncall name and instructions for paging.

For emergencies: @oncall page <title> in this channel.

Common Questions (FAQ)

1. How do I credit/refund a seller's balance in bulk? Use the bulk adjustments tool at go/bulk-adjustments (also at https://regulator-fe.sqprod.co/bulk-adjustments). It accepts a CSV with unit token and amounts. The Adjustments service handles balance increases/decreases. For large batches (>1K sellers), coordinate with oncall before running. Funds typically reflect within ~15 minutes. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1778098867492279

2. Who owns [service] and where do I ask questions?

   • Ledger, Payouts, Payment Balances, FinancialAccount, Moneysweeper, Settler, Bankc, Banklin, Adjustments → this channel (#ledgering-help)
   • Settler is owned by ledgering-team@squareup.com (not the old ATM team — that no longer exists)
   • Reconciliation report (app.squareup.com/dashboard/sales/reports/reconciliation) → #sq-money-movement or the Sales Reporting team
   • ACH payment method delays (PAY_WITH_ACH hold periods) → Esperanto/Kiwi team (upstream of Ledger) Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1776040316264049

3. A seller's deposit/transfer isn't showing the right schedule or amount. How do I investigate? Use Regulator (regulator.sqprod.co) to check the seller's deposit schedule, transfer history, and ledger entries. Key sections: Bank Accounts, Transfers, Ledger Entries. The deposit schedule shown in Regulator comes from Ledger (source of truth). The seller Dashboard UI gets the deposit schedule from deposits service, which forwards to Ledger — if they differ, check whether the seller has multiple locations (impersonation may default to the wrong one). Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1775222064291119

4. What does a PENDING transaction mean? When does it settle? A PENDING transaction means the payment has been received but not yet swept/settled. Moneysweeper processes cleared transaction events and moves funds on the ledger. For automated savings (SFS), savings status must be consistent between sfs-core and MDS — if savings aren't depositing, check both. Sweeps happen per the seller's deposit schedule. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1774985179451149

5. How do refunds appear in a seller's transfer/payout? Refunds are back-dated to the time of the original capture. If the capture funds haven't been paid out yet, the refund reduces the upcoming transfer rather than appearing as a separate entry. This means refunds may not show as a distinct line item but are incorporated into the payout for the original payment period. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1774594223058469

6. Default settlement behavior for a new seller with a verified bank account? Once a bank account is verified, the seller receives nightly transfers by default for funds already processed. The marketing statement "no additional action needed" is accurate for the default case — however, sellers can also set up manual transfers or use Square Card, which are separate. Risk review adds ~2 minutes of delay, not days. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1775491112097659

7. How do I browse Kafka topics to see what messages exist? Use KPow — Block's standard Kafka topic browser. For sandbox: go/kpowstaging. For production: go/kpow. Select the appropriate cluster. Kafka infrastructure is owned by the Platform Eventing team in BlockPlat; their support channel is #blockplat-help. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1774456664170019

8. I need a stamp/approval on a PR or ACL/dependency request. What's the process? Post the PR or Registry link directly in this channel and mention @oncall. For ACL/dependency requests: post the Registry link (registry.sqprod.co/app_dependency_requests/XXXXX). For Terraform LSC PRs: the oncall engineer can merge and apply. Stamps are a routine request — no need to preface with lengthy context, just link and tag oncall. Source: multiple threads

9. What's the right channel for [cross-team question]?

   • Kafka/streaming infrastructure → #blockplat-help
   • Reconciliation report discrepancies → Sales Reporting team / #sq-money-movement
   • PAY_WITH_ACH hold timing → Esperanto/Kiwi team
   • Square Banking UI questions → #banking-help or Square Banking team
   • Financial reporting (Mode reports, compliance) → Accounting team directly
   • PagerDuty routing changes → post in this channel, oncall can assist

10. How do I determine what unit token is associated with a payout or transfer? Use Regulator: search by merchant token to find transfers, then look at the transfer details for the associated unit token. For money transfers, use getMerchantDepositTags on the Ledger RPC to get deposit tag info. If you have the transfer token, look it up via Regulator's transfers section. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1777497866254329

Resources

Operational Tools

• Regulator — Primary ops tool for investigating seller accounts, transfers, ledger entries, PB accounts. Referenced in nearly every investigation thread.
• go/bulk-adjustments — Self-serve CSV-based bulk balance adjustments tool. Use for crediting/refunding multiple sellers.
• RQM (Request Query Machine) — Look up individual payment records by payment token.
• KPow (staging) / KPow (prod) — Kafka topic browser.

Documentation

• Ledger FAQ — Frequently asked questions about Ledger service behavior. Referenced for refund/transfer questions.
• Settlement overview doc — High-level explanation of how settlement works for Square sellers.
• Settler overview doc — Training notes on Settler service usage (referenced by Erin Stanfill in thread).
• go/bulk-adjustments — (also listed above under tools)

Team Resources

• App Registry — Ledgering services — Owner info, ACL, dependency requests for all Ledgering services.
• Backfila — Job management for backfill operations (referenced for SPOOL and savings backfills).

Known Issues and Fixes

Symptom: Someone asks about bulk-adjustments and mentions a URL like go/adjustments, go/ledger-credits, or asks the team to "process the refund for us via a spreadsheet." Response: The correct tool is go/bulk-adjustments (also at https://regulator-fe.sqprod.co/bulk-adjustments). It is self-serve — requestors can run it themselves after getting access. It accepts a CSV with unit token and amount columns. For access, request via Registry. For large batches, coordinate with oncall first. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1778098867492279 | Confidence: high

Symptom: Someone asks about Settler ownership and mentions the "ATM team" or an old banking/treasury channel. Response: The ATM team no longer exists. Settler is owned by the Ledgering team — contact via ledgering-team@squareup.com or #ledgering-help. Do not reference the old ATM team or its Slack channels. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1776040316264049 | Confidence: high

Symptom: Someone asks about the Reconciliation report (app.squareup.com/dashboard/sales/reports/reconciliation) showing different amounts than Regulator. Response: The Reconciliation report is owned by the Sales Reporting team, not Ledgering. Discrepancies between the Reconciliation report and Regulator transfers should be routed to the Sales Reporting team / #sq-money-movement. Ledgering can confirm transfer amounts in Regulator but cannot explain Reconciliation report logic. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1775244896934439 | Confidence: high

Symptom: Someone asks why an ACH payment (PAY_WITH_ACH) takes 3 days to appear in Ledger / deposit to merchant. Response: Ledger does not add any days-long delay for ACH payments specifically — it processes balance change events from Esperanto (Kiwi) as soon as they arrive, same as card payments. If there's a 3-day delay, it is upstream of Ledger, in Esperanto/Kiwi (the payment method layer). Route to the Kiwi/Esperanto team (see registry.sqprod.co/applications/kiwi). Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1776717268615629 | Confidence: high

Symptom: Someone asks about how refunds appear in a seller's payout/transfer, expecting a separate line item. Response: Refunds are back-dated to the original capture time. If the capture hasn't been paid out yet, the refund is netted against the upcoming payout rather than appearing as a separate debit. The key missing piece that BuilderBot often omits: we back-date refunds to the time of capture so that if we haven't sent the money for the capture yet, we don't want to send it at all. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1774594223058469 | Confidence: high

Symptom: Someone says the Ledger getMerchantDepositTags RPC or getMoneyTransfer RPC gives them a result, but when they try it nothing is there / it doesn't exist. Response: There is no getMoneyTransfer RPC on the Ledger service — do not suggest it. For deposit tags, use getMerchantDepositTags. For transfer details, use Regulator or the listBankSettlementEntries RPC. When uncertain about which RPCs exist, check the Ledger proto definition rather than guessing. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1776793526170619 | Confidence: high

Symptom: Someone asks which Kafka tool to use to browse topics in sandbox. Response: Use KPow at go/kpowstaging (sandbox) or go/kpow (production). The Kafka infrastructure is owned by the Platform Eventing team in BlockPlat. Their support channel is #blockplat-help. Note: #kafka-users is for general Kafka questions but Platform Eventing / BlockPlat owns the infrastructure. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1774456664170019 | Confidence: high

Symptom: A seller's deposit schedule looks different in Regulator vs. the Square Dashboard UI. Response: First check if the seller has multiple locations — impersonation in Dashboard may default to a different location than the one linked in Regulator. Regulator gets deposit schedule from Ledger (source of truth). The Dashboard UI for deposit settings is still Ember (not React). If there's a genuine mismatch between the active deposit schedule in Ledger and what the UI shows, it may be a bug in the deposits service or Dashboard JS layer. Source: https://sq-block.slack.com/archives/C0AL684AAA2/p1775222064291119 | Confidence: high

Routing Rules

• ACH payment hold timing / PAY_WITH_ACH delay questions → redirect to Esperanto/Kiwi team (registry.sqprod.co/applications/kiwi or registry.sqprod.co/applications/esperanto). Ledger does not add ACH-specific delays.
• Reconciliation report discrepancies → redirect to Sales Reporting team / #sq-money-movement. Ledgering can confirm transfer amounts in Regulator but doesn't own the Reconciliation report.
• Square Banking UI / seller-facing dashboard questions → redirect to Square Banking or Dashboard team. Ledgering owns backend data; UI is owned elsewhere.
• Kafka infrastructure / topic browser access → redirect to #blockplat-help (Platform Eventing team).
• PagerDuty schedule or routing changes → oncall can assist directly; post in thread.
• GDPR deletion requests → these sometimes get misrouted here; redirect to the Privacy/Legal team or the appropriate GDPR workflow.

Escalation Paths

• Production incident or data correctness issue → mention @oncall page <title> in channel to page the current oncall engineer immediately.
• Large balance adjustment (>1K sellers, high dollar value) → coordinate with oncall before running go/bulk-adjustments; post in channel for a team member to co-pilot.
• Strategic seller issue (named account, escalating) → tag oncall and include the merchant token and Regulator link. The oncall engineer can grant impersonation for investigation.
• Cross-team ownership ambiguity → if a request has bounced through multiple channels, tag oncall with full context. The team will either own it or definitively redirect with the correct owner.

Baseline Metrics (from bootstrap analysis)

Date range: 2026-03-12 to 2026-05-14 | Threads analyzed: 125 (exhaustive) Resolved: 34% | Assisted: 14% | Failed: 10% | Silent: 22% | Inconclusive: 17% | Not Support: 3% BB Involvement: 18% | Direct BB Resolution Rate: ~5% | Failure Rate among BB responses: ~55%

Key observations:

• BB involvement is low (18%) — most threads are resolved by human team members directly without BB participation.
• When BB does engage, it is corrected or supplemented by humans more often than not (~55% failure/assisted rate among BB responses).
• The channel handles a wide mix: ~35% are ops/investigation requests (seller issues), ~25% are stamps/ACL/PR reviews, ~20% are cross-team technical questions, ~15% are oncall escalations/FYIs, ~5% are announcements/non-support.
• Silent rate (22%) is significant — many threads receive no BB response. These are primarily stamp requests, oncall FYIs, and cross-team questions that humans handle directly.