[Payments]: Bank Transaction Integration via GoCardless & Invoice Matching

[xniti3x]

🔧 Feature Request: Bank Transaction Integration via GoCardless & Invoice Matching

Summary:
As a user, I want to connect my bank account using the GoCardless Bank Account Data API or any other provider and view my transactions in InvoicePlane. I want to manually or automatically match those transactions to invoices using smart matching criteria.

💡 Key Features

Bank Integration via GoCardless
Use GoCardless Bank Account Data API or any provider to connect user bank accounts securely.

Fetch and store:
Transaction date
Description/reference
Amount (credit/debit)
Transaction ID
2. Csv import

📊 Transaction Views
Index View (/transactions):

Paginated, sortable, and filterable list of all fetched bank transactions.

Columns:
Date
Description
Amount
Matched Invoice (if any)
Matching Score (if applicable)
Status (Matched / Unmatched / Suggested Match)
Filter options:
Date range
Match status
Amount range
Search by description

UI Concept (Table View):
Date Description Amount Invoice # Match Score Status
2025-09-01 Payment from John $250.00 INV-1023 95% Matched
2025-08-29 ACH Debit PayPal -$15.99 — 42% Unmatched

Edit View (/transactions/edit/{id}):
View/edit transaction details.
Show suggested invoices based on a matching score:

Criteria:
Amount match
Invoice number in transaction reference
Close dates (e.g., ±5 days)

Manual override: User can select a different invoice to match or unlink an existing one.

UI Concept (Matching Panel):
Transaction: 2025-09-01 | Amount: $250.00 | Desc: Payment from John

Suggested Invoices:
✔ INV-1023 | $250.00 | Due: 2025-09-01 | Score: 95%
INV-1019 | $245.00 | Due: 2025-08-30 | Score: 72%
INV-1021 | $250.00 | Due: 2025-09-10 | Score: 68%

[Link to Selected Invoice] [Unlink] [Save]

⚙️ Automation Logic (Optional Feature)

A cron job or background task can periodically:

Fetch new transactions from GoCardless.
Attempt auto-matching using criteria (amount, date proximity, reference number).

🔗 Linking Invoices to Transactions
Once matched, the invoice detail page shows:
Linked transaction details

A “Reconciled” badge or status

Ability to unlink and reassign if necessary.

✅ Benefits

Seamless reconciliation workflow.
Reduces manual tracking of payments.
Enhances accuracy of accounting.

[nielsdrost7]

As a user, I want to connect my bank account using the GoCardless Bank Account Data API or any other provider and view my transactions in InvoicePlane. I want to manually or automatically match those transactions to invoices using smart matching criteria.

---

Bank Integration & Import (Api)

The GoCardless integration should use the Bank Account Data API as documented at: https://developer.gocardless.com/getting-started/introduction/

---

Transaction Views

Index View (/transactions)

• This view will display a paginated, sortable, and filterable list of all bank transactions.
• Columns:
  • Date
  • Description
  • Amount
  • Matched Invoice (if any)
  • Matching Score (if applicable)
  • Status (Matched / Unmatched / Suggested Match)
• Filter options: Date range, match status, amount range, and search by description.

Table View Example:

Date	Description	Amount	Invoice #	Match Score	Status
2025-09-01	Payment from John	$250.00	INV-1023	95%	Matched
2025-08-29	ACH Debit PayPal	-$15.99	—	42%	Unmatched

Edit View (/transactions/edit/{id})

• This view allows a user to view or edit transaction details.
• Suggested invoices will be displayed based on a matching score, using these criteria:
  • Amount match
  • Invoice number in transaction reference
  • Close dates (e.g., ±5 days)
• A manual override will allow the user to select a different invoice to match or unlink an existing one.

Matching Panel Example:

Transaction Details

• Date: 2025-09-01
• Amount: $250.00
• Description: Payment from John

---

Suggested Invoices

