Deutsche Version

Back to overview

SEPA Direct Debit: Developer API

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

The plugin gives other plugins three integration points: an event for new mandates, a service for accessing mandates, and HTTP routes for admin and storefront.

MandateCreatedEvent

The event is dispatched after a new mandate has been stored while an order is completed. It is not dispatched when an existing mandate is reused, and not when a customer creates their mandate on the customer account page.

The event is dispatched under its name. Subscribe to the string mmd.sepa_payment.mandate.created; a subscription by class name is not triggered.

Example: 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;
        }

        // Example: hand the mandate data to an ERP system
        $reference = $mandate->getMandateReference();
        $holder = $mandate->getAccountHolder();
        $orderId = $event->getOrderId();
    }
}

Optional dependency

If your plugin should only optionally support the SEPA plugin, use the event name as a string and type the parameter as object, so there is no hard dependency on the event class:

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

SepaMandateServiceInterface

Mmd\SepaPayment\Service\Contract\SepaMandateServiceInterface is registered as a service (alias to SepaMandateService) and can be injected via the constructor.

The SepaMandateEntity entity offers, among others, getMandateReference(), getAccountHolder(), getBic(), getStatus(), getSignedAt(), getRevokedAt(), getCustomerId(), isActive() and isRevoked(). getIban() returns the encrypted IBAN only. getMaskedIban() on the entity always throws an exception; use the service instead.

Example: reading a customer's mandate

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(),
        ];
    }
}

The decrypted IBAN is personal bank account data. Call getDecryptedIban() only when you really need it, and never write it to logs.

Admin API routes

All routes are in the API scope and require an admin login.

The plugin does not register the privileges mmd_sepa_mandate.viewer and mmd_sepa_mandate.editor in the admin role management. The routes are therefore only usable for administrators with full access.

In addition, the mmd_sepa_mandate entity is reachable through the admin's standard entity API.

Storefront routes

The bundled checkout script does not call the validate-iban route; it validates the IBAN in the browser.

Orders and mandates

The plugin stores no link between an order and a mandate. The mandate belongs to the customer. You only learn the order from the MandateCreatedEvent via getOrderId().

Integration examples

The event is suited to report mandate data to your own systems, such as an ERP, a CRM or accounting software, or to trigger a notification. The plugin does not ship such integrations; you build them yourself on top of the event.