English Version

Zurück zur Übersicht

SEPA-Lastschrift: Entwickler-API

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Das Plugin bietet anderen Plugins drei Anknüpfungspunkte: ein Event bei neuen Mandaten, einen Service für den Zugriff auf Mandate und HTTP-Routen für Admin und Storefront.

MandateCreatedEvent

Das Event wird ausgelöst, nachdem ein neues Mandat beim Abschluss einer Bestellung gespeichert wurde. Es wird nicht ausgelöst, wenn ein bestehendes Mandat wiederverwendet wird, und nicht, wenn ein Kunde sein Mandat auf der Kundenkonto-Seite anlegt.

Das Event wird unter seinem Namen ausgelöst. Abonniere deshalb den String mmd.sepa_payment.mandate.created, ein Abonnement über den Klassennamen wird nicht ausgelöst.

Beispiel: Event-Subscriber

<?php

namespace MyPlugin\Subscriber;

use Mmd\SepaPayment\Event\MandateCreatedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class SepaMandateSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'mmd.sepa_payment.mandate.created' => 'onMandateCreated',
        ];
    }

    public function onMandateCreated(MandateCreatedEvent $event): void
    {
        $mandate = $event->getMandate();

        if ($mandate === null) {
            return;
        }

        // Beispiel: Mandatsdaten an ein ERP-System übergeben
        $reference = $mandate->getMandateReference();
        $holder = $mandate->getAccountHolder();
        $orderId = $event->getOrderId();
    }
}

Optionale Abhängigkeit

Soll dein Plugin das SEPA-Plugin nur optional unterstützen, verwende den Event-Namen als String und tippe den Parameter als object, damit keine harte Abhängigkeit auf die Event-Klasse besteht:

public function onMandateCreated(object $event): void
{
    $mandateId = $event->getMandateId();
}

SepaMandateServiceInterface

Mmd\SepaPayment\Service\Contract\SepaMandateServiceInterface ist als Service registriert (Alias auf SepaMandateService) und kann per Konstruktor injiziert werden.

Die Entität SepaMandateEntity bietet unter anderem getMandateReference(), getAccountHolder(), getBic(), getStatus(), getSignedAt(), getRevokedAt(), getCustomerId() sowie isActive() und isRevoked(). getIban() liefert nur die verschlüsselte IBAN. getMaskedIban() an der Entität wirft immer eine Exception, nutze stattdessen den Service.

Beispiel: Mandat eines Kunden lesen

use Mmd\SepaPayment\Service\Contract\SepaMandateServiceInterface;
use Shopware\Core\Framework\Context;

class MyService
{
    public function __construct(
        private readonly SepaMandateServiceInterface $mandateService,
    ) {
    }

    public function describe(string $customerId, Context $context): ?array
    {
        $mandate = $this->mandateService->getMandateByCustomerId($customerId, $context);

        if ($mandate === null) {
            return null;
        }

        return [
            'reference' => $mandate->getMandateReference(),
            'ibanMasked' => $this->mandateService->getMaskedIban($mandate),
            'accountHolder' => $mandate->getAccountHolder(),
            'signedAt' => $mandate->getSignedAt(),
        ];
    }
}

Die entschlüsselte IBAN ist eine personenbezogene Bankverbindung. Rufe getDecryptedIban() nur auf, wenn du sie wirklich brauchst, und schreibe sie nicht in Logs.

Admin-API-Routen

Alle Routen liegen im API-Scope und verlangen eine Admin-Anmeldung.

Das Plugin registriert die Privilegien mmd_sepa_mandate.viewer und mmd_sepa_mandate.editor nicht in der Rollenverwaltung des Admins. Die Routen sind deshalb nur für Administratoren mit Vollzugriff nutzbar.

Zusätzlich ist die Entität mmd_sepa_mandate über die Standard-Entity-API des Admins erreichbar.

Storefront-Routen

Das mitgelieferte Checkout-Skript ruft die Route validate-iban nicht auf, es prüft die IBAN im Browser.

Bestellungen und Mandate

Das Plugin speichert keine Verknüpfung zwischen Bestellung und Mandat. Das Mandat gehört zum Kunden. Die Bestellung erfährst du nur im MandateCreatedEvent über getOrderId().

Beispiele für Integrationen

Das Event eignet sich, um Mandatsdaten an eigene Systeme zu melden, etwa an ein ERP, ein CRM oder eine Buchhaltung, oder um eine Benachrichtigung auszulösen. Solche Integrationen liefert das Plugin nicht mit, du baust sie über das Event selbst.