Partial Payments

The Partial Payments app lets you collect a deposit when a customer places an order and then receive the remaining balance on a schedule you control. Customers pay a percentage or fixed-amount deposit at checkout and return to their account to pay each installment when it comes due. Automated emails handle the reminders so you do not need to chase customers manually.

This app is ideal for stores selling high-ticket items, custom-made goods, services booked in advance, training courses, or any product where spreading the cost makes the purchase more accessible.

Requirements

• PHP 8.3.0 +
• Joomla! 6.x
• J2Commerce 6.x
• Joomla email (SMTP or PHP mail) configured so reminder emails can send

Purchase and Download

Step 1: Go to the J2Commerce website -> Apps

Step 2: Locate Partial Payments -> click View Details -> Add to Cart -> Checkout

Step 3: Go to your My Downloads section under your profile button at the top right corner and search for the app. Click Available Versions -> View Files -> Download Now to save the ZIP file to your computer.

Install the App

In the Joomla Administrator, go to System -> Install -> Extensions.

Upload the plugin app_partialpayment.zip file or use the Install from URL option.

Enable the App

The plugin installs and enables itself automatically. No separate enable step is needed. However, it's important to know where to go to enable or disable it in the future .

There are two ways to reach the Apps list.

Option A: Go to the J2Commerce icon at the top right corner -> Apps

Option B: Go to Components on the left sidebar -> J2Commerce -> Apps

To help you narrow down the list, you can do a search for Partial Payments, click the X, and it will turn into a green checkmark. It is now enabled and ready for setup.

Configure the App

Click the Partial Payments title (next to the green checkmark) to open the settings screen.

The settings are split across six tabs: General Settings, Checkout, Schedule Settings, Escalation Settings, Mail Settings, and Automatic Charge (Saved Card).

General Settings tab

Cron URL: A read-only URL you copy into your server cron or the Joomla Scheduler. Run it at least once a day so scheduled installments activate on time and reminder emails go out. See Cron Setup below.

Framework: Choose Bootstrap 5 for standard Joomla templates or UIkit for UIkit 3-based templates. This controls how the front-end payment selector and cart display look.

Enable Partial Payment (Default): The storewide default. You can override it on each product.

• Disabled — partial payment is off unless a product overrides this to turn it on
• Enabled (Required) — every buyer must pay a deposit; full payment is not offered
• Enabled (Optional) — the customer chooses between paying in full or paying a deposit

Pre-Selected Payment Option: When partial payment is optional, this is the choice pre-selected on the product page. The customer can still switch before adding to cart.

• Full Payment — full payment is ticked first
• Partial Payment — the deposit option is ticked first

Partial Payment Type (Default): How the deposit amount is calculated.

• Percentage — a percentage of the product price (e.g. 30 means 30%)
• Fixed Amount — a fixed amount in your store currency

Default Amount: The deposit value when using the storewide default. Enter 30 for 30% when the type is Percentage, or 50 for a $50 fixed deposit.

Default Payment Plans: One or more saved payment plans offered across all products that use the storewide defaults. Create plans first in Creating Payment Plans.

Scheduled Order Status: The order status assigned to future installments after the deposit is paid. Defaults to Scheduled, which is created for you at install.

Installment Paid Status: The order status that marks an installment as paid. Defaults to Processed.

Tax Allocation: How order tax is split between the deposit and the installment payments.

• Proportional — each payment carries its proportional share of the total tax (default)
• Upfront (With Deposit) — the full tax is collected with the deposit; installments are tax-free

Vendor Commission Split: For marketplace setups, how vendor commissions are distributed across payments.

• Proportional — each installment carries its share of the commission (recommended)
• Upfront (First Installment) — the entire commission is deducted from the deposit only

Coupon Scope: How a coupon discount is applied when partial payment is active.

• Full Order (Proportional) — the discount is spread across all payments proportionally (default)
• Deposit Only — the entire discount reduces the deposit; installments stay at full price
• Each Installment — the discount is re-applied independently to every installment

Debug: Logs partial payment events to the J2Commerce log for troubleshooting. Leave No on a live store.

Checkout tab

Allowed Payment Methods: Restrict deposit payments to specific gateways. Leave empty to allow all active payment methods. Only gateways selected here appear for partial payment orders at checkout.

Show Billing Address: Show the billing address step when a customer pays an installment (the Pay Now flow). Disable this if billing was already collected with the original deposit order and does not need re-entry.

