Drei App Store Rückerstattungs-Benachrichtigungen treffen ein, nachdem Apple entschieden hat, und REFUND_REVERSED gibt den Verkauf zurück

Apple entscheidet über deine Rückerstattung, und dann redet es weiter. Sobald das Ergebnis feststeht, sendet der App Store deinem Server eine von drei App Store Rückerstattungs-Benachrichtigungen, und jede verlangt einen anderen Schritt. Ein REFUND besagt, dass das Geld weg ist und du den Zugang entziehen solltest. Ein REFUND_DECLINED besagt, dass der Kunde die Anfrage verloren hat und du den Verkauf behältst. Ein REFUND_REVERSED besagt, dass Apple eine bereits gewährte Rückerstattung rückgängig gemacht hat, also gehört der Verkauf wieder dir und du musst zurückgeben, was auch immer du entzogen hast. Die meisten Apps richten die erste ein und ignorieren die anderen beiden stillschweigend. So landet ein zahlender Kunde ausgesperrt vor etwas, wofür er bezahlt hat.

Diese drei sind getrennt von CONSUMPTION_REQUEST, der einzigen Rückerstattungs-Nachricht, die eine Antwort verlangt. Die Benachrichtigungen nach der Entscheidung wollen keine Diskussion. Sie wollen ein HTTP 200 und die richtige Änderung am Zugang des Kunden. Hier steht, was jede bedeutet, welche genauen Felder die Fakten tragen und wo das Geld verloren geht, wenn du sie falsch behandelst.

Die vier Rückerstattungs-Benachrichtigungen, und welche eine Antwort will

App Store Server Notifications V2 ist ein einziger Feed. Du richtest ihn auf eine URL und Apple sendet jeden Benachrichtigungstyp dorthin, also empfängst du bereits alle vier Rückerstattungs-Nachrichten, ob du sie behandelst oder nicht. Vier der Typen betreffen Rückerstattungen, und nur einer davon ist eine Frage.

Was eine REFUND-Benachrichtigung dir tatsächlich sagt

REFUND wird ausgelöst, wenn der App Store eine Transaktion erfolgreich an einen Kunden erstattet hat. Es gilt für jeden Kauftyp: einen Verbrauchsartikel, einen nicht verbrauchbaren Artikel, ein automatisch verlängerbares Abonnement und ein nicht verlängerbares Abonnement. Die signierte Transaktion in der Benachrichtigung trägt jetzt zwei Felder, die sie vor der Rückerstattung nicht hatte, und diese zwei Felder sind die ganze Geschichte.

revocationDate und revocationReason tragen die Fakten

revocationDate ist die UNIX-Zeit in Millisekunden, zu der der App Store die Transaktion erstattet oder widerrufen hat. revocationReason nennt dir die Kategorie der Rückerstattung und nimmt genau zwei Werte an.

Das Vorhandensein eines revocationDate auf einer Transaktion ist selbst das Signal. Wenn du später eine Transaktion abrufst und sie ein revocationDate hat, wurde dieser Kauf erstattet, mit oder ohne Benachrichtigung. Lies den Grund daneben, damit eine Welle von Rückerstattungen mit Wert 1 bei einer einzigen Veröffentlichung dir nicht als Rauschen entgeht.

Nach Transaktion widerrufen, nicht nach Produkt

Die Falle hier ist, zu viel zu widerrufen. Ein REFUND nennt eine Transaktion. Es sagt dir nicht, jeden Kauf zu deaktivieren, den der Kunde jemals von dieser Produkt-ID getätigt hat. Apples eigene Empfehlung ist zu prüfen, welchen Zugang der Kunde noch hat, bevor du etwas abschaltest, weil sich Berechtigungen überschneiden. Der klassische Fall ist ein Abonnement: Eine Rückerstattung landet auf der Verlängerung des letzten Monats, während die Verlängerung dieses Monats aktiv und voll bezahlt ist. Widerrufe auf Produktebene und du hast gerade einen aktuellen, zahlenden Kunden wegen einer Rückerstattung für einen bereits beendeten Zeitraum ausgesperrt.

