SEPA direct debit with online mandates: PrestaShop module documentation
Install, configure and use the SEPA direct debit module: mandate signed online with sealed evidence, validated pain.008 file, schedules, rejects and GDPR.
Overview
The dfsepadebit module adds SEPA direct debit as a payment method to PrestaShop 1.7.8, 8 and 9. The customer signs a mandate online during checkout, with a code received by email, without leaving the payment page. Each order, each instalment of a schedule and each one-off debit becomes a collection pre-notified to the customer. You generate the pain.008 file and upload it to your bank’s website. You then import the return files to update payments and rejects.
The module does not connect to your bank and sends no data to a third party: the funds go straight to your account.

New in 2.0.0: online signature fixed (it failed in 1.1.0 on PrestaShop 8 and 9), PrestaShop 1.7.8 support, one-off mandates (OOFF), FNAL sequence, pain.008.001.08 by default, every file validated against the official ISO 20022 schema, sealed mandate PDF and chained audit trail, bank files encrypted and never sent by email, permissions per employee profile, setup assistant and configuration in 5 tabs.
Requirements
- A SEPA creditor identifier and a SEPA direct debit agreement with your bank. Mention the B2B scheme if you collect from businesses.
- The file format accepted by your bank (pain.008.001.08 or pain.008.001.02) and its submission deadline (usually 1 TARGET business day before the collection date).
- A shop with the euro enabled: the payment method only appears for carts in euros.
- PrestaShop 1.7.8 to 9.x, PHP 7.1 to 8.5 with the OpenSSL extension (AES-256-GCM encryption of IBANs and files).
- A daily cron job (hosting or external service) for schedules, automatic bank files and payment confirmations.
Installation and upgrade
- In Modules > Module Manager, click Upload a module and select
dfsepadebit-2.0.0.zip. - The module creates its tables, two order statuses (“SEPA direct debit scheduled” and “SEPA direct debit rejected”) and the Sell > SEPA direct debit menu: Dashboard, Mandates, Collections, Recurring schedules and Bank files.
- Open the configuration. The setup assistant at the top of the page shows what is left to do: creditor name and full address, creditor identifier, IBAN, euro enabled, daily task, first bank file accepted by your bank. Until the creditor is complete, the payment method stays hidden.
- Copy the cron URL shown in the configuration and schedule it once a day. The New cron URL button generates another one and invalidates the old one.

