Lampirkan appAccountToken pada setiap pembelian App Store, atau Anda tidak bisa membela refund

Seorang pelanggan meminta refund ke Apple, Apple mengirimkan CONSUMPTION_REQUEST ke server Anda, dan Anda punya dua belas jam untuk menjawab dengan data nyata tentang bagaimana orang itu menggunakan produk. Lalu Anda membuka notifikasi itu dan menyadari Anda tidak tahu siapa mereka. Transaksi membawa originalTransactionId dan id produk, tetapi tidak ada yang menunjuk ke akun di basis data Anda sendiri. Celah itulah yang persis ditutup oleh appAccountToken, dan jika Anda tidak menyetelnya saat pembelian, Anda tidak bisa menutupnya belakangan untuk penjualan tersebut.

appAccountToken adalah UUID yang Anda lampirkan pada pembelian sehingga transaksi App Store yang dihasilkan membawa penunjuk kembali ke pengguna yang tepat di sistem Anda. Setel, dan setiap pertanyaan refund yang pernah Apple ajukan tentang pelanggan itu datang dengan identitasnya terlampir. Lewati, dan Anda menebak. Berikut apa itu field ini, cara menyetelnya, endpoint baru yang menyelamatkan pembelian yang dilakukan di luar aplikasi Anda, dan berapa sebenarnya biaya mata rantai yang hilang saat sebuah refund tiba.

Apa sebenarnya appAccountToken itu

appAccountToken adalah UUID buram yang Anda buat dan berikan ke StoreKit pada saat pembelian. Apple menyimpannya pada transaksi dan mengembalikannya di info transaksi untuk pembelian itu, dan tetap di sana. Dalam kata-kata Apple, ini adalah "UUID yang mengaitkan transaksi dengan akun pengguna di layanan Anda sendiri." Satu-satunya aturan format adalah bahwa nilainya harus UUID. Apple tidak membacanya, tidak memvalidasi ke mana ia terpetakan, dan tidak peduli apa artinya di sisi Anda. Ini adalah tautan yang Anda kendalikan.

Karena ia hidup pada transaksi, ia kembali di mana pun transaksi itu kembali. Transaksi bertanda tangan dalam notifikasi server, respons Get Transaction Info dari App Store Server API, dan setiap perpanjangan dalam rantai langganan, semuanya membawa token yang sama jika Anda menyetelnya pada pembelian asli. Satu UUID, dilampirkan sekali, mengikuti penagihan pelanggan sepanjang umur hubungan itu.

Ia harus berupa UUID asli, atau ia diam-diam menghilang

Satu aturan yang ditegakkan Apple adalah format. StoreKit 2 membutuhkan UUID RFC 4122. Jika Anda mengirim string gabungan, id bilangan bulat, atau alamat email, StoreKit tidak melempar error. Ia membuang nilai itu dan transaksi kembali dengan appAccountToken disetel ke nil. Pengembang terus-menerus mengalaminya, dan gejalanya selalu sama, semacam varian dari "appAccountToken hilang dalam payload transaksi" di forum Apple sendiri, hampir selalu karena nilai yang dikirim bukan UUID yang valid. Buat UUID asli di sisi server, simpan terhadap akun, dan jangan pernah memberikan apa pun yang lain ke StoreKit.

Cara menyetelnya saat pembelian

Di StoreKit 2 ini adalah satu opsi pembelian. Buat UUID di server Anda saat pengguna mendaftar atau pertama kali mencapai checkout, simpan pada catatan akun mereka, dan berikan nilai yang sama ke panggilan pembelian.

Tanda tangannya adalah Product.PurchaseOption.appAccountToken(_ token: UUID), dan sebuah pembelian terlihat seperti try await product.purchase(options: [.appAccountToken(token)]). Saat transaksi kembali, diverifikasi melalui App Store Server API atau dikirim oleh notifikasi server, ia membawa UUID itu, dan server Anda mencari pelanggan dalam satu kueri.

Gunakan satu token stabil per akun

Jangan membuat token baru untuk setiap pembelian oleh pengguna yang sama. Apple mengembalikan token pada perpanjangan, percobaan ulang penagihan, dan peningkatan dalam rantai yang sama, jadi UUID stabil per akun memberi Anda benang yang bersih dari pembelian pertama hingga setiap peristiwa mendatang. Token yang berubah setiap pembelian memutus benang itu dan menggagalkan seluruh tujuannya. Satu akun, satu token, digunakan kembali setiap kali akun itu membeli.

Endpoint yang menyelamatkan pembelian di luar aplikasi

Hingga 2025 ada sebuah lubang. Jika pelanggan menukar kode penawaran atau membeli pembelian dalam aplikasi yang dipromosikan langsung dari App Store, aplikasi Anda tidak pernah menjalankan alur pembelian, jadi tidak ada tempat untuk menyetel appAccountToken. Transaksi-transaksi itu datang anonim dan tetap begitu.