Show Shipping Address: Show the shipping address step when a customer pays an installment. Disable if shipping details were already captured with the original order.

Payment Display: What total the customer sees in the checkout sidecart.

• Full Order Total — the complete order price is shown even though only the deposit is charged today (default)
• Partial Amount Only — only the deposit amount due today is shown

Show Coupon & Voucher Fields at Checkout: When enabled, coupon and voucher entry fields are shown in the sidecart during installment checkout. Disable to hide them when the customer is paying a later installment.

Show Order Details at Checkout: When enabled, a summary of the original order items appears below the totals in the sidecart during installment checkout.

Schedule Settings tab

Maximum Installment Horizon (Days): The longest a payment plan may run, measured in days from the deposit date. Set 0 to remove the limit. The default is 365. This prevents a plan from scheduling a payment far into the future accidentally.

Escalation Settings tab

These settings control what happens when a customer misses an installment due date.

Escalate After (Days): How many days past the due date before escalation triggers. Set 0 to turn escalation off entirely.

Escalation Action: What happens when an installment escalates.

• No Action — record the event but take no automated step
• Notify Admin by Email — send an alert to the escalation email address
• Cancel This Installment — void the overdue installment only
• Cancel All Remaining Installments — void all outstanding installments for the order

Escalation Admin Email: The address that receives the notification when the action is Notify Admin by Email. Leave empty to use the site's global administrator email.

Mail Settings tab

Send Email When Order Is Ready for Payment: Emails the customer when a scheduled installment becomes due. Default Yes.

Notify Payment Pending on (Days): Comma-separated day counts after the due date on which to send overdue reminders. For example, entering 2,5 sends one reminder 2 days after the due date and another at 5 days. Leave empty to disable overdue reminders.

Send Thank-You Email for Deposit Payment: Emails a confirmation the moment the deposit is received. Default Yes.

Push Email Templates (Editor): Seeds the built-in HTML email bodies into the J2Commerce Email Templates manager in standard editor format. Run this once after installation or after resetting defaults. Existing rows are updated, not duplicated.

Push Email Templates (Visual Builder): Seeds the same email bodies using the GrapesJS visual builder format. Use this when you want to customize templates with the drag-and-drop visual editor.

Automatic Charge (Saved Card) tab

Enable Automatic Charge: When enabled, the daily cron attempts to charge each installment automatically on its due date using a saved payment method from the customer's account, instead of emailing them to pay manually.

Creating Payment Plans

A payment plan defines how the balance is collected after the deposit — for example "deposit today, then three equal monthly payments." You can assign plans storewide in General Settings or per product.

To manage plans, open the Partial Payments settings in J2Commerce -> Apps, then click the Manage Plans button in the toolbar -> New.

Plan Details tab

Plan Name: A short, customer-facing label (e.g., "3 Monthly Payments"). This appears on the product page and cart.

Plan Description: Optional text shown to the customer when they select the plan.

Then open the Options tab to set display preferences:

Display Style: How the payment option cards appear on the product page.

• Card Display — each option shows as a visual card (default)
• Radio Display — a compact radio-button list

Display Description: Show or hide the plan description text in the product-page payment selector.

Visible at Checkout: When off, this plan is not offered to customers at checkout but remains available for admin assignment. Useful for plans in draft or plans used only on specific products.

Title Display: Controls the label shown in the cart line item.

• Default Title — shows a generic "Payment Plan" label
• Plan Title — shows the actual plan name

Schedule tab

Then open the Schedule tab to build the installment timeline.

1. Click Add Installment to add a row.
2. Enter the Payment amount for that installment. Use a trailing % (e.g. 33.33%) for a percentage of the order total, or a plain number for a fixed amount in your store currency.
3. Set When the payment is charged using an interval after the deposit: Days, Weeks, Months, or Years.
4. Drag rows to reorder them.

The Schedule preview updates as you type and shows whether the total across all rows adds up to 100% (or the full order amount for fixed plans). Click Save when the preview shows the full amount is allocated.

Options tab

Title Display: Controls the title shown for this plan on the product-page payment selector and the cart line item. Default Title shows a generic Payment Plan label; Plan Title shows the name of this plan.

Display Style: Choose how payment options are displayed to customers on the product page.

Display Description: Show the plan description in the product-page payment selector.

Enabling Partial Payment on a Product

Each product can use the storewide defaults or set its own deposit terms. There are three ways to reach a product.

Option A: Go to the J2Commerce icon at the top right corner -> Catalog -> Products

Option B: Go to Components on the left sidebar -> J2Commerce -> Products