Upgrading from 1.1.0: upload the new ZIP over the old one. Mandates, collections, schedules, bank files and settings are kept, including the pain.008.001.02 format if you had chosen it. The upgrade recomputes the IBAN fingerprints, encrypts the bank files already generated, opens the audit trail of each mandate and renames the order statuses that still have their original name. Mandates signed in 1.1.0 have no sealed PDF: their PDF is regenerated from the original evidence and marked “regenerated copy”.
Configuration
The configuration is split into 5 tabs.
Creditor
Creditor name (as it will appear on your customers’ statements), creditor identifier, IBAN of the account credited, BIC (optional in the EEA) and full address: street, postcode, city and country are required because they appear on the mandate. The creditor identifier is checked with its check digits (MOD 97-10) and the IBAN with its check digits and the length of its country.
Mandates and checkout
- Scheme of new mandates: SEPA B2B (business to business, no refund right, the debtor must register the mandate with their bank) or SEPA Core (any customer, refund possible within 8 weeks).
- Type of payment of the mandates signed online: recurrent (the customer signs once and the mandate is reused for the next orders and schedules) or one-off (one mandate per order, valid for a single debit).
- Mandate reference prefix: letters and digits, 8 characters maximum (DF by default).
- Signature with a code sent by email: recommended, it strengthens the evidence file. When off, the customer signs with a simple checkbox.
- Attach the mandate PDF to the confirmation email: the attached copy shows the IBAN partially hidden. The complete copy stays available in the customer account.
- Only for customers with a company name: the payment method is shown only when the invoice address has a company.
- Allowed customer groups, minimum and maximum order amounts.
- Maximum outstanding per customer: collections not yet paid plus the current cart. Above it, the payment method is hidden for that customer.
- Hide after rejects in the last 12 months: 2 by default, 0 to disable.
Collections and bank files
- Pre-notification period: the rulebooks set 14 calendar days unless another period is agreed with the debtor. The module suggests 2 days: a period shorter than 14 days must be written in your terms of sale. The period is stated in the mandate text. An order is debited at the end of this period.
- Submission deadline of your bank, in TARGET business days.
- File format: pain.008.001.08 by default (2019 version of ISO 20022, used by the EPC implementation guidelines in force). Keep pain.008.001.02 only if your bank still asks for it.
- Batch booking: one credit per file on your statement, or one credit per collection.
- Send the first debit of a mandate as FRST: the rulebook allows RCUR from the first debit; keep FRST if your bank still requires it.
- Send the last debit of a limited schedule as FNAL: optional. After a FNAL debit the mandate is closed and cannot be used again.
- Always include the debtor address in the file: the address is always sent for accounts outside the EEA; turn this on if your bank asks for it for every debit.
- Generate the bank file automatically: the daily task creates the file of the collections due within N days and sends a notice to the alert address. The file itself is never sent by email: you download it in the back office.
- Mark as paid automatically after N days without a reject (5 by default). 0 to confirm by hand or with camt.054.
Rejects
- Reason codes with automatic retry: AM04 and MS03 by default.
- Maximum number of retries and delay before a retry.
- Reject fee added to the retry, only if your terms of sale provide for it.
- Reason codes that revoke the mandate: AC01, AC04, AC06, AC13, MD01 and MD07 by default. The mandate is closed and its schedules are cancelled.
- Email for merchant alerts: rejects, revocations, bank changes, paused schedules and automatic bank files. Shop email if empty.
Data and privacy
- Keep closed mandates after the last debit: 13 months minimum (see GDPR below).
- Delete all data on uninstall: off by default. Mandates are evidence; deleting them can breach your retention obligations.
Customer journey
Signature in the checkout
At the payment step, the customer chooses SEPA direct debit. The block shows the amount and the collection date. If they already have an active mandate, they select their account (masked IBAN) and place the order.
Otherwise, they sign a new mandate in 3 steps inside the payment block. The form is prefilled from the invoice address: company, account holder, address, place of signature (the city), IBAN and BIC. The IBAN is formatted and checked while typing: length for the country, check digits, BIC required outside the EEA. The customer reads the mandate text (collapsible) and ticks the acceptance box. In B2B, they also confirm that the account is a business account and that they will register the mandate with their bank.

They receive a 6-digit code by email, valid for 10 minutes. A new code can be requested after 45 seconds; after 5 wrong attempts a new code is needed. The mandate is signed as soon as the right code is entered. Until then, placing the order is blocked with a message.


The confirmation page shows the amount, the collection date, the masked IBAN, the mandate reference and the creditor identifier.

If the theme prevents the script from running, the customer is redirected after confirming to the standalone signature page, then the order is created. An order cannot be created twice for the same cart, and the amount is always recomputed on the server from the cart.
Confirmation email and mandate PDF
The customer receives the confirmation of their mandate with the masked IBAN and a link to their mandates. If the option is on, the attached PDF copy also has the IBAN masked.

The PDF carries the SEPA mandate details: title “SEPA Business to Business Direct Debit Mandate” in B2B or “SEPA Direct Debit Mandate” in Core, unique reference, creditor identifier and address, debtor, account, type of payment (recurrent or one-off), authorisation text, place and time of signature, signature method and SHA-256 fingerprint.

Standalone signature page
When you send a signature request from the back office, the customer receives a secure link to a signature page, with no login required. It shows the creditor summary and the same checks as in the checkout.

Customer account
The My SEPA mandates page shows each mandate as a card: PDF, running schedules and latest collections. The customer can revoke a mandate or click Change bank account: they sign a new mandate, their schedules and collections not yet sent move to the new account and the old mandate is closed. The link appears in My account only for customers in the allowed groups or who already have a mandate. The details of each order show the collection date and its status.

Back office
Dashboard
Amount to send to the bank within 7 days, amount at the bank awaiting confirmation, collected this month, reject rate over 90 days, monthly recurring revenue of fixed-amount schedules, active and pending mandates. A chart shows the next 6 weeks (collections created and schedule forecast). The latest rejects and the mandates waiting for signature, with a Remind button, complete the page. An alert appears when the daily task has not run for 36 hours.

Mandates
The list shows the reference, the debtor, the masked IBAN, the scheme (B2B or Core), the type (recurrent or one-off) and the status. The New mandate button offers two modes: send an online signature request to the customer, or record a paper mandate already signed with its place and date of signature. The Replaces the mandate field moves the schedules of an existing mandate once the new one is signed.