Invoice	Amount	Due Date	Score	Actions
✓ INV-1023	$250.00	2025-09-01	95%	[Unlink] [Save]
INV-1019	$245.00	2025-08-30	72%	[Link] [Save]
INV-1021	$250.00	2025-09-10	68%	[Link] [Save]

---

Automation Logic (Optional Feature)

• A cron job or background task will periodically:
  • Fetch new transactions from GoCardless.
  • Attempt to auto-match them using the defined criteria (amount, date proximity, and reference number).

---

Linking to Invoices

• Once a transaction is matched, the corresponding invoice's detail page will show:
  • Linked transaction details.
  • A "Reconciled" badge or status.
  • An option to unlink and reassign the transaction if needed.

[drewangell]

Just a quick note - the PayPal integration I'm working on is going to basically do all of this, but with your PayPal data. You could connect your GoCardless bank account to PayPal, and hook InvoicePlane up to PayPal, and everything should be pretty clear for you.

Check the issues list for all the stuff we're planning. :)

[nielsdrost7]

Planning Note — v2 Implementation

Story
As a company bookkeeper, I want to connect my bank account via GoCardless and see imported transactions matched against open invoices so that I can reconcile payments without manually cross-referencing bank statements.

v2 Context
This feature lives in Modules/Payments/. It introduces a new BankTransaction model alongside the existing Payment model. Transactions are fetched from GoCardless Bank Account Data API (formerly Nordigen) and stored per-company thanks to the BelongsToCompany trait. A matching engine compares amount, date proximity (±5 days), and reference text against open Invoice records. The company-panel Filament resource exposes the transaction list and a side-panel for manual match confirmation.

A CSV import path is also required as a fallback for banks not covered by GoCardless, sharing the same BankTransaction table and matching logic.

Acceptance Criteria

• Company settings page allows connecting a GoCardless requisition (institution selection + OAuth redirect flow)
• Scheduled job (or manual trigger) fetches new transactions and upserts BankTransaction records, avoiding duplicates by external transaction ID
• Matching engine assigns a score per invoice based on: exact amount (40 pts), invoice number in reference text (30 pts), date proximity ≤5 days (30 pts)
• Transaction list view shows Date, Description, Amount, Matched Invoice, Score, Status columns with filters on date range, match status, and amount range
• Edit/detail view shows ranked candidate invoices; user can confirm, override, or unlink a match
• Confirming a match creates a Payment record linked to the invoice and marks the invoice as paid
• CSV import accepts standard bank export format (date, description, amount) and runs through the same matching pipeline
• Linked transaction details and "Reconciled" badge appear on the Invoice detail view
• All company-scoped — transactions from one company are never visible to another

Implementation

• Module: Modules/Payments/
• New model: Modules/Payments/Models/BankTransaction.php — columns: id, company_id, external_id, transaction_date, description, amount, currency, status (enum: unmatched/suggested/matched), invoice_id (nullable FK), match_score (nullable tinyint), raw_data (JSON), source (enum: gocardless/csv)
• New migration: Modules/Payments/Database/Migrations/
• New service: Modules/Payments/Services/GoCardlessService.php — wraps the GoCardless API; methods: getRequisitionUrl(), exchangeToken(), fetchTransactions(string $accountId, Carbon $from)
• New service: Modules/Payments/Services/TransactionMatchingService.php — scoreInvoice(BankTransaction, Invoice): int, findCandidates(BankTransaction): Collection, confirmMatch(BankTransaction, Invoice): Payment
• New job: Modules/Payments/Jobs/FetchBankTransactionsJob.php — dispatchable, queued
• New Filament resource: Modules/Payments/Filament/Company/Resources/BankTransactionResource/ with ListBankTransactions, EditBankTransaction pages
• New Filament page: Modules/Payments/Filament/Company/Pages/GoCardlessSettings.php
• Modify: Modules/Invoices/Filament/Company/Resources/Invoices/ — add "Reconciled" badge and linked transaction infolist section
• Config key: services.gocardless (client_id, client_secret, redirect_uri) stored in config/services.php

Test Scenarios (PHPUnit)

