Een aankoop in behandeling lijkt op een verkoop, maar het geld is nog niet binnen, en wie hem te vroeg vrijgeeft, geeft het product weg

Iemand tikt in je app op kopen. Je logs tonen een nieuwe bestelling, je billing-listener wordt geactiveerd, en je overhandigt de goederen. Bij de meeste aankopen is dat precies goed. Bij een aankoop in behandeling is het een fout, want de bestelling bestaat maar het geld niet. De klant koos een betaalmethode die later wordt afgehandeld, de store wacht nog op zijn geld, en jij hebt zojuist een betaalde functie geleverd voor een afschrijving die misschien nooit binnenkomt. Dit is de stille neef van een terugbetaling. Hier wordt niets teruggedraaid, omdat er nooit iets is geïnd. Je hebt het product gewoon weggegeven.

Een aankoop in behandeling is een echte bestelling in een nog-niet-betaalde status, en zowel de App Store als Google Play kennen die. Beide stores zeggen je onomwonden te wachten. De valstrik is dat een bestelling in behandeling er in je code vrijwel identiek uitziet als een voltooide, zodat een integratie die elke nieuwe aankoop als verkoop behandelt goederen levert op bestellingen die de store nog probeert te innen. Doe het goed en je verliest niets. Doe het fout en elke trage betaling die afketst is pure kostenpost, geleverd op jouw rekening.

Wat een aankoop in behandeling eigenlijk is

Een aankoop in behandeling is een bestelling die de store heeft vastgelegd maar nog niet heeft afgeschreven. De koper startte de stroom, de store accepteerde hem, en de afhandeling gebeurt ergens waar je app niets kan zien. Google Play noemt dit de PENDING-status. Apple noemt het een lopende, of uitgestelde, transactie. Verschillende namen, hetzelfde feit: de store houdt een bestelling open terwijl hij wacht op betaling, en heeft je verteld die bestelling niet als geld te behandelen.

Google Play: de betaling gebeurt ergens anders

Sommige betaalmethoden worden buiten de reguliere stroom afgehandeld. Contant geld in een fysieke winkel, bankoverschrijvingen en sommige vormen van betaling via de telefoonrekening vergen allemaal extra stappen tussen de tik en de afschrijving. Wanneer een klant er een kiest, geeft Google de aankoop terug in de PENDING-status in plaats van PURCHASED. Bij een contante betaling ontvangt de klant een code per melding en per e-mail, brengt die naar een deelnemende winkel en betaalt bij de kassa. Tot dat gebeurt heeft Google niets geïnd, en jij evenmin. Google's regel is één zin: gebruik getPurchaseState() en verleen alleen toegang wanneer de status PURCHASED is. Google zegt je ook een aankoop niet te bevestigen zolang die PENDING is, want bevestiging hoort bij een betaalde bestelling, niet bij een beloofde.

Apple: de aankoop wacht op de tik van iemand anders

Apple's lopende status betekent dat de transactie een externe actie nodig heeft voordat ze kan worden voltooid. De meest voorkomende is Ask to Buy, waarbij een kind een aankoop start en een gezinsorganisator hem moet goedkeuren. In StoreKit 2 geeft de aankoopaanroep Product.PurchaseResult.pending terug. In het oudere StoreKit wordt de transactie als uitgesteld gemeld. Hoe dan ook heeft Apple niemand belast, en de voltooide transactie komt, als ze komt, asynchroon binnen via Transaction.updates. Toon de klant een wachtstatus en ontgrendel niets tot de voltooide transactie binnenkomt.

Waarom het vrijgeven van een aankoop in behandeling je echt geld kost

Het verlies hier is niet het terugbetalingssoort, waarbij geld dat je hebt geboekt wordt teruggetrokken. Het is op één specifieke manier erger: er is geen geld terug te trekken, omdat er nooit iets is geïnd.

Jij levert, en de store int nooit iets

Wanneer je ontgrendelt bij een bestelling in behandeling die later wordt geannuleerd, heb je al besteed om die te bedienen. De rekenkracht die de functie draaide, de API-aanroepen van derden waarvoor je betaalde, de opslag die je toewees, en bij een verbruiksartikel de daadwerkelijke uitbetaling van wat je verkocht. Dat gaat allemaal de deur uit op een bestelling die geen omzet opleverde. Een terugbetaling begint tenminste vanuit een afschrijving die plaatsvond. Een onterecht verleende aankoop in behandeling had helemaal nooit een afschrijving, dus verschijnt hij niet eens als geld dat naar buiten gaat. Hij verschijnt als niets, en dat is precies waarom hij makkelijk over het hoofd te zien en makkelijk te herhalen is.

Het annuleersignaal, en wat het betekent

De store laat je wel degelijk weten wanneer een bestelling in behandeling sterft. Op Google Play stuurt een eenmalig product dat afketst een ONE_TIME_PRODUCT_CANCELED-melding, type 2, en een abonnement dat in behandeling was stuurt SUBSCRIPTION_PENDING_PURCHASE_CANCELED, type 20. Wanneer diezelfde bestellingen wél doorgaan, krijg je ONE_TIME_PRODUCT_PURCHASED, type 1, of SUBSCRIPTION_PURCHASED, type 4. Bij Apple is er geen annuleergebeurtenis om op te vangen, want een uitgestelde transactie die wordt geweigerd wordt simpelweg nooit een voltooide transactie. Als je te vroeg hebt ontgrendeld, is die stilte de rekening.