The mandate page shows the signature evidence (date, method, place, IP address, browser, evidence fingerprint), the sealed PDF with its SHA-256, the schedules, the collections and the chronological audit trail with its integrity check. The Display the full IBAN button requires the edit permission and each display is logged. The customer page of the back office also shows a SEPA mandates block with a button to request a new mandate.

Collections
Filterable list of all collections with their status: to export, sent to the bank, paid, rejected, cancelled. From a collection page: mark as paid, record a reject with its code, cancel (before export). After a reject with a retry code, the page shows the scheduled retry and the history. The New one-off collection button creates a collection on an active mandate, optionally linked to an order. A zero amount is refused, and a one-off mandate accepts a single collection only.

Recurring schedules
A schedule is linked to a recurrent mandate (active or waiting for signature) and works in two modes: fixed amount or repeat an order (the reference order is placed again at current prices at each instalment, then debited). Choose the frequency, the next due date and the number of collections (0 for no end). The customer receives a summary email. A schedule can be paused, resumed or stopped.
Bank files
- Choose the latest due date of the collections to include and click Preview: nothing is exported. The preview shows one payment block per scheme, sequence (FRST, RCUR, OOFF, FNAL) and date, and the dates moved forward to respect your bank’s deadline.
- Click Generate. The file is validated against the official ISO 20022 schema before it is saved, then stored encrypted with its SHA-256 fingerprint. The list shows the validation result and the number of downloads.
- Download the file and upload it to your bank’s website the same day. The module never sends anything to a bank.
- Then import the return files: pain.002 (rejected file or transactions), camt.054 or camt.053 (returns and credits). The same file imported twice is not processed again.

A bank file not yet sent can be cancelled: its collections go back to “to export”. Generation is locked: two clicks, two employees or a simultaneous daily task cannot export the same collections twice.
Order page
The order page of the back office shows a SEPA direct debit block: mandate, masked IBAN, amount, due date and status of each collection.

