API, webhooks and backend Published undefined 9 min read

Full and partial refunds after online payment: safe architecture

A refund is a controlled financial event, not a note manually added to an order.

Full and partial refunds after online payment: safe architecture

Article focus

Full and partial refunds after online payment: safe architectureAPI, webhooks and backendpayment webhooksidempotency key paymentsserver-side payment verification

Make refunds a controlled payment operation

A refund requires authorization, reference to the original payment and a verifiable outcome.

Refund command lifecycle
Permission check -> original payment validation -> refund command -> provider verification -> business update.

Do not treat a refund as a free-text order status. The system should validate the original confirmed payment, the refundable balance, the actor permission and the requested amount before sending a controlled provider command.

Record the refund as a new payment event linked to the original transaction. This keeps customer support, accounting and later dispute handling traceable.

  • Validate original payment and remaining balance.
  • Require explicit authorization.
  • Store a provider refund reference and audit trail.

Partial refunds need their own model

Several valid partial refunds must never exceed the original confirmed amount.

Partial-refund ledger
Original amount, completed refunds, pending refund attempts and remaining refundable balance.

Track every partial refund independently, including amount, currency, status and provider reference. Calculate the remaining refundable balance from completed and pending events rather than relying on a manually edited order total.

Apply idempotency to the refund command. A retry after a timeout should return the original refund result instead of sending another request for the same amount.

  • Keep a refund ledger.
  • Prevent exceeding the paid amount.
  • Use idempotency for refund retries.

Update operations only after verification

CRM, ERP and fiscal workflows must receive a verified refund event.

Verified refund handoff
Provider result -> normalized refund state -> CRM/ERP, fiscal and support actions.

Update customer-facing and operational systems after the provider result is verified. A requested refund, a pending refund and a completed refund are distinct states that need different communication and accounting treatment.

Fiscal and legal consequences of refunds depend on the merchant and current rules. Validate the required process against current regulatory and provider guidance before implementation or publication of a merchant-specific procedure.

  • Normalize requested, pending and completed states.
  • Keep fiscal actions separate and auditable.
  • Record manual exception handling.

FAQ

Can a refund be started directly from CRM?

It can be initiated through CRM only when the payment service enforces authorization, validation and a controlled provider command.

Why are partial refunds more complex?

The system must track each refund and prevent the cumulative amount from exceeding the original payment.

Is an audit log needed for refunds?

Yes. Refunds are financial events and should record the actor, reason, original payment and verified result.