Rückerstattungen

Einen Einzug ganz oder teilweise zurückgeben.

Eine Rückerstattung anlegen

POST /v1/refunds

Feld	Pflicht	Beschreibung
payment_id	ja	Der ursprüngliche Einzug: seine Kennung oder seine Referenz
amount_minor	—	Zeichenkette, in kleinsten Einheiten. Fehlt = der Restbetrag
reason	—	customer_request, duplicate, fraudulent oder other
description	—	Freitext, im Dashboard sichtbar

Die Rückerstattung ist eine vollwertige Operation: eigene id, eigener Status, eigenes Webhook-Ereignis (refund.success / refund.failed).

Regeln

• Nur ein erfolgreicher Einzug lässt sich erstatten.
• Die Summe der Rückerstattungen darf den eingezogenen Betrag nicht überschreiten — darüber antwortet die API 422 refund_exceeds_refundable.
• Einzugsgebühren werden nicht zurückgegeben: sie bleiben bei Ihnen.
• Eine Teilerstattung lässt den ursprünglichen Einzug einsehbar, mit vollständiger Historie.
• Die Mittel werden zum Zeitpunkt des Aufrufs Ihrem verfügbaren Guthaben entnommen, wie bei einer Auszahlung.

Ein Idempotenzschlüssel je Rückerstattung. Nie die Kennung der ursprünglichen Zahlung: ein Einzug kann in mehreren Schritten erstattet werden, und ein Schlüssel mit der Kennung des übergeordneten Objekts ließe die zweite Teilerstattung wie eine Wiederholung der ersten aussehen.

Lesen und auflisten

GET /v1/refunds/{id}
GET /v1/refunds                     — Liste; ?payment_id= für einen einzelnen Einzug
GET /v1/payments/{id}/refunds        — die Erstattungen eines Einzugs

GET /v1/payments/{id}/refunds und GET /v1/refunds?payment_id= liefern dasselbe Objekt wie die Liste, mit derselben Paginierung. Der Einzug wird über seine Kennung oder seine Referenz benannt; der eines anderen Kontos antwortet 404 auf der Unterressource und eine leere Liste beim Filter.

Ablehnungscodes

Eine abgelehnte Erstattung antwortet 422, in der üblichen Fehlerhülle:

Code	Bedeutung
refund_exceeds_refundable	Der Betrag übersteigt den noch erstattbaren Betrag. Der Fehler enthält amount_refundable_minor.
wave_partial_refund_window_closed	Wave-Einzug: die Frist für Teilerstattungen ist abgelaufen; nur noch eine vollständige Erstattung ist möglich, sofern nichts erstattet wurde.
wave_partial_refunds_disabled	Wave-Teilerstattungen sind nicht freigeschaltet; eine vollständige Erstattung bleibt möglich.
wave_refund_window_closed	Wave-Einzug bereits teilweise erstattet, Frist abgelaufen: keine weitere Erstattung.
payer_not_found	Wave nennt den Zahler nicht: eine Teilerstattung, die an den Zahler geht, kann nicht ausgeführt werden.
insufficient_funds	Ihr verfügbares Guthaben deckt die Erstattung nicht.

Wave: Teilerstattungen

Wave erstattet eine Transaktion nur vollständig. Eine Teilerstattung eines Wave-Einzugs wird daher an die Wave-Nummer des Zahlers gezahlt, und nur innerhalb der Frist, die partial_refund_deadline am Einzug angibt. Danach ist nur noch eine vollständige Erstattung möglich, und nur, wenn nichts erstattet wurde.