// Modules/Payments/Tests/Unit/TransactionMatchingServiceTest.php
class TransactionMatchingServiceTest extends AbstractTestCase
{
    #[Test]
    public function it_scores_exact_amount_and_invoice_number_reference_highest(): void
    {
        $invoice = Invoice::factory()->make(['invoice_number' => 'INV-1023', 'total' => 250.00]);
        $transaction = BankTransaction::factory()->make([
            'amount' => 250.00,
            'description' => 'Payment INV-1023',
            'transaction_date' => $invoice->due_date,
        ]);

        $score = app(TransactionMatchingService::class)->scoreInvoice($transaction, $invoice);

        $this->assertGreaterThanOrEqual(90, $score);
    }

    #[Test]
    public function it_returns_zero_score_for_mismatched_amount_and_no_reference(): void
    {
        $invoice = Invoice::factory()->make(['invoice_number' => 'INV-9999', 'total' => 500.00]);
        $transaction = BankTransaction::factory()->make([
            'amount' => 12.50,
            'description' => 'Random payment',
            'transaction_date' => now()->subMonths(3),
        ]);

        $score = app(TransactionMatchingService::class)->scoreInvoice($transaction, $invoice);

        $this->assertLessThan(20, $score);
    }
}

// Modules/Payments/Tests/Feature/BankTransactionResourceTest.php
class BankTransactionResourceTest extends AbstractCompanyPanelTestCase
{
    #[Test]
    public function it_lists_bank_transactions_for_current_company_only(): void
    {
        BankTransaction::factory()->count(3)->for($this->company)->create();
        $otherCompany = Company::factory()->create();
        BankTransaction::factory()->for($otherCompany)->create();

        $this->testLivewire(ListBankTransactions::class)
            ->assertSuccessful()
            ->assertCountTableRecords(3);
    }

    #[Test]
    public function it_confirms_a_match_and_creates_a_payment(): void
    {
        $invoice = Invoice::factory()->for($this->company)->create(['total' => 250.00, 'status' => 'sent']);
        $transaction = BankTransaction::factory()->for($this->company)->create([
            'amount' => 250.00,
            'status' => 'unmatched',
        ]);

        $this->testLivewire(EditBankTransaction::class, ['record' => $transaction->id])
            ->callAction('confirmMatch', ['invoice_id' => $invoice->id])
            ->assertHasNoErrors();

        $this->assertDatabaseHas('payments', ['invoice_id' => $invoice->id]);
        $this->assertDatabaseHas('bank_transactions', ['id' => $transaction->id, 'status' => 'matched']);
    }
}

---

Generated by Claude Code

[nielsdrost7]

---

Test Suggestions

Added to support future implementation of this request. The issue body is unchanged.

Today there is no bank-transaction feature anywhere in the codebase: no BankTransaction model, no GoCardless (or any Open Banking) client, no transaction-matching UI, and no CSV import path for transactions. Modules\Payments\Models\Payment is a manually-entered record tied 1:1 to an invoice_id via PaymentForm; there's no concept of an unmatched, provider-fetched transaction awaiting reconciliation. This request substantially overlaps with #101 (same feature, GetMyInvoices/enablebanking instead of GoCardless) — worth consolidating the two before implementation starts, since parallel provider integrations aren't realistic for one effort. If built, coverage should include:

• PHPUnit: it_stores_fetched_bank_transactions_scoped_to_the_company()

#[Test]
public function it_stores_fetched_bank_transactions_scoped_to_the_company(): void
{
    /* Arrange */
    /* Act */
    $transaction = BankTransaction::factory()->for($this->company)->create(['amount' => 250.00, 'description' => 'Payment from John']);

    /* Assert */
    $this->assertDatabaseHas('bank_transactions', ['company_id' => $this->company->id, 'amount' => 250.00]);
}

• PHPUnit: it_computes_a_match_score_between_a_transaction_and_a_candidate_invoice()

