SEPA direct debit with online mandates: PrestaShop module documentation

Overview

The dfsepadebit module adds SEPA direct debit as a payment method in PrestaShop 8 and 9. The customer signs a mandate online during checkout with a code sent by email. Each order, each subscription instalment or each one-off collection becomes a collection pre-notified to the customer. You generate the pain.008 file and upload it to your bank, then import the return files to update payments and rejects.

The module does not connect to your bank and no data passes through a third party: funds go straight to your account.

Prerequisites

• A SEPA creditor identifier and a SEPA direct debit agreement from your bank. Mention the B2B scheme if you debit businesses.
• The file format your bank accepts (pain.008.001.02 or pain.008.001.08) and its submission deadline (usually 1 TARGET business day before the collection date).
• A shop selling in EUR: the payment method only appears for carts in euros.
• PrestaShop 8.0 to 9.x, PHP with the OpenSSL extension (AES-256-GCM encryption of IBANs).
• A daily cron task (hosting panel or external service) for schedules and automatic confirmations.

Installation

1. In Modules > Module Manager, click Upload a module and select the dfsepadebit ZIP.
2. The module creates its tables, two order statuses (“Awaiting SEPA direct debit” and “SEPA direct debit rejected”) and a Sell > SEPA direct debit menu.
3. Open the configuration and fill in the creditor. Until the name, creditor identifier and IBAN are valid, the payment method stays hidden.
4. Copy the cron URL shown at the top of the configuration and schedule it once a day.

Configuration

Creditor

Creditor name (as it will appear on your customers’ statements), creditor identifier, IBAN of the credited account, BIC (optional in the EEA) and address. The identifier and IBAN are checked on save.

Mandates and checkout

• Scheme of new mandates: SEPA B2B or SEPA Core.
• Mandate reference prefix: letters and digits, 8 characters maximum (DF by default).
• Signature with a code sent by email: recommended. When disabled, the customer signs with a checkbox.
• Only for customers with a company name: the payment method is offered only when the invoice address has a company.
• Allowed customer groups, minimum and maximum order amounts.
• Maximum outstanding per customer: unpaid collections plus the current cart. Above it, the payment method is hidden for this customer.
• Hide after rejects in the last 12 months: 2 by default, 0 to disable.

Collections and bank files

• Pre-notification period: the legal default is 14 days. A shorter period (the module suggests 2 days) is only valid if it is written in your terms of sale. An order is debited at the end of this period.
• Submission deadline of your bank, in TARGET business days.
• File format: pain.008.001.02 (the most widely accepted) or pain.008.001.08.
• Batch booking: one credit per file on your statement, or one credit per collection.
• First debit as FRST: keep it enabled if your bank still requires the FRST sequence.
• Generate the bank file automatically: the daily task builds the file for collections due within N days and emails it as an attachment to the alert address.
• Mark as paid automatically after N days without reject (5 by default). 0 to confirm manually or with camt.054.

Rejects

• Reason codes with automatic retry: AM04, MS03 by default.
• Maximum number of retries and delay before a retry.
• Reject fee added to the retry amount, only if your terms of sale provide for it.
• Reason codes that revoke the mandate: AC01, AC04, AC06, AC13, MD01, MD07 by default.
• Email for merchant alerts: rejects, revocations, bank changes, paused schedules, automatic files.

Customer journey

Signature at checkout

At the payment step, the customer chooses “Pay by SEPA direct debit”. With an active mandate, they select their account (masked IBAN) and confirm the order. Otherwise a form opens in the payment block, prefilled from the invoice address: company, account holder, address, IBAN (checked while typing) and BIC. They read the mandate text, tick the acceptance box and receive a 6-digit code by email. The mandate is signed as soon as the code is entered. Until then, order confirmation is blocked with a message.

Customer account

The My SEPA mandates page lists mandates with their PDF, current schedules and recent debits. 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 details of each order show the debit 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, 90-day reject rate, monthly recurring revenue of fixed-amount schedules, active and pending mandates. A chart shows the next 6 weeks (collections created and forecast of schedules). Latest rejects and mandates awaiting signature, with a Remind button, complete the page. A warning appears if the daily task has not run for 36 hours.

Mandates

The New mandate button offers two modes: send an online signature request to the customer (they receive a secure link, no login required) or register a paper mandate already signed, with its signature date. 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, IP, browser, SHA-256 fingerprint), the PDF, schedules and collections, and allows revocation.

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). The New one-off collection button creates a collection on an active mandate, optionally linked to an order.

Recurring schedules

A schedule is linked to a mandate (active or awaiting signature) and works in two modes: fixed amount or repeat an order (the reference order is placed again at current prices at each due date, then debited). Choose the frequency, next due date and number of debits (0 for open-ended). The customer receives a summary email. A schedule can be paused, resumed or stopped.

Bank files

1. Choose the latest due date of the collections to include and click Generate.
2. Download the XML file and upload it to your bank the same day.
3. Then import the bank return files: pain.002 (file or transaction rejects), camt.054 or camt.053 (returns and credits).

A file not yet sent can be cancelled: its collections go back to export.

Life of a collection

1. To export: created with the order, by a schedule or manually. The customer receives the pre-notification.
2. Sent to the bank: included in a file. The date may move to the first possible day of the TARGET2 calendar.
3. Paid: after the period without reject, on camt.054 import or manually. The order moves to “Payment accepted”.
4. Rejected: R-code recorded, order in “SEPA direct debit rejected”, retry or revocation depending on the configuration.

Handling rejects

A file or payment block reject in a pain.002 (format, unknown creditor identifier…) does not concern the customer: collections go back to export for the next file.

Daily task (cron)

The token-protected cron URL creates the collections of schedules falling due within the pre-notification period, generates the automatic file when enabled, marks collections without reject as paid after the configured delay, expires mandates unused for 36 months and purges signatures abandoned for 60 days. 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 with PDF, signature request, schedule notice, debit pre-notification, reject.
• To the merchant: reject, revocation by the customer, bank change, paused schedule, automatic file ready (XML attached).

Templates are provided in 8 languages in mails/ and can be edited like native emails.

Invoice, order page and GDPR

The PDF invoice carries a pre-notification mention (amount, date, masked IBAN, mandate reference, creditor identifier), which becomes “paid on” once the collection is confirmed. The back-office order page shows the mandate and collections. With the official GDPR module, mandates are included in the data export; when a customer is deleted, only pending mandates and those closed for more than 14 months are anonymised, the others being kept as evidence.

Troubleshooting

The payment method does not appear

Check that the creditor is valid (green box at the top of the configuration), that the cart is in EUR, that the customer is logged in (not a guest), that the invoice address has a company if the option is on, and that the customer has not exceeded the allowed outstanding or number of rejects.

MD01 reject on a B2B mandate

The customer did not register 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 one minute; the code is valid for 10 minutes.