Feature request: Installment payment support in the payment plugin structure

[talhakaanozkan]

Hi,

In many markets, customers can split card payments into installments (e.g. 3, 6 or 12 monthly payments). The available options and any additional fees usually depend on the payment provider and the customer's card.

As far as I can see, the current payment plugin structure doesn't have a standard way to support this.

Suggestion

1. Installment options from the provider: A way for payment plugins to return available installment options (number of installments, monthly amount, total amount, any additional fee), for example based on the card number entered.
2. Checkout display: Showing these options on the checkout page so the customer can choose one.
3. Order record: Storing the selected installment count and total amount with the order.
4. Admin panel: Showing installment details on the order page, plus settings to enable/disable installments and set limits (e.g. minimum order amount, maximum number of installments).
5. Product page (optional): Displaying an installment table on the product page.

Questions

• Would you consider adding installment support to the payment plugin structure?
• If it's not planned soon, what would be the recommended way to implement this within the current structure?

Thanks for the great work on GrandNode2!

[KrzysztofPajak]

Hi @talhakaanozkan, thanks, this is a common requirement in markets where card installments are standard, and it fits well with the payment plugin structure.

Most of this can already be built inside a payment plugin:

• Collecting the choice. A payment plugin renders its own payment info form (a view component), and receives the submitted values in ValidatePaymentForm(IDictionary<string, string>) and SavePaymentInfo(...). The form can call an endpoint in the plugin once the card number (BIN) is entered, fetch the installment options from the gateway, and show them for the customer to choose.
• Storing it. SavePaymentInfo returns the PaymentTransaction, which has CustomValues (Dictionary<string, object>) and AdditionalInfo. The selected installment count and amounts can be stored there and passed to the gateway in ProcessPayment.
• Limits and settings. Minimum order amount, maximum installments and enabling/disabling usually differ per gateway, so they fit naturally in the plugin's own settings. Use HidePaymentMethod(cart) or simply hide the installment selector below a threshold.
• Product page table. This works best as a widget in the plugin. Options depend on the card and bank, so it can only be indicative.

Two areas where the current structure falls short:

1. Showing installment details on the order. The order details pages (admin and customer) have a place for custom values, but the payment transaction's CustomValues are not mapped to them today. So a plugin can store the installment choice but cannot show it there without its own views.
2. Installments with interest or a fee. GetAdditionalHandlingFee(cart) only receives the cart, not the payment form, so the payment fee cannot depend on the option the customer selects. Interest-free installments work fine today. For installments that change the order total, the fee would have to be known before the order totals are calculated. Charging it only at the gateway would leave the order total, refunds and invoices out of step with what the customer actually paid. Supporting this properly would need a payment-form-aware fee calculation, ideally added without breaking existing payment plugins.

Recommended approach today: implement installments in the payment plugin as described above. Interest-free installments are fully possible now. Keep in mind that some providers (especially redirection-based and BNPL ones) let the customer pick installments on their own hosted page. For those, the plugin only needs to read back the result.

To be transparent: this is not a priority on our side at the moment, so we don't plan to work on it in the near term. If you'd like to try preparing something, for example a payment plugin for your gateway or a pull request for one of the two gaps above, we'd be happy to review it and help with questions along the way.

If you are building this for a specific gateway, it would also help to know whether it charges interest to the customer or to the merchant, since that decides whether the order total has to change at all.