Zowel Apple als Google kunnen dezelfde terugbetaling meer dan eens aan uw server bezorgen, en dubbele terugbetalingsmeldingen kosten u geld als u op elke afzonderlijke reageert

Uw server zal dezelfde terugbetalingsgebeurtenis meer dan eens ontvangen, en beide stores hebben dat met opzet zo ontworpen. Apple probeert een App Store Server Notification tot vijf keer opnieuw wanneer uw endpoint niet netjes antwoordt. Google Play bezorgt zijn Real-time Developer Notifications over Cloud Pub/Sub, dat at-least-once-bezorging belooft en niets over volgorde. De vraag is dus nooit of een duplicaat binnenkomt. Ze luidt wat uw code doet de tweede keer dat hij dezelfde terugbetaling ziet. Doe dat verkeerd en u trekt een saldo tweemaal af, draait een uitbetaling tweemaal terug, of verbrandt factureerbare API-quota door een terugbetaling opnieuw te controleren die u al had afgesloten. Zo bereiken dubbele terugbetalingsmeldingen u werkelijk, welke herhalingen echte duplicaten zijn en welke er alleen zo uitzien, en hoe u ze behandelt zodat de tweede bezorging gratis is.

Een terugbetalingsmelding wordt minstens één keer bezorgd, wat niet hetzelfde is als precies één keer

Beide stores behandelen een bezorgde melding als een belofte die ze steeds opnieuw proberen na te komen, niet als een enkel schot dat ze afvuren en vergeten. Dat is goed voor de betrouwbaarheid, want een melding die u tijdens een deploy mist, bereikt u later alsnog. Het is een valkuil voor de juistheid, want het mechanisme dat garandeert dat u de gebeurtenis uiteindelijk krijgt, garandeert ook dat u ze soms twee keer krijgt. Uw handler moet idempotent zijn, wat betekent dat de tweede en derde bezorging van één terugbetaling niets veranderen wat de eerste niet al veranderde.

Apple probeert vijf keer opnieuw over drie dagen

Wanneer Apple een App Store Server Notification V2 stuurt, verwacht het dat uw server antwoordt met een HTTP-status in het bereik 200 tot 206. Al het andere, een 4xx of een 5xx, vertelt Apple dat de bezorging is mislukt, en Apple probeert opnieuw. Het schema ligt vast: vijf retries, na 1, 12, 24, 48 en 72 uur na de vorige poging. De eerste poging meegeteld kan één terugbetalingsgebeurtenis tot zes keer binnenkomen, verspreid over ongeveer een week. Elk van die retries draagt dezelfde notificationUUID. Dat veld is uw deduplicatiesleutel. Als u een notificationUUID al hebt vastgelegd, is de bezorging die u vasthoudt een herhaling, en het juiste antwoord is niets nieuws op te slaan en toch 200 terug te geven.

Google Play leunt op Pub/Sub, dat at-least-once belooft en niets zegt over volgorde

De Real-time Developer Notifications van Google Play worden gepubliceerd naar een Cloud Pub/Sub-topic. De bezorggarantie van Pub/Sub is at-least-once, en er is helemaal geen volgordegarantie. Dat betekent dat hetzelfde bericht meer dan eens aan uw endpoint kan worden bezorgd, en dat twee berichten voor dezelfde aankoop in verkeerde volgorde kunnen binnenkomen. Googles eigen richtlijn is expliciet: pak het base64-data-veld uit, lees de messageId en controleer dat u die nog niet hebt gezien voordat u iets verwerkt. Een dubbele messageId is een herhaling die u overslaat. Twee verschillende meldingen over één aankoop moeten toch op hetzelfde record belanden, dus veranker uw opgeslagen toestand ook aan de purchaseToken en laat een latere gebeurtenis de rij bijwerken die een eerdere aanmaakte.

De herhalingen die geen duplicaten zijn

Niet elke melding die eruitziet als een die u al hebt gezien, is een retry. Twee Apple-gedragingen sturen echt nieuwe gebeurtenissen die een aankoop delen maar elk verwerkt moeten worden, en ze samenvoegen met een naïeve deduplicatie gooit informatie weg die u nodig had.

Apple stuurt verse CONSUMPTION_REQUESTs, geen retries

Tijdens een open terugbetalingsverzoek voor een verbruiksartikel stuurt Apple niet één CONSUMPTION_REQUEST en wacht af. Het stuurt over het hele open terugbetalingsvenster periodiek nieuwe, tot de terugbetaling is afgesloten. Apple-medewerkers hebben bevestigd dat dit geen retries zijn, en het verraderlijke teken is het veld waarop u dedupliceert: elke verse CONSUMPTION_REQUEST draagt een andere notificationUUID. Een deduplicatie verankerd aan de notificationUUID doet dus automatisch het juiste. Ze voegt echte retries samen en behoudt elke afzonderlijke prompt. Wat u niet mag doen, is dedupliceren op transactie-id en meldingstype, want dat zou elke CONSUMPTION_REQUEST na de eerste het zwijgen opleggen en u het 12-uur-bewijsvenster kosten op de weggegooide.

Eén transactie kan meer dan één beslissing dragen

