Provide a new "Add payment" form

Created on 26 July 2025, 6 days ago

The current "Add payment" form approach reverses a normal merchant's logic. Where a merchant might say, "I'd like to charge $25 to this card," our form currently asks, "What card would you like to charge? How much? Ok, a full charge or just an authorization?"

We should fix the logic and also provide more helpful information on the form, such as the order items and the effect of any previous payments, including a textual representation of the current order balance (instead of just defaulting the current balance in the payment amount field).

This is an in-browser mock-up of the new approach:

Note that it shows the actual order items and also includes in the order totals area a line showing how much has already been paid and what the remaining balance is. We do need to ensure this is backwards compatible, so we should:

  1. Define a new controller for this new form approach.
  2. Default Drupal Commerce to using this new controller.
  3. Look for a setting variable that if set edits the route to use the old controller. Perhaps something as simple as a setting called use_two_step_add_payment_form.
  4. Mark the old controller as deprecated so it can be deleted in 4.x.
  5. Embed the order items table atop the form, along with the order total summary.
  6. Add lines to the summary for the total paid and outstanding balance.
  7. Put the payment details inside a fieldset to visually match the order comments form on the view page.
  8. Float the currency selector if present. This isn't a strict requirement, because it can be a pain in the neck to get the vertical alignment right in the abstract. But this would be nicer than vertical stacking.
  9. Note the changed label, from "Payment option" to "Payment method."
  10. If the merchant is reusing a payment method, no problem, we process payment on submit.
  11. If the merchant is entering a new payment method, update the form to include the necessary elements.
  12. Create the payment method on submit and charge the payment as before.

I'll make a separate ticket specific to supporting a return from an offsite payment solution. The scope of this ticket is primarily to make the form ready for that while also providing a much nicer UX to merchants.

Feature request
Status

Active

Version

3.0

Component

Payment

Created by

🇺🇸United States rszrama

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

Production build 0.71.5 2024