Handling Stripe Processing Fee Recovered From Customer Creates Unallocated Advance Amount

Rahul2690 · May 21, 2026, 6:19am

ERPNext v15 – Handling Stripe Processing Fee Recovered From Customer Creates Unallocated Advance Amount

ERPNext Version

ERPNext: v15.61.1
Frappe Framework: v15.68.1

Problem Summary

We are integrating Stripe Card payments with ERPNext Payment Entry flow.

Our business model recovers Stripe processing fees directly from the customer during checkout.

Example:

Description	Amount
Sales Invoice Amount	$100
Stripe Processing Fee	$3
Total Customer Paid	$103

The issue is:

ERPNext treats the extra $3 as an unallocated customer advance/payment credit.

Current Accounting Behavior

Payment Entry Created

Field	Amount
Paid Amount	103
Allocated to Invoice	100
Unallocated Amount	3

ERPNext accounting becomes:

Account	Debit	Credit
Stripe Clearing / Bank	103
Accounts Receivable		100
Customer Advance / Unallocated		3

This leaves a customer advance balance even though:

customer does not actually have a credit balance
the extra amount is only Stripe fee recovery
invoice is fully paid

Why This Is Problematic

This creates multiple accounting/reporting issues:

Customer ledger shows incorrect advance balance
AR aging/reporting becomes confusing
Manual reconciliation required
Additional Journal Entry needed to clear advance
No native surcharge/convenience fee handling in ERPNext
Payment Entry and GL entries become semantically misleading

Attempted Solutions & Problems

1. Creating Journal Entry After Payment Entry

We tried:

Payment Entry = 103
Invoice allocation = 100
Additional JE to remove customer advance

Technically this works.

However:

Payment Entry still shows:

Field	Amount
Paid Amount	103
Allocated	100
Unallocated	3

So the document itself becomes misleading because:

customer does not actually have an advance
extra amount is not a real credit balance
audit trail becomes confusing

2. Using Payment Entry Deductions

We tried using Payment Entry deductions for the Stripe fee.

Problem:

ERPNext deductions are designed for:

bank charges
gateway deductions
withheld amounts

Meaning ERPNext assumes:

“Gateway deducted amount FROM merchant”

But our use case is opposite:

“Customer paid EXTRA amount to cover gateway fee”

This causes:

double imbalance/unallocated amounts
incorrect GL impact
incorrect outstanding handling

Example:

| Customer Paid | 103 |
| Invoice | 100 |
| Deduction | 3 |

This resulted in unexpected additional unallocated behavior.

3. Using Negative Deduction

We also tried negative deduction values.

Problem:

ERPNext credits the expense account.

Example:

Account	Effect
Stripe Expense Account	CREDIT

This becomes semantically/accounting-wise incorrect because:

expense accounts should not be credited for customer surcharge recovery
financial reports become misleading

Potential Alternative Solution

The only fully clean accounting approach we found is:

Add Stripe Fee As Invoice Item

Example invoice:

Item	Amount
Product/Service	100
Stripe Processing Fee	3
Total Invoice	103

Then:

Stripe Charge = 103
Payment Entry = 103
Invoice = 103
Outstanding = 0
No advance
No deductions
No cleanup JE
Clean GL and AR

Additional ERPNext Limitation

However, another issue is:

ERPNext does not allow modifying submitted Sales Invoices.

Meaning after invoice submission:

item rows cannot be added/removed normally
totals cannot be adjusted safely
dynamically adding Stripe surcharge later becomes difficult

In many real-world cases:

customer selects payment method only during checkout
surcharge amount is known only at payment time
invoice is already submitted before payment

So dynamically appending:
“Stripe Processing Fee” item
after submit is not straightforward or recommended.

Root ERPNext Limitation

ERPNext Payment Entry fundamentally assumes:

Paid Amount == Amount Applied To Receivable

But surcharge/convenience fee scenarios require:

Customer Paid Amount > Invoice Amount

There is currently no native concept for:

surcharge
convenience fee
gateway fee recovery
pass-through processing fee

