DATEV and Square integration

What moves between them

The main flow runs from Square into DATEV. As Square payments complete and refunds settle, ml-connector builds EXTF CSV booking batches and submits them to DATEV Rechnungswesen, with the Square processing fee posted as its own line so the net and the gross both reconcile, and each batch tagged with the cost center for the Square location that took the sale. Square invoice copies move the same direction, uploaded into DATEV Unternehmen Online as client-specific documents such as Rechnungsausgang. A periodic poll of the Square Payments and Refunds lists backfills anything a webhook missed and lets month-end totals be checked against the Square payouts. Nothing flows back from DATEV into Square: DATEV bookings are write-only and posted journal entries cannot be read, so Square is never updated from the ledger.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Square side it sends the Bearer token and the Square-Version header on every request, refreshing the thirty-day OAuth token before it expires rather than waiting for a 401, and accepts a Personal Access Token instead for a single-account setup. It verifies every inbound Square webhook by recomputing the HMAC-SHA256 signature over the notification URL plus the raw body with the per-subscription signature key, using a constant-time compare, and returns 403 on a bad signature so Square keeps retrying rather than marking the endpoint healthy. On the DATEV side it runs the OAuth Authorization Code flow with PKCE, keeps the state value at least twenty characters, and refreshes the 900-second token using the client ID only. Square payments and refunds are mapped into EXTF rows: amount, debit and credit accounts, document date, the Square payment reference, tax code, the fee as a separate posting, and the location resolved to a cost center. Because DATEV has no webhooks, each EXTF or DXSO submission returns a job ID that ml-connector polls with exponential backoff until the job completes or fails. DATEV detects duplicate EXTF files by filename plus document type, so ml-connector generates stable deterministic filenames to make a retry safe rather than a double-post, and sends a UUID idempotency_key on any Square write. Three real edge cases are handled: Square paginates with a cursor that expires after five minutes, so each backfill page is consumed promptly; DATEV document types are client-specific, so the document type list is fetched per client before any upload; and the standard GL account numbers cannot be read from DATEV, so the GL, tax-code, and location-to-cost-center mapping is configured up front. Every record carries a full audit trail and can be replayed if a call fails.

A real-world example

A mid-sized German hospitality group with about sixty staff runs three cafe locations on Square for both in-person card payments and online orders, while its tax advisor keeps the books in DATEV. Before the integration, a bookkeeper exported Square transactions each week and hand-entered the sales, the refunds, and the per-transaction Square fees into DATEV, and the fee lines in particular were easy to miss, which left the Square clearing account out of balance and the three locations lumped together at month-end. With DATEV and Square connected, every settled payment and refund posts into DATEV as an EXTF booking batch with the fee on its own line and the right location cost center, and a weekly poll of the Square payments list confirms the totals against the payouts. The Square clearing account reconciles on its own, each location reports separately, and the manual weekly export and re-keying step is gone.

What you can do

• •Post settled Square payments and refunds into DATEV as EXTF booking batches against the correct GL accounts and tax codes.
• •Book each Square processing fee as its own line and tag each batch with the cost center for the Square location.
• •Upload Square invoice copies into DATEV Unternehmen Online as client-specific documents fetched per client.
• •Bridge Square's OAuth Bearer token or Personal Access Token and DATEV's OAuth Authorization Code flow with PKCE.
• •Verify Square HMAC-SHA256 webhooks, confirm every async DATEV import job by polling, with deterministic filenames, retries, and a full audit trail.

Questions

Which direction does data move between DATEV and Square?

Data moves from Square into DATEV. Settled payments, refunds, and processing fees become EXTF booking batches and Square invoice copies become DATEV documents. Nothing is written back to Square, because DATEV bookings are write-only and posted journal entries cannot be read back through the API.

How does the integration handle DATEV having no webhooks while Square pushes events?

ml-connector listens for Square webhooks such as payment.updated, refund.updated, and invoice.payment_made and verifies their HMAC-SHA256 signatures with a constant-time compare, returning 403 on failure. DATEV cannot push anything, so each EXTF or DXSO submission returns a job ID that ml-connector polls with exponential backoff until it completes. A periodic poll of the Square payments and refunds lists catches any event that was missed.

How are Square payments mapped to DATEV GL accounts when DATEV will not return its chart of accounts?

DATEV does not expose its standard chart of accounts through the API, so the GL accounts, tax codes, and the location-to-cost-center mapping are configured up front. Each Square payment, refund, and fee is then written to the matching debit and credit account in the EXTF file, with the Square location resolved to its cost center. Document types for invoice uploads are client-specific and are fetched per DATEV client before any upload.