SEPA Direct Debit: Checkout and Customer Account
How SEPA Direct Debit works in the storefront: checkout with a new or existing mandate, validation rules for IBAN, BIC and account holder, the mandate page in the customer account, and PDF download for customers and guests.
SEPA Direct Debit: Checkout and Customer Account
Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net
Checkout flow
- The customer selects the SEPA Direct Debit payment method. The plugin's fields appear below it.
- The customer has no active mandate yet, or chooses new bank details: they enter IBAN, optionally BIC, and the account holder (prefilled with first and last name), read the mandate text and confirm it with "I agree to the SEPA direct debit mandate".
- When the checkout is submitted, the server validates the data. If something is missing or the IBAN is invalid, the order is not created.
- When the order is created, the plugin stores the new mandate with an encrypted IBAN and dispatches the event
mmd.sepa_payment.mandate.created, see Developer API. - The order confirmation page and the order details contain a link to the mandate PDF.
The plugin does not collect the amount. It only records the mandate, see the notice on the overview page.
Using an existing mandate
If the logged-in customer has an active mandate, checkout shows the preselected option "Use existing SEPA mandate:" with the masked IBAN, account holder and mandate reference. The customer can untick it and enter new bank details instead.
- If the existing mandate is used, the plugin creates no new mandate and dispatches no event.
- If the customer enters new bank details, the plugin revokes the previous active mandate and creates a new one. A customer has at most one active mandate.
- Guests are supported: a guest customer also gets a mandate and can download the PDF.
Validation rules
| Field | Rule | When checked |
|---|---|---|
| IBAN | Spaces and dashes are removed and the value is uppercased. Then: 15 to 34 characters, format country code + two check digits + alphanumeric, country-specific length and checksum (modulo 97). | In the browser (checksum) and on the server when submitting |
| IBAN countries | The 27 EU member states plus Iceland, Liechtenstein, Norway, Switzerland, Monaco, San Marino, Vatican City and the United Kingdom. Other country codes are rejected. | Server |
| BIC | Optional. If given: 8 or 11 characters according to ISO 9362. | Server, when the mandate is created |
| Account holder | Required, 2 to 70 characters. Allowed are letters A-Z and a-z without umlauts and ß, digits, spaces and / - ? : ( ) . , ' +. |
Empty check on submit, character check only when the mandate is created |
| Mandate confirmation | The checkbox must be ticked. | Server |
The account holder character check only runs once the order already exists. A name with an umlaut, for example "Müller", therefore leads to a failed payment instead of an error message on the form, see Troubleshooting.
Mandate page in the customer account
Logged-in customers find the entry SEPA Direct Debit Mandate in the customer account sidebar, directly below the payment methods (path /account/sepa-mandate).
With an active mandate the page shows the mandate reference, masked IBAN (for example DE89****3000), BIC (if present), account holder, date of issue and status. The Revoke mandate button asks for confirmation and revokes the mandate. On the next order the customer then enters new bank details.
Without an active mandate the page shows a form Create new SEPA direct debit mandate with IBAN, BIC, account holder and consent. The mandate is created immediately, no order required.
On the customer account page only the browser checks that the consent is ticked. The server does not evaluate the checkbox. Also, creating a mandate through the customer account page does not dispatch the event
mmd.sepa_payment.mandate.created.
Downloading the mandate PDF
| Where | Who | Access |
|---|---|---|
| Order confirmation page | Customer or guest | The link carries the order's deepLinkCode |
| Order details in the customer account | Logged-in owner of the order | Path /sepa-mandate/download/{orderId} |
The link only appears for orders paid with the SEPA Direct Debit payment method. Anyone who is neither the order owner nor knows the matching deepLinkCode gets a 404 response, and the attempt is written to the log.
The PDF contains the data of one mandate of the customer, not of a single order. Both downloads load the customer's mandate without restricting to active mandates and without any sorting. If a customer has several mandates, for example a revoked one and a new one, it is not defined which of them ends up in the PDF. It can also be an older, revoked mandate.
The PDF shows creditor data, account holder with the full IBAN, the mandate text, the payment type "One-off payment / Recurring payments" and a date and signature line. It is an A4 document in German or English depending on the shop language.