Option C: Go to Content -> Categories -> find the category, then open the product

Open the product, click the J2Commerce tab, then the Apps tab, and find the Partial Payment section.

Enable Partial Payment: Set this product's availability.

• Disabled — partial payment is off for this product, even if the storewide default is on
• Enabled (Required) — every buyer must pay a deposit for this product
• Enabled (Optional) — the customer chooses full payment or a deposit

Pre-Selected Payment Option: (appears only when set to Enabled (Optional)) Which option is pre-ticked on the product page — Full Payment or Partial Payment.

Partial Payment Type: (appears when not Disabled) Whether the deposit is a Percentage of the price or a Fixed Amount.

Deposit Amount: (appears when not Disabled) The deposit for this specific product. Overrides the storewide default amount.

Payment Plans: (appears when not Disabled) The plans offered for this product. Overrides the storewide plan list.

How It Works

When a customer reaches a product page or checkout:

1. J2Commerce checks whether Partial Payment is enabled for that product (or uses the storewide setting).
2. If it is optional, the customer sees a Pay in Full / Pay Deposit choice. If it is required, the deposit is applied automatically.
3. At checkout the customer pays only the deposit amount through their chosen payment method. The order total on the order record reflects the full purchase price, while the gateway charges only the deposit due today.
4. The remaining balance is saved as one or more scheduled child orders using your Scheduled Order Status.
5. When an installment's due date arrives, the cron activates it and either emails the customer a Pay Now link or auto-charges a saved card, depending on your settings.
6. The customer pays from the Pay Now link, and a confirmation email is sent for each completed installment.

Customer Experience

Product Detail Page

When partial payment is optional, a toggle appears near the add-to-cart button:

• Pay in Full — proceeds normally at the full price
• Pay Deposit — shows the deposit label, e.g. "Pay a 30% deposit" or "Pay a deposit of $150"

When a payment plan is offered, a plan selector also appears so the customer can choose their preferred installment schedule.

When partial payment is required, the deposit label shows without a toggle and the customer proceeds directly with the deposit.

Cart

Line items using partial payment show a Deposit badge next to the product name. The order totals area adds two extra rows:

• Full Subtotal — the complete price before the deposit arrangement
• Future Payments — the balance still owed after today's deposit

Checkout

If you have set Allowed Payment Methods in the Checkout tab, only those gateways appear. The total shown in the sidecart follows your Payment Display setting — either the full order total or only the deposit due today.

Customer Profile: Pay Now and Schedule

After the deposit order is placed, the customer can view the remaining payment schedule in their account under My Profile -> Orders. When an installment becomes due, a Pay Now alert appears on the order with a direct link to complete the payment. A Payment Schedule view lists all installments, their amounts, and their due dates.

Managing Payment Plans on Orders

Each order paid with a deposit has its own Payment Plan screen. Use it to check what a customer has paid, record a payment received outside the store, change an installment's due date or status, and correct the plan after you edit the order.

Open a Payment Plan

1. Go to J2Commerce -> Sales -> Partial Payments.
2. Open the Installment Orders view from the navigation bar. It lists every deposit order with its customer, order number, order date, progress, order total, remaining balance, next due date and status.
3. Click the customer name to open the plan. The page is titled Edit Payment Plan followed by the order number, and the plan is on the Payment Plan tab.

Plan Summary

The Plan Summary section is read-only, except for the order status. View Order Details opens the original order.

Field	What It Shows
Customer	The customer who placed the order.
Order Total	The full price of the order.
Deposit Paid	The amount charged at checkout, minus any refunds.
Paid to Date	The deposit plus every installment paid so far.
Balance Due	What the customer still owes.
Plan Order Status	The status of the main order. You can change it here.

Installments

Below the summary, each installment has its own section headed Installment with its position in the plan (for example 1 of 3) and its order number. View Order Details in the heading opens that installment's order.

Field	What It Does
Amount Due	The installment amount. Read-only.
Payment	Read-only evidence of payment: No payment recorded, Paid through checkout, Marked paid by an administrator, a transaction ID, or a manually recorded payment.
Order Status	The status of the installment order. A status you change here is noted on the order history.
Due Date	When the installment becomes payable. Edit it to move the due date.

Record a Payment

An installment that can still take a payment shows a Record Payment heading. Use it when a customer pays outside the store, for example by bank transfer.

