Teilzahlungen an bexio schicken

Möglichkeit für Teilzahlungen

Ab Version 2.10.0 des WooCommerce Bexio Automator Plugins ist es möglich, Teilzahlungen an unseren Plugin-Service zu schicken, welcher diese verarbeitet und an bexio schickt. Wichtig: dies ist keine offizielle Unterstützung, das Plugin bietet lediglich die Möglichkeit, dies so zu schicken, es werden aber nicht automatisch verschiedene Zahlungen auf einer Bestellung identifiziert und geschickt.

Implementation

Grundsätzlich gibt es 2 Möglichkeiten, Teilzahlungen an bexio zu schicken. Primär ist vorgesehen, dass Teilzahlungen direkt über die API Klasse geschickt werden.

Möglichkeit 1 - direkt über API Klasse

Beim Aufruf der Methoden pay_invoice() oder pay_order() in der API Klasse können als 3ter Parameter direkt Anweisungen für Teilzahlungen gemacht werden. Wenn du die Zahlungen selbständig auslösen willst, solltest du sicherstellen, dass diese nicht über das Plugin automatisch bereits ausgelöst wurden - verwende dazu z.B. den Filter 'raptus-wc-bexio-connector-sync-invoice', um die automatische Synchronisierung einer Zahlung für die jeweilige Bestellung, für die du Teilzahlungen schicken willst, zu verhindern (andernfalls könntest du eine Überbezahlung auslösen).

Möglichkeit 2 - über Filter bei Synchronisierung einer separaten Zahlung

Es wurde ein neuer Filter eingeführt, mit dem Anweisungen für Teilzahlungen definiert werden können: 'raptus_wc_bexio_connector_partial_payments'. Es steht zudem auch die Action 'raptus_wc_bexio_connector_after_partial_payments' zur Verfügung, welche aufgerufen wird, wenn Teilzahlungen geschickt wurden und die Antwort verarbeitet wurde, damit überprüft werden kann, welche der verarbeiteten Teilzahlungen erfolgreich waren. Das Plugin prüft in diesem Fall jeweils den in der Antwort aufgeführten Restbetrag - ist dieser grösser als 0, wird auf der Bestellung hinterlegt, dass die Rechnung nur als "Teilweise" markiert werden konnte.

Wichtig:

• Dieser Filter ist nur verfügbar, wenn Zahlungen separat synchronisiert werden (wenn pay_invoice() oder pay_order() aufgerufen werden).
• "separat synchronisiert" bedeutet: die Zahlung wird später synchronisiert als der Auftrag, d.h. zu einem anderen Bestellstatus.

Teilzahlungen definieren

Um Teilzahlungen zu definieren, kann ein Array mit den entsprechenden Zahlungen geschickt werden. Hierbei gilt zu beachten:

• Wird als Wert 'false' übermittelt, löst dies eine Zahlung über den übrigen offenen Restbetrag auf der Rechnung aus.
• Für jede Teilzahlung kann optional auch ein abweichendes Bankkonto und Datum angegeben werden. Werden keine angegeben, gelten die Standarddaten (das Bankkonto der Rechnung selbst, resp. das Datum der WooCommerce-Bestellung).
• Es sollte ein assoziatives Array verwendet werden, resp. solltest du jeder Zahlung einen Schlüssel geben, über den du diese später in der Antwort leicht identifizieren kannst, um die verarbeiteten Zahlungen zu überprüfen. Die Schlüssel können frei definiert werden (im nachfolgenden Beispiel "payment_a" & "payment_b").

Ein Beispiel, wie Teilzahlungen definiert werden könnten:

$invoice_id = 1234; // the id of the bexio invoice
$invoice_date = "2025-09-15";
$partial_payments = [
    'payment_a' = [
        'value' => 10.0,
        'bank_account_id' => 4,
        'date' => '2025-09-05',
    ],
    'payment_b' = [
        'value' = false
    ]
];
\Raptus\WC\BexioConnector\Api::instance()->pay_invoice($invoice_id, $invoice_date, $partial_payments);

