# Deposit payment: deposit at checkout and balance on delivery

> Installation Install the module from Modules > Module Manager > Upload a module by sending the ZIP file, or copy the dfdeposit folder into the /modules/ directory of your shop…

- Page: <https://www.datafirefly.com/en/documentation/dfdeposit/>
- Language: en
- Last updated: 2026-10-07
- Other languages: [fr](https://www.datafirefly.com/documentation/dfdeposit/index.md), [es](https://www.datafirefly.com/es/documentation/dfdeposit/index.md), [de](https://www.datafirefly.com/de/documentation/dfdeposit/index.md), [it](https://www.datafirefly.com/it/documentation/dfdeposit/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfdeposit/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfdeposit/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfdeposit/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Installation

Install the module from **Modules > Module Manager > Upload a module** by sending the ZIP file, or copy the `dfdeposit` folder into the `/modules/` directory of your shop and click Install.

On installation, the module:

- creates its tables (deposits, Stripe transactions, rate rules);
- creates five order statuses: **Awaiting deposit**, **Deposit received, balance due**, **Balance requested**, **Ready for pickup, balance due** and **Shipped, balance due**;
- adds the **Orders > Deposits** menu and the **Deposit rates** screen, reachable from that menu and from the configuration;
- registers its hooks: payment options, product page, cart, order confirmation, customer account, back-office order page and PDF invoice.

On uninstall, the tables are kept on purpose: the numbering of deposit invoices and credit notes must stay continuous if you reinstall the module.

## Setup check

The configuration page starts with a list of checks in green, orange or red: a payment method ready, Stripe key accepted by Stripe, test mode still active, webhook secret filled in and date of the last event received, last cron run, trigger statuses present, a trigger status marked as paid, legal note on invoices. Fix any red line before opening sales.

The **Test the Stripe key** button queries Stripe with the key of the selected mode. The test also runs automatically on save when the key changes. Webhook and cron URLs are copied with the **Copy** button.

## Deposit rules

### Rate and minimum amount

**Deposit rate**: share of eligible products paid at checkout, between 1 and 99%. **Minimum order amount** (tax incl.): below it, the deposit option is hidden. 0 means no minimum.

### Eligible categories and other products

Leave the list empty to offer the deposit on the whole catalog, or select the categories concerned. The **Other products in the cart** setting decides what happens to non-eligible products in a mixed cart: **Paid in full within the deposit** (added at 100% to the deposit amount) or **Hide the deposit option**.

### Shipping and rounding

Shipping costs can be **paid with the balance** (default), **paid with the deposit** or **split at the deposit rate**. Rounding is to the cent or up to the next whole unit, for amounts like €748 instead of €747.35.

### Customer groups and display

**Customer groups**: only the selected groups see the option, for example professionals for pro equipment. Empty = all customers. **Show on product pages** adds a line under the add to cart button such as "Order with a 30% deposit: €747.00 now, €1,743.00 on shipping or pickup". **Show in the cart** adds the deposit / balance split to the summary.

## Rates per product, category or brand

Open **Deposit rates** from the deposit list or the configuration, then **Add a rate**. Each rule targets a single item: a product (search by name, reference or ID), a category or a brand, with a rate between 0 and 99%.

Priority order: the product rule, then the rule of the deepest category among the product's categories, then the brand rule, then the default rate from the configuration. A **0%** rate excludes the target: the product is paid in full with the deposit. A rule applies even if the product's category is not among the eligible categories.

When a cart contains products with different rates, the deposit is calculated line by line. The rate shown to the customer and on the invoice is then the effective rate, for example 48.39%.

## Balance

### Statuses that request the balance

When an order with a paid deposit enters one of these statuses, the customer receives the balance request email with the payment link. By default: **Balance requested**, **Ready for pickup, balance due** and **Shipped, balance due**.

Do not use the native **Shipped** status for an order whose balance is unpaid: it is marked as paid in PrestaShop, which then automatically records the rest as paid. Use **Shipped, balance due**. The setup check flags a trigger status marked as paid.

### Status once fully paid

Status applied when the balance reaches zero (Payment accepted by default), and a second one for orders already shipped (Shipped by default). This is when PrestaShop generates the final invoice.

### Reminders and notifications

**Reminder every** X days and **Maximum reminders** control the reminder emails sent by the cron task. **Team notifications**: addresses, separated by commas, alerted when a customer pays a deposit or a balance online, when a deposit arrives with an unexpected amount, and when a transfer order is placed.

### Other ways to pay the balance

Free text per language shown on the balance page and in emails, for example "The balance can also be paid by card or cash when you collect your order at the workshop".

## Card payment (Stripe)

1. Enable **Enable card payment** and choose **Test** or **Live** mode.
2. Paste the secret key of the chosen mode (`sk_test_`, `sk_live_` or a restricted `rk_` key). Saved keys are masked on display.
3. In the Stripe dashboard, Developers > Webhooks, create an endpoint with the URL shown in the configuration and the events `checkout.session.completed` and `checkout.session.async_payment_succeeded`.
4. Copy the `whsec_` signing secret into the **Webhook signing secret** field.

The customer is redirected to a Stripe Checkout page. On return, the order is created immediately. If the customer closes the tab before returning, the webhook creates the order. Each session is processed only once.

After your first test payment, the "Last Stripe event received" line of the setup check should turn green. If it stays orange, check the endpoint URL and events.

## Bank transfer

Enable **Offer the deposit by transfer** and fill in the account holder, IBAN, BIC and bank name. The order is created in **Awaiting deposit**; the customer sees your bank details on the confirmation page and receives them by email, with the order reference as payment reference.

**Show bank details for the balance** adds transfer as a way to pay the balance. **Cancel unpaid transfer orders after** X days: the cron task cancels orders still awaiting their deposit with no payment at all, and the stock goes back on sale. 0 disables this cancellation.

## Deposit invoice

**Number prefix** (AC by default) and **Credit note prefix** (AVAC by default) must differ. **Next number (minimum)** lets you continue an existing sequence: the next invoice takes this value if it is higher than the last number issued. **Legal note**: text per language printed at the bottom of each deposit invoice (company name, share capital, registration number, VAT number, payment terms).

## Cron task

Schedule the cron URL shown in the configuration once a day, for example at 6am. It sends balance reminders and cancels expired transfer orders, for all shops. The setup check shows its last run.

## The customer journey

1. At checkout, the customer chooses "Pay a deposit of €X by card" or "by bank transfer". The details show the total, the deposit, the balance and a split bar.
2. After a card payment, the order moves to **Deposit received, balance due**, and the deposit invoice is issued and attached to the email. With a transfer, the order waits until you confirm it.
3. When the order reaches a trigger status, the customer receives the link to the balance page: card payment, bank details and your instructions.
4. Once the balance is paid, the order moves to the final status and the customer receives a confirmation email.

A three-step tracker (Deposit paid, Order ready and balance requested, Fully paid) appears on the confirmation page, in the order details of the customer account and on the balance page. Customers can pay the balance before it is requested from their account.

## Managing deposits in the back office

### Orders > Deposits

Four indicators at the top: balances still due, balances requested, transfers to confirm and deposits collected this month. For each order, the list shows the rate, total, deposit, amount paid, balance due, status and deposit invoice. Tick several orders then **Request the balance** to send the links at once, for example the day a batch is ready for pickup.

### "Deposit and balance" panel on the order page

- **Confirm the deposit**: for a received transfer, enter the amount, method and reference. The payment is recorded and the deposit invoice is issued and sent.
- **Request the balance now** or **Send the payment link again**, and copy of the balance link.
- **Record a balance payment**: transfer, cheque, cash, card in store or on delivery. When the balance reaches zero, the order moves to the final status and the customer is notified.
- **Cancel the deposit invoice (credit note)**: for a cancelled order, issues a numbered credit note. The refund itself is made in Stripe or by transfer.

## Invoicing

The deposit invoice includes the billing address, order reference, rate, one line per VAT rate with net amount, VAT and gross amount, the payment method and the remaining balance. The VAT breakdown is calculated pro rata to the order tax rates, shipping and wrapping included, then frozen when issued. Customers download it from their account, administrators from the list or the order page.

The final PrestaShop invoice is generated when the balance is paid, with a block recalling the deposit invoice. The credit note shows the deposit invoice amounts as negatives and the reference of the cancelled invoice.

## Troubleshooting

### The deposit option does not appear at checkout

Check in this order: a payment method ready (Stripe key or IBAN), the customer group, the minimum amount, eligible categories and 0% rules, and the "Hide the deposit option" setting if the cart contains a non-eligible product.

### A card payment did not create an order

The webhook secret is probably missing or wrong, or the endpoint does not listen to the right events. The payment remains visible in Stripe. Once the webhook is fixed, resend the event from the Stripe dashboard: the order is created.

### The order is in "Payment error"

The amount paid by card does not match the expected deposit, usually because the cart changed during payment. Check the order payments, then confirm the deposit from the order page panel or refund the customer.

### Reminders are not sent

The cron task is not running or the reminder delay is set to 0. The setup check shows the date of its last run.

### The balance was marked as paid although the customer paid nothing

A status marked as paid (Payment accepted, Shipped) was applied to the order: PrestaShop then records the rest as paid. Check the order payments and use the module statuses for the next orders.

## Compatibility

- PrestaShop 8.0 to 9.x, the same ZIP covers both branches.
- Multistore, multi-currency (zero-decimal currencies handled for Stripe) and multilingual.
- ModuleAdminController architecture, Stripe API called directly, no Composer dependency.
- Interface, emails and PDFs in French, English, Spanish, German, Italian, Dutch, Polish and Portuguese.