Een enkele transactionId kan over haar leven meer dan één terugbetalingsuitkomst voortbrengen. Apple kan een REFUND_DECLINED sturen en dan, later, een REFUND voor dezelfde transactie, en ontwikkelaars melden drie of meer terugbetalingsgerelateerde meldingen voor één transactie-id te ontvangen. Elk is een afzonderlijke gebeurtenis met haar eigen notificationUUID. Als uw deduplicatiesleutel de transactie-id is, ziet de tweede beslissing eruit als een duplicaat van de eerste en komt u nooit te weten dat de terugbetaling uiteindelijk is toegekend. De transactie-id groepeert gebeurtenissen. Ze identificeert ze niet.

Wat een duplicaat u werkelijk kost

Een terugbetalingsmelding is geen statuslampje. Ze zet echte acties in gang: u trekt toegang in, u trekt een verbruikssaldo af, u draait een uitbetaling aan een maker terug, u roept de App Store Server API of de Play Developer API aan om de toestand te bevestigen. Voer een van die een tweede keer uit op een duplicaat en de kosten zijn reëel.

Volg het geld. Toegang tweemaal intrekken is onschadelijk, want de toegang is al weg. Een saldo tweemaal aftrekken is dat niet: een gebruiker die een pakket munten kocht en terugbetaalde, kan naar een negatief saldo worden gedreven dat uw supportteam dan met de hand moet ontwarren. Een uitbetaling tweemaal terugdraaien haalt geld terug dat u al één keer had teruggegeven, en nu bent u een maker een verontschuldiging en een correctie schuldig. En elk duplicaat dat u opnieuw tegen een store-API verwerkt, verbruikt quota die Google u uitdrukkelijk aanraadt te beschermen, dus een uitbarsting van Pub/Sub-herbezorging tijdens een storing kan u naar rate limiting duwen op precies de dag waarop u het zich het minst kunt veroorloven.

De terugbetalings-bewijsvensters verhogen de inzet aan de Apple-kant. Als een naïeve deduplicatie de herhaalde CONSUMPTION_REQUESTs het zwijgen oplegt die Apple over het open terugbetalingsvenster stuurt, kunt u degene missen die u moest beantwoorden, en een CONSUMPTION_REQUEST die u niet binnen 12 uur beantwoordt, is een terugbetaling die Apple vaak standaard toekent. Dat is geen dubbele afschrijving. Het is een verloren verkoop plus de rekenkracht, API-aanroepen, opslag en uitbetalingen die u al hebt uitgegeven om de aankoop te leveren, waarvan de terugbetaling er geen terugbrengt.

Hoe u dubbele terugbetalingsmeldingen behandelt zonder dubbel te handelen

Het patroon is op beide stores hetzelfde, met een andere sleutel. Leg de bezorging vast, controleer de sleutel voordat u handelt, handel één keer, en vertel de store altijd dat u ze hebt ontvangen.

• Dedupliceer op de bezorg-id van de store, niet op de transactie. Gebruik notificationUUID voor Apple en de Pub/Sub-messageId voor Google Play. Sla die op met een unieke constraint zodat een gelijktijdig duplicaat de race verliest in plaats van dubbel te handelen.
• Maak de downstream-actie idempotent op haar eigen voorwaarden. Verankeren aan de bezorg-id stopt de herverwerking, maar schrijf ook het effect zo dat intrekken, aftrekken of terugdraaien eerst de huidige toestand controleert en veilig twee keer kan draaien.
• Eerst persisteren, dan bevestigen. Schrijf de gebeurtenis naar uw database voordat u 200 teruggeeft of het Pub/Sub-bericht bevestigt. Als u eerst bevestigt en het schrijven mislukt, beschouwt de store het bericht als bezorgd en stuurt het nooit meer, en nu bent u het definitief kwijt.
• Geef altijd een successtatus terug, ook voor een duplicaat. Een 200 tot 206 voor Apple, een 200 op de Pub/Sub-push voor Google. Een herhaling afwijzen met een fout zorgt er alleen voor dat de store ze opnieuw stuurt.
• Groepeer op de entiteit, identificeer op de gebeurtenis. Veranker uw opgeslagen aankooptoestand aan de purchaseToken of originalTransactionId zodat bezorgingen in verkeerde volgorde één rij bijwerken, maar behandel elke notificationUUID of messageId als een eigen gebeurtenis, want één aankoop brengt terecht meerdere voort.

Een korte checklist voordat u uw terugbetalings-webhook vertrouwt

• Apple-bezorgingen worden gededupliceerd op notificationUUID, en een herhaling schrijft niets nieuws maar geeft toch 200 terug.
• Google Play-bezorgingen worden gededupliceerd op de Pub/Sub-messageId, gecontroleerd vóór enige verwerking.
• De aankooptoestand is verankerd aan purchaseToken of originalTransactionId, zodat gebeurtenissen in verkeerde volgorde op één record belanden.
• Elk terugbetalingsneveneffect, intrekken, aftrekken of terugdraaien, is veilig meer dan eens uit te voeren.
• Uw handler schrijft de gebeurtenis voordat hij bevestigt, nooit erna.
• Herhaalde CONSUMPTION_REQUESTs worden behandeld als afzonderlijke prompts, niet als duplicaten, zodat geen open terugbetalingsvenster wordt weggegooid.

Stuur met opzet een duplicaat door uw eigen webhook en kijk hoe het de tweede keer niets verandert. Dat is de hele test. Een terugbetalingshandler die veilig twee keer geraakt kan worden, is er een waarover u zich niet meer druk hoeft te maken zodra een store besluit hem zes keer te raken.