Dies würde dazu führen, dass auf der Rechnung 2 Zahlungseingänge hinterlegt werden: 1x für 10.0 über das Bankkonto mit der ID 4 und dem Datum 05.09.2025 und 1x für den Restbetrag, damit die Rechnung anschliessend im Status "Bezahlt" ist.

Beachte:

• Wenn du Teilzahlungen schickst, aber am Ende keine Zahlung über den Restbetrag auslöst, kann es sein, dass die bexio-Rechnung nicht vollständig bezahlt ist. Sie wäre dann nicht im Status "Bezahlt", sondern im Status "Teilweise".
• Wurden Teilzahlungen geschickt, enthält die Antwort daher auch immer den noch offenen Restbetrag der Rechnung - verwende diesen um allfällige weitere Zahlungen auszulösen.

Teilzahlungen überprüfen

Wurden Teilzahlungen geschickt, ist die Antwort vom Plugin-Service nicht nur 'true' oder 'false', sondern enthält ein Array mit dem Status für jede definierte Teilzahlung. Beachte: die Teilzahlungen können als assoziatives Array definiert werden, dies erleichtert deren Identifikation in der Antwort vom Service. Analog dem Beispiel oben, könnte die Antwort vom Service z.B. wie folgt aussehen:

[
    "payments" => [
        "payment_a" => true,
        "payment_b" => true
    ],
    "due_amount" => 0
]

Wichtig: um zu überprüfen, ob alle Teilzahlungen erfolgreich waren, solltest du "payments" mit den von dir geschickten Teilzahlungen vergleichen - im Falle eines Fehlers könnte es sein, dass nicht alle geschickten Teilzahlungen verarbeitet werden konnten. Ebenso sollte "due_amount" überprüft werden - ist der Restbetrag grösser als 0, bedeutet dies, dass die Rechnung noch nicht vollständig bezahlt wäre. Leite aus diesen Daten entsprechende Folgemassnahmen ab.

Wichtige Hinweise

Folgende Dinge sollten beachtet werden, wenn du Teilzahlungen verwenden willst:

• Dies ist keine offizielle Unterstützung von Teilzahlungen, insofern dass das Plugin diese automatisch aus einer Bestellung auslesen kann - du bist selbständig dafür verantwortlich, Anweisungen für Teilzahlungen zu schicken, resp. diese auszulösen. Das Plugin stellt dir dafür nur die notwendigen Mittel zur Verfügung.
• Teste eine Implementation in deinem Shop zuerst in einer Testumgebung, um sicherzustellen, dass die Teilzahlungen wie von dir gewünscht synchronisiert werden, bevor du die Implementation im Live-Shop aktivierst. Unser Plugin kann keine nachträglichen Änderungen vornehmen, nachdem etwas synchronisiert wurde - unser Support kann dir dabei nicht helfen.
• Du bist selbst für die korrekte Hinterlegung der notwendigen Zahlungen verantwortlich. Konnten aufgrund eines Fehlers z.B. nicht alle Teilzahlungen verarbeitet werden, musst du sicherstellen, dass die offenen Teilzahlungen erneut geschickt werden. Ebenso solltest du sicherstellen, dass der vollständige Rechnungsbetrag gedeckt wird, damit die Rechnung als "Bezahlt" markiert wird.
• Es sollten direkt alle Teilzahlungen auf einmal geschickt werden - versuche nicht, selbständig die API Methoden mehrmals aufzurufen, da dies ansonsten zu mehr Serverlast und längerer Wartezeit führt.
• Der Plugin-Service kann nicht erkennen, ob eine Rechnung überbezahlt wurde - schicke also nur Teilzahlungen für die Beträge, die du wirklich kennst. Üblicherweise sollten diese nur einen Teil des gesamten Betrages ausmachen, daher sollte als letzte Zahlungsanweisung immer eine Zahlung für den noch offenen Restbetrag ausgelöst werden (siehe Definition von Teilzahlungen).