Enable Refund of Customer Balances to Payment Cards

🔍 Problem Statement

Currently, the platform does not support refunding customer balances directly back to their payment cards.

This limitation requires manual intervention or external processing to return unused balances, which increases operational overhead, delays refunds, and may create confusion or dissatisfaction for customers expecting automatic refunds to their original payment method.

💡 User Story

As a customer support or billing administrator,

I want to be able to refund a customer’s balance directly to their saved or original payment card through the platform,

so that refunds are processed seamlessly, accurately, and without manual handling outside the system

🎯 Definition of Done (DoD)

A feature is considered complete when:

✔ Given a payment whose destination was a customer balance,

→ The “Refund” button appears in the Admin Dashboard as it does for normal payments.

✔ When an admin initiates a refund,

→ The refund amount defaults to the original charge amount.

→ If the customer balance is higher than the charge, only the charge amount is refundable (no over-refunds).

✔ Refunds may be full or partial, but cannot exceed the original charge amount.

✔ Each refund is tied to its originating payment and processed via the original payment method and gateway used for the charge.

✔ The refund event triggers (charge.refunded) containing:

1. Refund amount

2. Customer ID

3. Masked card details

4. Payment and refund transaction IDs

5. Timestamp

✔ Accounting impact matches the current refund mechanism for standard payments.

🧩 Impacted Components

⚙️ Limitations / Notes

1. Applies to payments originally charged and credited to customer balance.

2. Refunds cannot exceed the original charge amount.

3. Refund logic must respect existing refund policies and gateway constraints.

Product Notes

1. Designs/Resources/Links/Wireframes/Mockups

2. Client Users Watchlist

Development Notes

1. Components which the feature touches

2. Details on backend/frontend/API/webhooks/SDK implementation

3. Error handling

4. Logging events

5. Technical doc links which have been updated

6. Breaking changes

7. Usability risks/limitations

8. Impact analysis:

9. (Sample)Added a new JSON key to the object stored in DB, therefor, either a guard in code needs to be added or old lists using Expiry object needs to be adjusted and adding the new JSON key to them.

10. QA steps needed to validate:

11. Check functionality of lists created prior this deployment

QA Notes

1. Planned Test cases: <Testrail link>

2. Initial Test run: <Testrail link>

3. Additional Test run(s): <Testrail link>

Open Questions

1. <Name of concerned member> Question