1. Enter the Amount Received in the order currency, as shown on the page.
2. Enter a Payment Reference, such as Bank transfer 4471. It is required whenever you enter an amount.
3. Leave Payment Date blank to use the current date and time, or pick another.
4. Select Save.

An amount below the installment amount moves the difference onto the next unpaid installment. An amount above it is refused, and so is a partial amount when no later installment can take the difference. Nothing is saved when any value is refused.

Toolbar Buttons

Button	What It Does
Save and Save & Close	In the Save menu. Save keeps you on the plan; Save & Close returns to the list.
Recalculate	Asks for confirmation, then resets installments marked paid with no recorded payment back to Scheduled and rebalances the unpaid installments to the current order total. It also moves refunded amounts back onto the unpaid installments, including refunds made outside the order screen, such as in your payment gateway dashboard. See Refunds on a Payment Plan. A note with the new remaining balance is added to the order history.
Repair Price Basis	Appears only on orders that need it. See Repair Price Basis.
Close	Leaves the plan without saving.
Settings	Opens the app settings.
Help	Opens this page.

Refunds on a Payment Plan

When you refund part of a payment plan order, the amount the customer owes again moves back onto the unpaid installments so you can collect it.

• A refund made from the order screen updates the installments automatically.
• For a refund made elsewhere, such as in your payment gateway dashboard, open the plan and select Recalculate.
• A refund that only returns an overpayment moves nothing.
• A full refund of the deposit is not moved automatically. Select Recalculate on the plan if you want the balance reopened.

Repair Price Basis

Orders placed before the app recorded full line prices cannot update their order total or installments when you edit the order. On these orders the plan shows a Price Basis section and a Repair Price Basis button. Neither appears on newer orders, on cancelled plans, or for users who cannot edit payment plans.

1. Open the plan. The Price Basis section lists each deposit line with its quantity and shows Order total at checkout for reference.
2. For each line, enter the full unit price in your store currency. Leave out options, and use the same tax basis as your product prices. If a line has options, the field notes how much they add per unit; they are counted separately.
3. Select Repair Price Basis and confirm.

On success the page shows the new order total and remaining balance, and the order history records who entered the prices, the old and new order totals, and the new remaining balance. The repair is all or nothing: if the restated order does not match the deposit plus the installments, nothing is changed.

• Every price must be greater than zero. A field that is empty, zero or too large is marked, and your entries stay in the form.
• The repair fails when the unpaid installments cannot absorb the difference. This usually means they are already paid or have a payment in progress.

Cron Setup

The cron does two things: it activates scheduled installments when their due date arrives, and it sends payment-due and overdue reminder emails. Run it at least once a day. Running it more often (every few hours) means customers are notified sooner after a due date passes.

Option A: Joomla Scheduler

If a companion Joomla Task plugin is available for Partial Payments, you can wire the cron into the native System -> Scheduled Tasks area and no server-level cron is needed.

Option B: Server Cron

Copy the Cron URL from the General Settings tab and add it to your server's cron table.

cPanel example:

1. Log in to cPanel and open Cron Jobs.
2. Set the schedule to once daily (for example 0 6 * * * for 6:00 AM daily).
3. In the command field use: curl -s "PASTE_YOUR_CRON_URL_HERE" > /dev/null 2>&1

Email Templates and Merge Tags

The app sends several types of email. Each has a built-in default body, and you can override the subject and body using the Email Templates manager (use the Push Email Templates buttons in the Mail Settings tab to seed the defaults).

Email type	When it sends
Installment Due	When a scheduled installment becomes ready for payment
Overdue Reminder	On each day listed in Notify Payment Pending on (Days) after the due date
Deposit Received	Immediately after a deposit payment is confirmed
Admin Overdue Alert	When an overdue installment escalates with action Notify Admin
Installment Confirmed	After a later installment payment is received
Plan Complete	When the final installment is paid and the plan is finished
Payment Failed	When an automatic charge attempt fails
Schedule Created	When the deposit is placed and the installment schedule is set up

Merge Tags

Use these tags in any custom email subject or body. They are replaced with real values when the email sends. Always include the square brackets exactly as shown.

Merge tag	What it inserts
[CUSTOMER_NAME]	The customer's name or email address
[PARTIAL_PAYMENT_ORDER_ITEM_NAME]	The product name from the order
[INVOICE_URL]	A link to the customer's order invoice
[PAY_NOW_URL]	A direct link the customer uses to pay an outstanding installment
[PARTIAL_PAYMENT_DATE]	The scheduled payment due date
[PARTIAL_PAYMENT_DAYS_PASSED]	Days elapsed since the due date (for overdue reminders)
[PAID_PARTIAL_AMOUNT]	The deposit already paid
[PARTIAL_PAYMENT_FULL_AMOUNT]	The full order total
[BALANCE_PARTIAL_AMOUNT]	The outstanding balance still owed
[INSTALLMENT_INDEX]	This installment's number in the sequence
[INSTALLMENT_TOTAL]	The total number of installments in the plan

