Refund API

Overview

Meaning and scope

A refund API lets authorized software request, inspect, and track the return of funds for a previously completed payment. Refund API must define the resource or operation, HTTP method or invocation, path, authentication and authorization, request fields, response schema, errors, idempotency behavior, limits, and version.

Mechanism and operation

Refund API initiates or inspects return of funds against an eligible payment; a successful request may still precede processing, provider completion, and ledger reconciliation. 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.

Practical payment example

A merchant submits a refund request referencing the original payment. The service tracks authorization, transfer initiation and confirmed settlement as different states so support never treats request acceptance as delivery.

Operational checks

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.

Distinctions and limits

Approval thresholds, destination controls, status mapping, customer communication, taxes, and ledger entries must correctly reflect actual settlement through durable records rather than request submission. Testing Refund API should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

Related reading

Related definitions: partial refunds, Refund.