Agicap Integration Proposal — Orcha as Central Hub

Date: 2026-04-01 For: Co-founder review Status: Research complete, ready for feedback Detailed research: 2026-04-01-agicap-integration-research.md

TL;DR

Orcha can fully integrate with Agicap for the payment use case. The partner uses Agicap only for payment execution — Orcha handles everything else: ingestion, booking, pre-accounting, DATEV export, and reconciliation. We confirmed the complete API surface by extracting all 5 OpenAPI specs from the Agicap developer portal.

The Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        ORCHA (Central Hub)                          │
│                                                                     │
│  1. Invoice arrives (email/scan/upload)                             │
│  2. Orcha extracts, validates, enriches with GL account + cost ctr  │
│  3. Approval workflow in Orcha                                      │
│  4. After approval, Orcha writes to:                                │
│     ├── 4a. DATEV (booking proposal via Maesn API) ── existing     │
│     └── 4b. Agicap (invoice for payment via Business Documents v2)  │
│  5. Partner pays in Agicap UI                                       │
│  6. Bank confirms payment (1-3 days later)                          │
│  7. Orcha polls Agicap Treasury Bank Journal API                    │
│  8. Orcha matches payment to invoice (via externalId)               │
│  9. Orcha updates internal status to "paid"                         │
│  10. DATEV reconciliation happens independently via bank feed       │
└─────────────────────────────────────────────────────────────────────┘

Step-by-Step Detail

Step 1-3: Invoice Ingestion & Approval (existing Orcha flow)

Invoice arrives → Orcha OCR/extraction → enrichment with GL account, cost center, tax code → approval workflow. This is what Orcha already does. No changes needed.

Step 4a: Write to DATEV (existing)

Orcha creates a Buchungsvorschlag (booking proposal) via the Maesn API, including:

• Invoice PDF
• GL account (Gegenkonto)
• Cost center (dimension1)
• BU-Schlüssel (tax code)
• Creditor account number

This creates an open item on the supplier account in DATEV.

Source: maesn.clj — existing implementation.

Step 4b: Write to Agicap (NEW)

Orcha pushes the invoice to Agicap via Business Documents v2 API:

POST /public/business-documents/v2/entities/{entityId}/connections/{connectionId}/supplier-invoices

[{
  "externalId": "orcha-document-uuid",        ← Orcha's ID (comes back in reconciliation!)
  "invoiceNumber": "INV-2024-001",
  "counterParty": {
    "id": "supplier-123",
    "name": "Lieferant GmbH"
  },
  "currency": "EUR",
  "amounts": {
    "totalAmount": 1190.00,
    "taxesAmount": 190.00,
    "dueAmount": 1190.00
  },
  "accounting": {
    "accountCode": "70100",                    ← Supplier (Kreditor) account
    "accountNumber": "4200",                   ← GL account (Aufwandskonto)
    "amount": 1190.00,
    "currency": "EUR"
  },
  "status": "due",
  "issueDate": "2024-01-15T00:00:00Z",
  "dueDate": "2024-02-15T00:00:00Z",
  "label": "Lieferant GmbH - INV-2024-001",
  "metadata": {
    "costCenter": "CC-MARKETING"               ← Dimension mapping TBD
  },
  "erpIdentificationFields": {
    "orchaDocumentId": "orcha-document-uuid",
    "datevCreditorNumber": "70100"
  }
}]

What this gives Agicap:

• The invoice appears as an expected transaction in Agicap Treasury (cash forecasting)
• The invoice is available in Agicap's payment workflow
• The partner can review, approve, and pay via Agicap UI

Optional: Upload the invoice PDF via POST .../{id}/attach-readable (Beta endpoint).

API source: Business Documents v2 OpenAPI spec — complete spec extracted.

Step 5: Partner Pays in Agicap

The partner logs into Agicap and:

1. Reviews the invoice (pushed by Orcha)
2. Approves payment in Agicap's approval workflow
3. Agicap generates a payment file and sends it to the bank via EBICS/SWIFT/H2H

Orcha is not involved in this step. This is entirely within Agicap's payment module.

Step 6: Bank Confirms Payment