Lifecycle of a collection
- To export: created with the order, by a schedule or by hand. The customer receives the pre-notification. The order is in “SEPA direct debit scheduled”.
- Sent to the bank: included in a bank file. The date can be moved to the first possible day according to the TARGET calendar and the submission deadline.
- Paid: after the delay without a reject, when a camt.054 is imported or by hand. The order moves to “Payment accepted”.
- Rejected: reason code recorded, order in “SEPA direct debit rejected”, retry or revocation depending on the configuration.
Sequences
- FRST: first debit of a recurrent mandate, when the option is on. Only one first debit per mandate and per file; if it is rejected, the next attempt is sent as FRST again.
- RCUR: following debits of a recurrent mandate.
- OOFF: single debit of a one-off mandate. A retry after a reject is treated as the same payment; have this practice confirmed by your bank if needed.
- FNAL: last debit of a limited schedule, when the option is on. The mandate is closed after payment.
A mandate that has not been used for any collection for 36 months expires.
Handling rejects
| Code | Meaning | Default action |
|---|---|---|
| AM04 | Insufficient funds | Retry |
| MS03 | Reason not specified by the bank | Retry |
| AC01, AC04, AC06 | Account incorrect, closed or blocked | Mandate revoked |
| AC13 | Consumer account in B2B | Mandate revoked |
| MD01 | No valid mandate (often a B2B mandate not registered with the bank) | Mandate revoked |
| MD07 | Debtor deceased | Mandate revoked |
| MS02, MD06 | Refusal or refund requested by the debtor | Alert, manual handling |
A file or payment block reject in a pain.002 (format, creditor identifier not recognised…) does not concern the customer: the collections go back to “to export” for the next bank file.
Signature evidence and audit trail
- Evidence snapshot: at signature time, the module records a timestamped snapshot with the exact mandate text and its fingerprint, the scheme, the type of payment, the place, the IP address, the browser, the signature method, the masked IBAN and its fingerprint. The full IBAN is never part of it.
- Sealed PDF: the mandate PDF is produced once, at signature, then stored encrypted. Its SHA-256 is recorded on the mandate and in the audit trail; later downloads return exactly this file.
- Audit trail: creation, code sent and wrong codes, signature, sealed PDF, emails, full IBAN displays, downloads, collections, exports, payments, rejects, revocation and anonymisation. The events of each mandate are chained with SHA-256: a modified or deleted row is reported on the mandate page.
The one-time code sent by email is an electronic signature within the meaning of Article 3(10) of the eIDAS Regulation (EU) No 910/2014; it is not a qualified signature. The module does not guarantee any particular legal value: its evidential weight and its acceptance by your bank are for you and your advisers to assess.
Security and employee permissions
- Mandate IBANs and bank files encrypted with AES-256-GCM, with a key derived from the shop secret key (settings file, not the database). Keep this file when you migrate the shop: without it, IBANs and bank files can no longer be read.
- Duplicates are found with an HMAC-SHA256 fingerprint, never with the IBAN in clear.
- Downloading a bank file, downloading the full PDF, displaying the full IBAN, sending a signature link again or running the tasks requires the edit permission on the relevant tab. A read-only profile gets a PDF copy with the IBAN masked and cannot download bank files.
- In multistore, an employee only sees the mandates, collections, schedules and bank files of the shops in their context.
- On the front office, a mandate is only accessible to its holder, in their shop, with a token against request forgery on revocation and the PDF.
- Imported return files are read without external entities (XXE protection).
Daily task (cron)
The cron URL, protected by a token, creates the collections of schedules due within the pre-notification period, generates the automatic bank file when it is enabled, marks as paid the collections without a reject after the configured delay, expires mandates unused for 36 months and purges signatures abandoned for 60 days. Two simultaneous runs cannot overlap. The Run the tasks now button on the Bank files page does the same for the current shop.
Emails sent
- To the customer: signature code, mandate confirmation, signature request, schedule notice, collection pre-notification, reject.
- To the merchant: reject, revocation by the customer, bank change, paused schedule, automatic bank file ready (with the link to the back office, no file attached).
The 8 templates are provided in 8 languages, in HTML and text, in mails/, and can be edited like the native emails. No email contains a full IBAN or a bank file.
Invoice, order page and GDPR
The PDF invoice carries a pre-notification notice (amount, date, masked IBAN, mandate reference, creditor identifier), which becomes “paid on” once the collection is confirmed.
With the official GDPR module, mandates (masked IBAN) and collections are included in the data export. On an erasure request, only pending mandates and closed mandates whose last debit is older than the configured retention period are anonymised: the IBAN, email, address and sealed PDF are then deleted. The other mandates are kept as evidence and you receive an alert.
Retention period: the EPC rulebooks refer to national law and require at least the refund period for an unauthorised transaction, that is 13 months after the debit date. National law, accounting law in particular, may require longer: set it with your advisers. The module does not set any national period and refuses a value below 13 months.
Limitations
- The module produces pain.008 files and reads pain.002, camt.054 and camt.053 files. It sends nothing to a bank and offers no EBICS connection or payment service provider.
- It does not guarantee the legal compliance of your use: check the format, deadlines, BIC, address and use of FRST with your bank, and your terms of sale, pre-notification period and retention period with your advisers.
- Only the common TARGET holidays are taken into account: 1 January, Good Friday, Easter Monday, 1 May, 25 and 26 December.
- The countries recently added by the EPC (Albania, Moldova, Montenegro, North Macedonia, Serbia) are accepted with a mandatory BIC; the actual participation of each bank is not checked.
Troubleshooting
The payment method does not appear
Check the setup assistant (complete creditor with its address), that the cart is in euros, that the customer is logged in (not a guest), that the invoice address has a company if the option is on, that the customer belongs to an allowed group, and that they have not exceeded the allowed outstanding amount or number of rejects.
MD01 reject on a B2B mandate
The customer has not registered the mandate with their bank. Ask them to do so with the mandate reference and your creditor identifier, then create a new one-off collection.
The customer does not receive the code
Check the PrestaShop email configuration and the customer’s spam folder. A new code can be requested after 45 seconds; it is valid for 10 minutes.
The bank refuses the file
Check the expected format (pain.008.001.08 or .02), the BIC and the debtor address. A file that does not match the ISO 20022 schema is never saved: the message shown at generation quotes the first errors. If the schema column shows “Not checked”, the PHP DOM or libxml extensions are missing on the server.
“Audit trail altered”
A row of the mandate audit trail was modified or deleted directly in the database. The message gives the event from which the chain is no longer intact. Restore the table from a backup.