Refunds
Record and follow a payment refund operation.
POST /v1/refunds records a refund operation and returns HTTP 202. It requires
refunds:write and an Idempotency-Key. A company member must have an active
second factor in live mode. Secret and restricted keys can call it; agent keys
and agent principals cannot. Product-limited Support can refund only when every
product on the payment is within their grant. Current product-limited members
have no configured product list, so their requests are refused.
{
"payment": "pay_...",
"amount": { "amount": 300, "currency": "usd" },
"access_reduction": "all",
"reason": "requested_by_customer"
}Omit amount to request the full remaining conservative capacity. The amount
must be positive and use the payment currency. reason is optional and accepts
duplicate, fraudulent, or requested_by_customer. Named lines are not
available yet and return 409.
A refund counts as partial when its amount is less than the payment amount minus
settled refunds and confirmed losses. While another refund, held dispute, or
operation hold is still unconfirmed, refunding the available remainder counts as
partial too, including when amount is omitted. Partial refunds require an
explicit access_reduction: "all" to end access or "none" to keep access.
Without that choice, a partial refund returns access_reduction_required (400).
A legacy request with only access: "keep" returns keep_access_needs_full_refund
(400) if it requests less than the available remainder; requesting the whole
remainder while some money is still unconfirmed returns
access_reduction_required instead. When the refund covers the full amount after
settled refunds and confirmed losses, access defaults to "end". If you send
both fields, use access: "end" with access_reduction: "all", or access: "keep"
with access_reduction: "none".
The response has an operation ID, status, createRefund step status, and a
refund summary. mirror: pending and refund.id: null mean that processor
sync has not produced a matching current refund row yet. A current mirror row
uses mirror: current and includes its rfd_ ID. Follow the operation and
refund sync before treating a 202 as a completed refund.
Send Hms-Dry-Run: true with a valid idempotency key for a read-only 200 preview.
The preview reports the proposed amount, remaining capacity, and any existing
operation. It neither claims the key nor creates an operation. A later request
with that key can still execute. A replay of an already recorded operation
returns the original operation even if new refunds are disabled for the tenant.
Refund creation is enabled for every seller, in both live and test mode. A
company and mode that is not enabled receives refunds_not_enabled (409). A
payment must be a succeeded Stripe charge with complete refund evidence and
provable Hermos invoice lineage. Fees, running installment plans, and
schedule-managed subscriptions are refused. Schedule-managed subscriptions are
conservatively refused until payment plan state can be derived. Held disputes
reduce the available amount; there is no refund-window cutoff. Superseded
processor accounts can use the payment's original account. The API does not
currently support fee refunds, named refund lines, agent refunds, or refunds
lacking provable invoice lineage.
See Errors for refusal rules. A 409 does not mean that a refund
was sent to the processor; retry only after resolving its named rule, and
with a new Idempotency-Key. A key is bound to its first outcome, so reusing
it replays the same 409.