Expected / Desired ERPNext Feature

ERPNext should ideally support native surcharge/convenience fee handling.

Example desired behavior:

Component	Amount
Invoice Amount	100
Gateway Fee Charged To Customer	3
Total Customer Paid	103

Accounting:

Account	Debit	Credit
Stripe Clearing	103
Accounts Receivable		100
Fee Recovery Account		3

without creating:

unallocated payment
customer advance
misleading deductions
manual reconciliation cleanup

Questions To Community

What is the recommended ERPNext accounting approach for Stripe surcharge recovery?
How are other ERPNext users handling convenience fees/payment gateway fee recovery?
Is there any native ERPNext feature available for this use case?
Has anyone implemented a cleaner solution in ERPNext v15?
Would it make sense to introduce:
- surcharge field in Payment Entry?
- gateway fee recovery support?
- convenience fee allocation logic?
- payment method based surcharge support?

Additional Notes

This issue is common with:

Stripe card surcharge
ACH fee recovery
Convenience fees
Credit card processing fees passed to customers

Would appreciate suggestions from the ERPNext/Frappe accounting community regarding the cleanest accounting design for this scenario.

asieftejani · May 21, 2026, 12:13pm

Hi @Rahul2690

I did it natively without strip integration. Allocated 100 to the customer and put +3 under the taxes and charges and this was my result which is what I think you are expecting: -

So probably the problem with the API mapping to payments/charges

If you have access to the github code for the integration app you (or a developer) can investigate it further

Hope it helps

Rahul2690 · May 21, 2026, 12:25pm

I noticed that in the payment entry, you listed the paid amount as 100, which is the sales invoice amount. However, the customer actually paid 103, making the payment entry incorrect. then how you show that the customer paid 103 how you add this in the tex and charges want to kwon more about how you handle this stripe fee amount

volkswagner · May 21, 2026, 12:45pm

I agree with @Rahul2690

We’ve created a custom app to handle Stripe automation. Take a look here at the stripe-plus branch as it’s dedicated to just the stripe enhancements. GitHub - volkswagner/erpusa at stripe-plus · GitHub

We suggest using a Stripe Holding account as a bank account for clearing the payments.

In my opinion, your Sales Invoice should add the Sales Taxes and Charges table for the fee you are collecting. Use your Merchant Fees account as the account head for this “tax/charge”. Total invoice with charges will be 103, customer pays 103. When Stripe sends your funds, they will deduct 3, sending you 100. Your payment entry will be for 103 towards the invoice. Your payout from stripe will be 103 credit to Stripe holding account, 100 debit to your bank account, 3 debit to your merchant fee account. If your fees are always 1:1, at the end of the period, your merchant fee expense will be zero. If you collected more than you paid it will have a credit balance, and if you paid more than you collected it will be a debit balance.

If you are uncomfortable crediting an expense account, you can set up your merchant fee account as a payable/liability and use period closing/correcting entries to move the balance to an expense or misc income account depending if it’s debit/credit balance.

I am curious how you are handling the customer paying the fees. Can you provide details on how the customer is notified of this fee? Are you simply adding 3% credit card fee to the invoice, or are you using the API to pull the exact fee amount from stripe?

Rahul2690 · May 21, 2026, 12:57pm

In our case, we provide two payment options: Stripe Card Payment and ACH Auto Debit (Bank Transfer). Because of this, we do not know which payment method the customer will select at the time the Sales Invoice is created.

For card payments, the Stripe processing fee is calculated and added dynamically at checkout after the customer selects the card payment option, as shown in the screenshots.

We have already clearly informed customers about the additional card processing fee in:

the Sales Invoice notification email,
the Sales Invoice,
and the service contract / quotation.

Customers are informed that if they choose card payment, they will need to pay the additional Stripe card processing fee.

volkswagner · May 21, 2026, 1:44pm

I’m curious if starting with a sales order, requesting payment from the sales order will help manage fees against the Sales Invoice (no need to correct a submitted invoice).