Coupon Restrictions

You can control how individual coupons interact with partial payment orders. When editing a coupon in J2Commerce -> Sales -> Coupons, look for the Partial Payment tab.

Coupon Restriction:

• No restriction — the coupon is accepted for any order (default)
• Deposit orders only — the coupon requires at least one partial payment product in the cart; it is rejected for full-payment-only carts
• Full payment orders only — the coupon is rejected when any partial payment product is in the cart

Tips

• Start small — test with one product set to Enabled (Optional) before turning partial payment on storewide.
• Run the cron daily — scheduled installments will not activate and reminders will not send without it.
• Keep plan names short — they appear on the product page and in the cart where space is limited.
• Use Upfront tax if your accounting requires the full tax amount collected at order time rather than spread across installments.
• Match the Framework setting to your active template (Bootstrap 5 or UIkit) so the payment selector looks right on the product page and cart.
• Note on subscription products: Partial Payments is not available for subscription products. If a cart contains a subscription, the partial payment option is automatically hidden.

Troubleshooting

The "Scheduled" order status is missing

Cause: The status was deleted after installation.

Solution: Go to J2Commerce -> Setup -> Order Statuses and add a status named Scheduled (a yellow or warning color is a good visual choice). Then open the Partial Payments settings and select it in Scheduled Order Status.

Reminder emails are not sending

Cause: The cron is not running, Joomla email is not configured, or the email setting is off.

Solution:

1. Open the Cron URL in a browser and look for a success message to confirm it runs.
2. Check Joomla email at System -> Global Configuration -> Server and send a test email.
3. In the Mail Settings tab, confirm Send Email When Order Is Ready for Payment is Yes.
4. Enable Debug in General Settings, run the cron again, then check the J2Commerce log for error messages.

The balance shows in the wrong currency

Cause: The store currency or exchange rate changed after the original deposit order was placed. Existing installment orders keep the currency from the original order.

Solution: For new orders, make sure the currency switcher is set correctly before the customer adds to the cart. Verify the J2Commerce currency plugin is enabled and exchange rates are current.

Customers can still select a restricted payment method

Cause: The gateway restriction is not saved, or the field is empty (which allows all methods).

Solution: Open J2Commerce -> Apps -> Partial Payments -> Checkout tab and confirm only the intended gateways are listed in Allowed Payment Methods (an empty field means all gateways are allowed). Save, then clear the Joomla cache at System -> Clear Cache.

The Pay Now button does not appear

Cause: The installment has not yet been activated by the cron, or the customer is viewing the parent deposit order instead of a child installment order.

Solution:

1. Confirm the installment order's status matches your Scheduled Order Status.
2. Confirm the cron has run at least once since the installment due date passed.
3. Ask the customer to view the individual installment order in their account, not the original parent order.

The partial payment option does not appear on a product

Cause: The product or storewide setting has partial payment set to Disabled, or the app itself is not enabled.

Solution:

1. Go to J2Commerce -> Apps and confirm Partial Payments has a green checkmark.
2. Open the product, go to the J2Commerce tab, then Apps, and check the Enable Partial Payment setting.
3. If the product setting is Disabled, change it to Enabled (Required) or Enabled (Optional) and save.

Automatic charge fails silently

Cause: The payment gateway does not support the auto-charge event, or the customer has no saved card on file.

Solution: Confirm your payment gateway plugin supports saved-card vaulting and the onJ2CommercePartialPaymentChargeInstallment event. If not, set Enable Automatic Charge to No and rely on the Pay Now email flow instead.

Recalculate Says the Order Total Could Not Be Confirmed

After Recalculate you see: "The installment amounts were left unchanged because this order's total could not be confirmed as the full order value." The order was placed before the app recorded full line prices, so the installments were not changed.

1. Open the order's payment plan.
2. Enter the full unit price for each line in the Price Basis section.
3. Select Repair Price Basis. See Repair Price Basis.

If the plan shows no Price Basis section, check the order lines and run Recalculate again.

See Also

• Apps and Extensions — browse all J2Commerce add-ons