The bank executes the payment and sends a bank statement back to:

• Agicap (via EBICS/PSD2) — Agicap auto-matches the bank line to the invoice
• DATEV (via bank feed / DATEV Bank Online) — independently

This takes 1-3 business days depending on payment type (SEPA instant vs. regular).

Step 7: Orcha Polls Agicap for Payment Confirmation (NEW)

Orcha polls the Treasury Bank Journal v1 API on a schedule (e.g. daily before 9am):

GET /public/treasury-bank-journal/v1/entities/{entityId}/exports?after={lastPollDate}&size=100

When new exports are available:

POST /public/treasury-bank-journal/v1/entities/{entityId}/exports/{newExportId}

This returns structured bank journal entries. Each entry contains:

{
  "paymentDate": "2024-02-14",                      ← Actual bank transaction date
  "name": "Lieferant GmbH Payment",
  "bankAccountName": "Geschäftskonto Deutsche Bank",
  "creditInOriginalCurrency": 1190.00,
  "originalCurrency": "EUR",
  "counterparts": [{
    "thirdPartyName": "Lieferant GmbH",              ← Supplier name
    "thirdPartyCode": "70100",                        ← Supplier code
    "accountingAccountNumber": "4200",                ← GL account
    "accountingAccountType": "SUPPLIER",
    "analyticalCodes": { "Project": "Marketing" },    ← Dimensions (cost centers)
    "document": {
      "externalId": "orcha-document-uuid",            ← ORCHA'S ID! Matching key.
      "documentReference": "INV-2024-001",            ← Invoice number
      "documentType": "SUPPLIER_INVOICE",
      "originalDueDate": "2024-02-15"
    },
    "debitInOriginalCurrency": 1190.00
  }]
}

The document.externalId is Orcha's own document UUID — this is what makes the matching trivial. No fuzzy matching needed.

API source: Treasury Bank Journal v1 OpenAPI spec — complete spec extracted with full examples.

Step 8-9: Orcha Reconciliation (NEW)

Orcha matches the bank journal entry to the original invoice via document.externalId:

1. Look up document.externalId → find the Orcha document
2. Verify amounts match (debitInOriginalCurrency = invoice total)
3. Record paymentDate as the confirmed payment date
4. Update Orcha document status to "paid"
5. Optionally store the full bank journal entry for audit trail

Then confirm to Agicap:

POST /public/treasury-bank-journal/v1/entities/{entityId}/exported-bank-journal-entries/mark-as-imported

{ "entriesImported": [{ "entryAgicapUniqueId": "f7f7ed5c-..." }] }

Or report errors:

POST .../mark-as-not-imported

{ "entriesNotImported": [{
    "entryAgicapUniqueId": "f7f7ed5c-...",
    "errors": [{ "errorType": "UNKNOWN_ACCOUNTING_ACCOUNT", "errorMessage": "..." }]
}]}

Step 10: DATEV Reconciliation (independent, no Orcha involvement)

DATEV receives the same bank statement independently via its own bank feed (DATEV Bank Online / FinTS). DATEV's built-in matching suggests which bank lines correspond to which open items. The Steuerberater reviews and accepts.

Neither Orcha nor Agicap push reconciliation results to DATEV. Both DATEV and Agicap reconcile independently from the same bank statement. This is the standard German accounting workflow — the bank is the single source of truth.

What Agicap Is and Isn't in This Architecture

Agicap IS:

• A payment execution platform — receives invoices from Orcha, partner approves and pays
• A bank statement aggregator — receives statements from banks, matches to invoices
• A cash forecasting tool — the "due" invoices Orcha pushes feed Agicap Treasury

Agicap is NOT:

• The system of record for invoices (Orcha is)
• The pre-accounting engine (Orcha does this)
• The DATEV integration point (Orcha handles this via Maesn)
• A real-time payment status API (no webhooks, must poll, 1-3 day delay)

Orcha IS:

• The central hub — invoice ingestion, extraction, approval, booking
• The pre-accounting engine — GL account, cost center, tax code assignment
• The DATEV integration — booking proposals via Maesn
• The reconciliation engine — matches Agicap payment data back to invoices
• The audit trail — complete lifecycle from ingestion to payment confirmation

