Design a transparent surcharge experience
Show an eligible surcharge before the customer confirms, and keep payment-method changes synchronized with the total.
Start with an approved program
A visual fee line is not authorization to surcharge. Confirm the merchant, location, payment channel, card eligibility, disclosure requirements, and permitted fee with the processor and the appropriate program review before implementation. NMI prohibits surcharges on debit and prepaid transactions. Do not treat a credit classification alone as sufficient program approval. This is an interface toolkit, not a jurisdiction-by-jurisdiction rulebook. It does not prescribe a production rate or claim that one rate applies everywhere.
Keep the price breakdown visible
This original example shows where the eligible fee and final total belong, without prescribing a rate. Use the program-approved amount, label, and disclosure in production. Keep the fee visible before the customer confirms payment. surcharge
Respond to the selected payment method
NMI Payment Component exposes card-category information through lookupData.card.category when available. Its implementation guidance treats debit and unknown classifications as no surcharge, recalculates when the card or amount changes, and discloses the fee before confirmation. Situation Recommended UI response Eligibility confirmed under approved program Show the fee separately and update total and button amount together. Debit or prepaid card Remove the surcharge and restore the applicable non-surcharged total. Unknown, unavailable, or incomplete classification Do not assume eligibility; display no surcharge. Customer changes card or order Invalidate the earlier calculation and refresh the displayed breakdown.
Keep calculation and confirmation aligned
Recommended application design: use one authoritative order calculation to populate the summary, confirmation label, and final transaction request. Do not trust a browser-submitted amount as the only pricing check. Resolve the current merchant program and order amount. Check the applicable payment-method eligibility signal. Calculate the permitted fee using the chosen integration and approved policy. Display the breakdown before confirmation and preserve it with the payment attempt. Revalidate the request on your backend and reconcile the result with the order. API and SDK surcharge contracts differ. Do not copy a field or client-side pattern from another payment API without checking the specific integration.
Test changes, not just the happy path
These are recommended acceptance tests for your interface. Switch from eligible credit to debit and verify that no stale fee remains. Clear the payment input and verify the total no longer assumes a known card category. Change the order value after card entry and verify that the fee and payment label agree. Reload a pending order and reconcile its previous payment attempt before accepting another charge. Verify that receipt and order records match the final charged amount. Payment Component implementation Payment operations and recovery