Refund API

Overview

A refund API lets authorized software request, inspect, and track the return of funds for a previously completed payment. Refund API initiates or inspects return of funds against an eligible payment; a successful request may still precede processing, provider completion, and ledger reconciliation. Approval thresholds, destination controls, status mapping, customer communication, taxes, and ledger entries must correctly reflect actual settlement through durable records rather than request submission. Card, bank, custodial crypto, and on-chain refunds can have very different settlement and reversibility rules. For Refund API, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state.

Clients should authenticate strongly, verify refund eligibility and remaining amount, require idempotency, record an internal refund intent, and reconcile uncertain outcomes before retry. The API may support full or partial refunds, multiple refunds against one payment, destination selection, status retrieval, fees, and references. Refund creation moves value and may not be safely repeatable. A timeout after acceptance can cause duplicate return attempts. Original payment amounts, fees, exchange rates, and blockchain destinations may not map cleanly to the customer’s expected result. Changes to Refund API should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions. Testing Refund API should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

The Refund API owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

Data handled by Refund API should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.