#[Test]
public function it_computes_a_match_score_between_a_transaction_and_a_candidate_invoice(): void
{
    /* Arrange */
    $invoice     = Invoice::factory()->for($this->company)->create(['invoice_total' => 250.00]);
    $transaction = BankTransaction::factory()->for($this->company)->create(['amount' => 250.00]);

    /* Act */
    $score = app(TransactionMatchingService::class)->score($transaction, $invoice);

    /* Assert */
    $this->assertGreaterThan(0.8, $score);
}

• PHPUnit: it_links_a_transaction_to_an_invoice_and_marks_it_reconciled()

#[Test]
public function it_links_a_transaction_to_an_invoice_and_marks_it_reconciled(): void
{
    /* Arrange */
    $invoice     = Invoice::factory()->for($this->company)->create();
    $transaction = BankTransaction::factory()->for($this->company)->create();

    /* Act */
    app(TransactionMatchingService::class)->link($transaction, $invoice);

    /* Assert */
    $this->assertSame('matched', $transaction->fresh()->status);
}

• PHPUnit: it_does_not_expose_another_companys_transactions_in_the_index()

#[Test]
public function it_does_not_expose_another_companys_transactions_in_the_index(): void
{
    /* Arrange */
    $other = BankTransaction::factory()->for(Company::factory()->create())->create();

    /* Act */
    $component = Livewire::actingAs($this->user)->test(ListBankTransactions::class, ['tenant' => Str::lower($this->company->search_code)]);

    /* Assert */
    $component->assertCanNotSeeTableRecords([$other]);
}

Edge cases worth covering: two open invoices with the identical amount (ambiguous match, should surface both as suggestions rather than auto-picking one), a transaction description containing no recognizable invoice number, and re-running auto-matching after a transaction has already been manually linked (must not silently overwrite a manual link).

[john-frandsen]

Great write-up — the matching-engine design (amount / invoice-number-in-reference / date-proximity scoring, a company-scoped BankTransaction table, and a CSV fallback) is solid and sensibly provider-agnostic. That's the right call, because the provider choice is the riskiest part here, not the reconciliation logic.

One concrete warning worth surfacing before implementation starts: GoCardless Bank Account Data (the former Nordigen API) closed to new sign-ups in mid-2025. Existing requisitions still work, but a brand-new self-hosted InvoicePlane user can no longer obtain GoCardless BAD credentials today. Building the whole GoCardlessService + requisition/OAuth flow on top of a provider new users can't actually onboard to would be a painful discovery at the end. Worth confirming on their developer portal before the v2 module commits to it.

On consolidating with #101 (enablebanking / GetMyInvoices): the EU PSD2 provider landscape splits into two models, and it's worth picking one deliberately:

• Bring-your-own-eIDAS-cert providers require you to hold PSD2 certificates (QWAC + QSeal). Those cost low-thousands of euros, take weeks to issue, and renew periodically — a real barrier for self-hosted invoicing users who just want to reconcile payments.
• Cert-free / regulated-AISP model: the provider is the registered Account Information Service Provider and holds the eIDAS certs themselves; your app just talks to a normal REST + OAuth API. GoCardless BAD was exactly this pattern — which is why it dominated the hobby/indie space.

For InvoicePlane's audience (small businesses and self-hosters), the cert-free AISP pattern is the only one that keeps onboarding friction-free. Your GoCardlessService interface (getRequisitionUrl() / fetchTransactions()) maps cleanly onto any cert-free EU PSD2 aggregator without the cert-provisioning overhead.

Practical suggestion: lift the fetcher behind a BankTransactionProvider interface now, so consolidating with #101 doesn't force a single winner — GoCardless (for legacy users), a cert-free PSD2 aggregator, and CSV can each implement it, with company settings choosing per-tenant. The matching engine then never has to care which one fed it rows.

Full disclosure — I maintain open-banking.io (a cert-free EU/UK PSD2 bank-data API), so I spend a lot of time in exactly this provider-decision space. Happy to share notes on the eIDAS-vs-cert-free trade-offs if useful.

[nielsdrost7]

@john-frandsen thanks, man!
There's a lot of information in there that will help building this issue