Het venster, en wie op wie wacht

Een aankoop in behandeling is geen klok waartegen je racet. Het is een klok die, vanaf jouw kant, nog niet is gestart.

Google Play geeft de klant dagen, geen minuten

Een contante of bankoverschrijvingsbetaling wordt afgehandeld op het schema van de klant, niet het jouwe. De bestelling blijft in PENDING totdat de klant betaalt of het venster verstrijkt en Google hem annuleert. Je eigen bevestigingsvenster van drie dagen, dat een aankoop automatisch terugbetaalt die je niet bevestigt, begint niet eens voordat de aankoop overgaat van PENDING naar PURCHASED. Er is dus geen haast om een bestelling in behandeling te bedienen. Er is alleen de discipline om te wachten tot de status verandert.

Apple's goedkeuring staat op de telefoon van de gezinsorganisator

Een Ask to Buy-verzoek belandt op het apparaat van de organisator als een melding die hij goedkeurt of weigert wanneer hij eraan toekomt. Dat kan minuten, uren of een dag later zijn, en je app kan het niet versnellen. Het enige juiste gedrag is de wachtstatus weergeven en StoreKit de voltooide transactie laten overhandigen als en wanneer de goedkeuring komt.

Hoe je aankopen in behandeling afhandelt zonder te lekken

De hele klus komt neer op vier gewoontes. Geen ervan is moeilijk, en het overslaan van ook maar één ervan is waar het geld heen gaat.

Verleen bij de betaalde status, nooit bij de behandelde

Op Google Play controleer je getPurchaseState() en verleen je alleen bij PURCHASED, en bevestig je een aankoop niet zolang die PENDING is. Bij Apple ontgrendel je alleen bij een voltooide transactie en nooit bij het lopende resultaat. Deze ene regel sluit het hele lek af. Al het andere gaat erover ervoor te zorgen dat je daadwerkelijk merkt wanneer de betaalde status binnenkomt.

Controleer opnieuw wanneer de app terugkomt

De overgang van behandeling naar betaald gebeurt vaak terwijl je app niet draait. Op Google Play roep je queryPurchasesAsync() aan in je onResume()-handler om bestellingen op te pikken die op de achtergrond PURCHASED werden, en houd je je Real-time Developer Notifications-listener als de serverzijdige bron van waarheid. Bij Apple luister je gedurende de hele levensduur van de app naar Transaction.updates, want een goedgekeurde transactie kan lang nadat de oorspronkelijke aankoopaanroep terugkeerde binnenkomen.

Schakel ondersteuning voor aankopen in behandeling in en test beide uitkomsten

Google vereist dat je enablePendingPurchases() aanroept wanneer je de BillingClient bouwt, en het ondersteunen van transacties in behandeling voor eenmalige producten is verplicht, niet optioneel. Test het voordat je uitlevert. Licentietesters krijgen twee extra testinstrumenten voor uitgestelde betaalvormen, waarbij de betaling na een paar minuten automatisch wordt voltooid of automatisch geannuleerd, zodat je zowel het betaalpad als het afketspad van begin tot eind kunt bekijken.

Vertel de klant dat de bestelling niet klaar is

Een koper in behandeling is een echte klant midden in een aankoop, geen mislukking. Laat hem zien dat de bestelling wacht op zijn betaling of op een goedkeuring, en geef hem een duidelijke weg terug om die af te ronden. Een stille status in behandeling verliest verkopen die een goed gelabelde terugwint, want de meeste van deze kopers willen het ding nog steeds en hebben slechts één stap te gaan.

Dezelfde feeds van Real-time Developer Notifications en App Store Server Notifications die RefundHalt al leest voor terugbetalingen en terugboekingen dragen ook deze signalen. De purchased-melding die zegt dat een bestelling in behandeling eindelijk is binnengekomen, en de canceled-melding die zegt dat dat niet zo is, belanden in je dashboard naast de rest van je omzetgebeurtenissen, zodat een bestelling in behandeling die afketste iets is dat je kunt zien in plaats van iets waarvoor je per ongeluk hebt betaald.

De korte versie

Een aankoop in behandeling is een bestelling zonder betaling, en beide stores zijn expliciet dat je moet wachten. Google Play geeft contante, bankoverschrijvings- en sommige betalingen via telefoonrekening terug in een PENDING-status en zegt je alleen bij PURCHASED toegang te verlenen. Apple geeft een lopende of uitgestelde transactie terug voor Ask to Buy en andere vereiste acties en levert de voltooide transactie later via Transaction.updates. Ontgrendel bij de betaalde status, controleer opnieuw wanneer je app hervat, schakel ondersteuning voor behandeling in en test die, en label de wachtende bestelling voor de klant. Doe dat en een aankoop in behandeling kost je niets. Sla het over en je levert een betaald product voor een afschrijving die nooit kwam, wat het enige verlies is zonder bonnetje om naar te wijzen.