REFUND_DECLINED bedeutet, du hast bereits gewonnen, also mach es nicht rückgängig

REFUND_DECLINED trifft ein, wenn der App Store die Rückerstattungsanfrage des Kunden abgelehnt hat. Der Kunde hat gefragt, Apple sagte nein, und du behältst den Verkauf. Oberflächlich gibt es nichts zu tun, und genau das ist der Punkt. Der Fehler, den diese Benachrichtigung aufdeckt, ist ein anderer: den Zugang zu früh zu widerrufen.

Wenn dein Code auf den CONSUMPTION_REQUEST reagiert, indem er den Zugang des Kunden entzieht, bevor Apple entschieden hat, ist ein REFUND_DECLINED der Moment, in dem diese Entscheidung explodiert. Apple hat dein Geld behalten und du hast einen Kunden ausgesperrt, dessen Rückerstattung abgelehnt wurde. Dieser Kunde bezahlt nun für ein Produkt, das er nicht nutzen kann, öffnet ein Support-Ticket und erinnert sich daran. Die Lösung ist eine Regel, kein Feature: widerrufe bei REFUND, niemals bei der Anfrage. REFUND_DECLINED ist einfach Apples Bestätigung, dass ein früher Widerruf die falsche Entscheidung gewesen wäre.

REFUND_REVERSED ist die Benachrichtigung, die dich auszahlt

REFUND_REVERSED ist diejenige, die fast niemand behandelt, und es ist diejenige, die dir Geld zurückbringt. Apple sendet sie, wenn es eine zuvor gewährte Rückerstattung rückgängig macht, typischerweise nachdem der Kunde diese Rückerstattung anficht. Die Widerrufsfelder, die ein REFUND der Transaktion hinzugefügt hat, werden wieder entfernt, sodass der Kauf erneut als bezahlt gilt. Apple formuliert die Aufgabe des Entwicklers in einem Satz: Wenn deine App Inhalte oder Dienste infolge der zugehörigen Rückerstattung widerrufen hat, muss sie diese wiederherstellen. Es gilt für jeden Kauftyp, vom Verbrauchsartikel bis zum automatisch verlängerbaren Abonnement.

Das Wochen-später-Problem

Die eigentliche Frage, die Entwickler in Apples eigenen Foren stellen, ist das Timing. Ein REFUND_REVERSED kann Wochen nach dem ursprünglichen REFUND eintreffen, lange nachdem ein Abonnementzeitraum abgelaufen ist. Stellst du dann den Zugang wieder her? Stelle wieder her, was die Transaktion tatsächlich gewährt, begrenzt auf das, was diese Transaktion abdeckt. Für einen Verbrauchsartikel oder einen nicht verbrauchbaren Artikel schalte die Freischaltung wieder ein. Für einen bereits abgelaufenen Abonnementzeitraum verteilst du keine neue Zeit, du korrigierst den Datensatz, damit die Historie des Kunden korrekt ist und jede noch gültige Berechtigung wieder aktiv wird. Stelle die konkrete Transaktion wieder her, und deine Überschneidungslogik entscheidet, was aktuell aktiv ist.

Wo bei richtiger Handhabung das Geld liegt

Jede dieser Benachrichtigungen entspricht einer echten Zahl, und die Kosten einer falschen Behandlung sind nicht nur der Verkaufspreis.

REFUND: hör auf, für einen erstatteten Kunden zu bezahlen

