Refund integration: how to sign off on partial refunds in an online store
A manager approved compensation for one item and clicked ‘Refund’, but received a connection error instead of confirmation. Is it safe to click again? These are precisely the questions that the refund integration you commission for your online store should answer. Acceptance depends not on having a button, but on evidence: the approved amount was refunded, a retry did not create an extra refund, and any discrepancy is visible to the finance team.
Start with the payment operation after the product return has been approved. Record its amount, its link to the original payment, the retry rules and the reconciliation method. This will distinguish a working integration from a demonstration where everything happened to work on the first attempt.
Where the payment integration’s responsibility begins
Responsibility begins once the business has determined whom to refund, for what and how much. Handling the request and executing the financial transaction should be linked but separate processes. An approved request does not yet prove that the payment provider has executed the refund.
If you are only setting up the process for receiving returned goods, you first need a returns portal with RMA requests and decisions. Here we cover the next step: turning an approved decision into a controlled financial action. In the specification, identify the source of the approved amount and the condition that must be met before it can be sent to the provider.
Instead of a single ‘Refunded’ status, distinguish approval, command submission, an uncertain outcome and confirmed execution. This is a recommended internal model, not API status names. Define the permitted next action for each state.
How much the system is allowed to refund
The system should refund the approved amount within the remaining balance of the specific payment. Checking only the original order value is insufficient: some funds may already have been refunded or reserved for another unfinished operation. In the requirements, distinguish amounts actually refunded from amounts whose outcome is still being established.
For a store owner, controlling the available refund amount means a simple rule: two employees cannot use the same remaining balance simultaneously. Ask the contractor to demonstrate how the system checks the limit and reserves the required amount in one coordinated step, rather than through two independent checks. The procedure for releasing that reservation after a provider rejection must also be defined.
How to calculate part of an item, discounts and delivery
The partial refund amount should come from an agreed calculation, not the product’s current catalogue price. Before development, define how the order discount, number of units and delivery are taken into account. The contractor implements these rules but should not independently choose the store’s financial policy.
Prepare examples involving kopiykas and the remaining balance after several partial refunds. Agree on calculation precision and where rounding occurs, and pass an already determined amount in the payment command. If the purchase was paid through several payments, an explicit allocation between them is required; the order number alone does not explain which payment to reduce.
What to check in your provider’s capabilities
Check support for partial refunds, the source of funds and the method of obtaining the outcome for your particular connection. The payment service’s name does not describe all its terms. Clarify these dependencies before approving the estimate; otherwise, a finished button may still be waiting for additional configuration.
For example, the official LiqPay refund documentation describes full and partial refunds to the card the customer used to pay. It also distinguishes funding from future payments and from the company’s PrivatBank account; the latter option is enabled by agreement when the contract is concluded. Successfully submitting a command should therefore not become an unconditional promise that the money will arrive instantly.
In LiqPay, the request contains the refund action, the amount and the purchase identifier order_id. The availability of a universal duplicate-prevention key needs to be confirmed, not assumed by analogy with another API.
- Is the required scenario available for your store and payment method?
- Which fields unambiguously link the refund to the original payment?
- What does the response to the request mean, and what confirms the final outcome?
- How can the outcome be checked if neither the response nor the server notification arrives?
- Which funding and fee terms need separate clarification with the provider?
How to keep a retry from becoming a second refund
Every approved financial action must have a stable internal identifier. Clicking again, redelivering a task and recovering after a failure must refer to the same operation. This is the basis of refund idempotency: processing a retry does not create a new monetary effect for a decision already executed.
The order number alone is not enough: a single purchase can have several legitimate partial refunds. But a new random number for every attempt will not work either—the system would lose the link between the retry and the original action. Specify the relationship between the amount decision, the internal operation, the original payment, submission attempts and provider confirmations.
What to do after a timeout
After a timeout, first establish the outcome rather than creating a new refund. A timeout means the store did not receive a response in time; it does not prove that the payment system rejected the operation. You therefore need a visible ‘outcome being checked’ state and a verification procedure for the responsible employee or a background task.
If the provider supports an idempotency key, retry the request according to its documented rules. Such a key does not automatically protect against a second operation someone creates separately in the provider dashboard. A request retry is not a new decision—this rule must apply both in the software and in the team’s actions. For uncertain cases, provide for stopping automatic retries and handing the operation over for reconciliation.
Hypothetical example: two approvals against one payment
In the demo, test several partial amounts, not just a full cancellation. The following is an invented test example, not a GL.ua case study: it distinguishes retrying an action from a new approval.
The store received a payment of 3 780 UAH. The finance team has already confirmed a refund of 640 UAH and then approved another 915 UAH for a different item. The second request timed out. Until the outcome is established, the system must retain that specific 915 UAH operation and prevent anyone from bypassing it by creating a new record on the same grounds.
Once execution is confirmed, the total refunded is 1 555 UAH and the remaining payment balance is 2 225 UAH. If another notification arrives about the same 915 UAH, the recorded amount must not increase. If the business later approves a separate 500 UAH, that is a new operation with its own grounds, not a retry of the previous one. This gives the finance specialist the history, not just the latest status.
| Demo scenario | Expected response | Acceptance evidence |
|---|---|---|
| Clicking again for 915 UAH | The existing operation opens | No second completed refund on the same grounds |
| Response lost after submission | Outcome is checked without a new decision | Amount, payment and attempt log retained |
| Repeated execution notification | The known record is updated | The total remains 1 555 UAH |
| New approval for 500 UAH | A separate operation is created after checking the balance | New grounds and a link to the same payment exist |
| Manual refund in the provider dashboard | The discrepancy is sent for reconciliation | The team sees the external action rather than concealing it with a retry |
How the finance team verifies completion
Completion is confirmed by matching the approved amount, the provider’s data and the record in the accounting system. A green label in the store does not replace this check. Reconciling refunds with the provider is necessary both for automatic operations and for actions performed outside the website.
Agree on a register containing the internal number, original payment, approved and confirmed amounts, currency, time of the last check, source of confirmation and person responsible for any discrepancy. Do not substitute the store’s net payout after fees for the refund amount. These are different measures; the finance team agrees on how fees are recorded under the service terms.
Provider notifications should be verified before use. The LiqPay Callback documentation provides for signature verification and the option of retrieving the current payment status separately. For acceptance, also require verification that the notification belongs to your store and the relevant payment. An authentic notification about another payment must not close the current refund.
Require a list of unconfirmed operations and discrepancies: the same daily total can conceal an incorrect customer association. Agree on reconciliation frequency and response times with the finance team, and show overdue items and the responsible person in the system.
What acceptance requirements to include in the contractor agreement
Include reproducible tests, an accessible register and a failure recovery procedure in acceptance. The demonstration should end with verification of the data in the store and at the provider. Integration acceptance criteria should be agreed before development so that eliminating the risk of duplicate operations does not become unexpected additional scope.
- Perform a standard partial refund and check the amount, payment and final state.
- Repeat the action from two workstations and verify that no extra financial effect occurs.
- Simulate a lost response, a repeated server notification and a restart of the task processor.
- Test rejection, an uncertain outcome and recovery after the accounting system becomes unavailable.
- Reconcile the partial refund history, available balance and an external manual operation.
- Give the finance specialist a test discrepancy: they should find its cause and understand the next step without a developer’s help.
For testing, use the provider’s available test environment, and check what it cannot reproduce through controlled failure simulation. Do not present a simulated response as an actual movement of money. Separately agree on verification of the live connection, who is responsible and the permitted procedure.
Timelines depend on access to the payment dashboard, agreement on amount calculation rules, accounting readiness and the ability to reproduce exceptions. Cost comprises analysis, a refund handler, duplicate prevention, logging, reconciliation, testing and support. If there are few operations, controlled manual execution with reconciliation may be a more sensible starting point than full automation.
Readiness means that an uncertain outcome has an owner, and every confirmed amount has clear grounds. To estimate this enhancement, discuss payment scenarios with GL.ua (Глянець) as part of online store development and improvement: which refunds to automate, what to keep under the finance specialist’s control and which tests will confirm the result.
Frequently asked questions
Do we need to change the store platform for refunds?
Not necessarily. First check the capabilities of the existing payment module and how transaction history is stored. Consider migration only after confirming a specific limitation, not simply because automation is needed.
Can another payment provider be added later?
This capability should be included separately in the scope of work. The shared register can remain, but each provider’s commands, statuses and confirmations will need their own mapping and tests.
What about payment with a gift certificate?
Do not automatically equate it with a card payment. The business must define a separate scenario for restoring the balance or providing other compensation, and the contractor must check how it combines with the monetary part of the purchase.
Does a payment refund replace accounting documents?
A successful payment operation does not in itself confirm completion of all accounting procedures. Your finance team and relevant specialists determine the required documents and actions; their automation is agreed separately.
What should we require when handing the integration over to support?
Ask for a description of states, settings, notifications and discrepancy-handling procedures, along with test scenarios and a list of responsible people. Transfer access to live keys using an agreed secure method, not in instructions or an error log.
Just one step to your perfect website