Complete API Surface (confirmed via OpenAPI specs)

All specs were extracted from the Agicap developer portal. Full details in the consolidated research document.

APIs We Use

APIs We Might Use

APIs We Don't Use

What's Confirmed vs. What Needs Testing

Confirmed (100% — from official OpenAPI specs)

• Invoice write: all document types, full CRUD, batch operations
• Accounting fields: GL account (accountNumber), supplier account (accountCode), accounting currency
• Instalments: multiple payment schedules per invoice
• PDF upload: attach-readable endpoint (Beta)
• Payment data read: full bank journal entries with invoice references, supplier info, amounts, dates
• ExternalId round-trip: Orcha's document ID comes back in Treasury Bank Journal exports
• Error feedback: mark-as-imported / mark-as-not-imported with typed error categories
• Connection creation: via API, but requires Agicap back-office activation

Needs Testing (blocked on connection provisioning)

• Analytical dimensions: How to attach cost centers/projects to invoices via the API — likely via metadata or erpIdentificationFields, but the key names are unknown. Agicap calls these "dimensions" in the UI and exports them as analyticalCodes in the Treasury Bank Journal.
• Auto-reconciliation of API-pushed invoices: Does Agicap's matching engine match bank transactions to invoices pushed via the Business Documents API? The schema strongly suggests yes (externalId flows through), but needs live testing.
• Connection activation lead time: How long does Agicap support take to activate a new connection?

Open Questions for Agicap

1. How do we get a Business Documents connection provisioned?
2. How do we attach analytical dimensions to API-pushed invoices? Via metadata, erpIdentificationFields, or another mechanism?
3. Does auto-reconciliation work for API-pushed invoices?
4. Is there a sandbox/test environment?
5. What is the pricing for API access?
6. What bank connection type does the partner use — EBICS or PSD2?

Implementation Effort Estimate

New Components

Existing Components (no changes)

Card Expenses / Travel Expenses (Phase 2)

Agicap also offers physical and virtual Mastercard corporate cards with built-in expense management: receipt capture via mobile app, per-card spending limits, approval workflows, auto-categorization to cost centers and chart of accounts, and pre-accounting.

Product source: Agicap Ausgabenmanagement

Card Expenses Bank Journal v1 API

A separate API exists for exporting card expense journal entries:

GET /public/card-expenses-bank-journal/v1/entities/{entityId}/accounting-transactions
    ?LastSynchronizationDate=2024-01-01T00:00:00Z
    &PageSize=100&PageNumber=1

API source: Card Expenses Bank Journal v1 OpenAPI spec — complete spec extracted.

Each entry contains:

Key limitations vs. AP invoice flow

Critical workflow dependency

From the API docs:

"You need your accountant to prepare the journal entries and click on 'export to my accounting software' for them to be available from the API database."

Card expense entries are NOT automatically available. A manual step in Agicap is required before Orcha can pull them.

Possible card expense flow

1. Employee pays with Agicap Mastercard
2. Employee scans receipt in Agicap mobile app
3. Agicap matches card transaction to receipt, does pre-accounting
4. Accountant reviews in Agicap, prepares journal entries       ← MANUAL
5. Accountant clicks "export to my accounting software"         ← MANUAL
6. Orcha polls Card Expenses Bank Journal API
7. Orcha gets: payment date, merchant, GL accounts, amounts
8. Orcha creates DATEV booking proposal via Maesn

Assessment

The card expense integration is a nice-to-have DATEV bridge, not a core value driver like the AP invoice flow. The API is too thin (no receipts, no cost centers, no external IDs) and too manual (accountant must click export) for Orcha to add significant value beyond what Agicap already does natively with its own DATEV connector.

Recommendation: Focus on the AP invoice flow first (Phase 1 — high value, fully automatable, rich API). Card expenses can be Phase 2 if the partner specifically asks for a unified DATEV export through Orcha. A stronger card expense play would require Agicap to enrich their Card Expenses API with dimensions, receipt references, and automatic export — worth raising with Agicap as a feature request.

Previous Research (reference)