Der Verkaufspreis ist in dem Moment weg, in dem REFUND eintrifft. Was du noch steuern kannst, sind die Kosten der weiteren Belieferung. Jede Stunde, die eine erstattete Berechtigung aktiv bleibt, gibst du weiter für Dinge aus, für die der Kunde nicht mehr bezahlt: Rechenleistung, Modell-API-Aufrufe, Speicher und jede an seine Nutzung gebundene Auszahlung an Creator oder Partner. Ein zügiger Widerruf bei REFUND stoppt diesen Zähler. Die Benachrichtigung zu ignorieren bedeutet, ein Produkt für jemanden zu finanzieren, den der Store bereits entschädigt hat.

REFUND_DECLINED: verwandle keinen Sieg in eine Rückerstattung aus Kulanz

Wenn du zu früh widerrufst und die Rückerstattung später abgelehnt wird, hast du den Verkauf auf dem Papier behalten und in der Praxis verloren. Der Kunde, der bezahlt hat, kann das Produkt nicht nutzen, also erbst du ein Support-Gespräch und, oft, eine freiwillige Rückerstattung, um es wiedergutzumachen. Das ist doppelt zahlen für einen Verkauf, der nie in Gefahr war. REFUND_DECLINED richtig zu behandeln kostet nichts, und genau deshalb ist es die günstigste Regel, die du übernehmen kannst, den Zugang unberührt zu lassen, bis REFUND kommt.

REFUND_REVERSED: die schlimmste Kombination ist, dass ihr Geld und ihr Zugang beide weg sind

Ignoriere REFUND_REVERSED und du erreichst das schlechteste Ergebnis auf dem Brett. Du bist bezahlt worden, und der Kunde hat nichts. Er hat bereits einmal seine Bank kontaktiert, um die Rückerstattung rückgängig zu machen, und eine Person, die von einem Produkt ausgesperrt ist, für das ihr jetzt Geld berechnet wird, ist eine Person, die die Bank wahrscheinlich ein zweites Mal kontaktiert. Dieser nächste Streit kann zu einem Karten-Chargeback werden, das bankseitig endgültig ist und mehr kostet, als der Verkauf je einbrachte. Den Zugang in dem Moment wiederherzustellen, in dem REFUND_REVERSED eintrifft, ist die günstigste Versicherung im ganzen Rückerstattungsablauf.

Was einzurichten ist

Die Handhabung ist gering, sobald das Modell stimmt. Verknüpfe Berechtigungen mit der Transaktions-ID, sodass jede Benachrichtigung auf einen Kauf zeigt. Bei CONSUMPTION_REQUEST sende deine Daten innerhalb von 12 Stunden. Bei REFUND widerrufe diese Transaktion. Bei REFUND_DECLINED tu nichts. Bei REFUND_REVERSED stelle wieder her. Gib bei allen schnell ein HTTP 200 zurück und nimm die Zugangsänderung zu deiner eigenen Zeit vor.

Für die Lücke, die Benachrichtigungen hinterlassen, nutze den Get Refund History Endpoint. Wenn dein Server während eines Ausfalls offline war und ein REFUND verpasst hat, rufe die Rückerstattungs-Suche der App Store Server API für eine Transaktions-ID unter /inApps/v2/refund/lookup/{transactionId} auf und lies die signierten Transaktionen mit ihrem revocationDate und revocationReason zurück. Es gleicht eine Transaktion nach der anderen ab und blättert durch die erstatteten Käufe eines Kunden, sodass ein verpasster Webhook nicht zu einer dauerhaft falsch gesetzten Berechtigung wird.

Das ist der Teil, den RefundHalt für dich übernimmt. Es lauscht auf alle vier Typen, widerruft bei REFUND, hält den Zugang bei REFUND_DECLINED unberührt und stellt bei REFUND_REVERSED automatisch wieder her, jeweils mit der genauen Transaktion verknüpft. Eine rückgängig gemachte Rückerstattung bleibt nicht in einer Warteschlange hängen, während ein zahlender Kunde ausgesperrt bleibt, und eine abgelehnte löst nie einen Widerruf aus, den du zurücknehmen müsstest.