WWDC 2025 menutup celah itu dengan endpoint Set App Account Token. Server Anda memanggil PUT /inApps/v1/transactions/{originalTransactionId}/appAccountToken di App Store Server API dengan UUID di dalam body, dan Apple menyetel token pada transaksi itu. Ini bekerja untuk setiap jenis produk, mencakup penukaran kode penawaran dan pembelian yang dipromosikan, dan nilai yang Anda kirim menimpa token apa pun yang sudah ada pada transaksi. Anda sekarang bisa mengaitkan sebuah pembelian belakangan, dari server Anda, tanpa pernah melewati aplikasi Anda.

Di mana mata rantai yang hilang membuat Anda rugi uang

Tujuan token bukanlah catatan yang rapi. Tujuannya adalah bahwa satu-satunya pertanyaan refund Apple untuk pengembang, CONSUMPTION_REQUEST, hanya dapat dijawab jika Anda bisa menemukan pelanggan yang dimaksud.

Saat pembeli meminta refund atas produk consumable atau langganan yang tidak diperbarui, Apple mengirimkan notifikasi CONSUMPTION_REQUEST ke server Anda dan memberi Anda dua belas jam untuk membalas dengan Send Consumption Information. Jawaban Anda adalah data tentang pelanggan spesifik itu: seberapa banyak produk yang mereka konsumsi, lama keanggotaan akun mereka, total belanja seumur hidup mereka, status pengiriman mereka. appAccountToken sendiri adalah salah satu field dalam permintaan itu, dan yang lebih penting, itulah cara transaksi notifikasi terpetakan ke akun yang penggunaannya akan Anda uraikan. Tanpa token, tanpa pencarian, tanpa jawaban yang akurat.

Berapa sebenarnya biaya jawaban kosong

Refund yang tidak teridentifikasi memaksa pilihan yang buruk. Anda bisa menjawab permintaan konsumsi tanpa apa pun, yang terbaca sebagai konsumsi rendah dan mendorong Apple ke arah mengabulkan refund, termasuk kepada pelanggan yang memakai produk secara intensif. Atau Anda bisa menebak. Bagaimanapun juga Anda mengembalikan uang atas pembelian yang punya bukti untuk dibela, dan Anda sudah membayar biaya nyata untuk melayaninya.

Biaya itu bukan harga jual. Sebuah produk consumable yang menjalankan sekumpulan panggilan API model, menghasilkan gambar, mengekspor video, atau memicu pembayaran kreator telah menghabiskan uang nyata pada saat ia dikirimkan. Refund mengembalikan pembayaran pelanggan. Ia tidak mengembalikan tagihan penyedia. Kalikan satu pelanggan yang tidak dapat diidentifikasi dengan setiap refund yang mereka ajukan, dan dengan setiap peminta refund berulang yang mengandalkan Anda tidak mengetahui siapa mereka, dan token yang Anda lewati menjadi baris kode termahal yang tidak pernah Anda tulis.

Ide yang sama ada di Android, dengan nama lain

Google Play memecahkan masalah yang sama persis dengan setObfuscatedAccountId, yang melampirkan pengenal akun pada pembelian sehingga tinjauan chargeback Google melalui orders.reviewrefund dapat dijawab terhadap pengguna nyata. Toko berbeda, mekanika berbeda, pelajaran yang sama: lampirkan identitas saat pembelian atau Anda tidak bisa membela sengketa belakangan. Di App Store, alat itu adalah appAccountToken, dan ia harus berupa UUID.

Tiga kebiasaan yang menjaga token tetap di tempatnya

• Buat satu UUID per akun dan simpan. Satu token stabil per pelanggan, dibuat saat mereka mendaftar atau pada checkout pertama, disimpan pada catatan mereka dan digunakan kembali untuk setiap pembelian.
• Validasi sebelum Anda mengirimkannya. Pastikan nilainya adalah UUID asli di kode pembelian Anda, agar id yang cacat tidak pernah bisa diam-diam menjadi token nil pada transaksi.
• Isi ulang pembelian di luar aplikasi. Saat notifikasi server tiba untuk penukaran kode penawaran atau pembelian yang dipromosikan tanpa token, panggil endpoint Set App Account Token untuk melampirkan yang benar.

Lakukan ketiganya dan setiap transaksi yang pernah Apple kirim kepada Anda, termasuk permintaan refund, tiba sudah terikat pada pelanggan yang menjadi pemiliknya.

Inilah fondasi yang diandalkan RefundHalt. Kami membaca appAccountToken dari setiap transaksi dan notifikasi server, mengaitkannya dengan penggunaan yang sudah kami lacak untuk akun itu, dan menjawab permintaan konsumsi Apple dalam jendela dua belas jam dengan angka nyata pelanggan. Token adalah benangnya. Setel sekali dan pembelaan refund Anda punya sesuatu untuk dipegang.