Hermos API
Concepts

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.