Ketika pembelian Google Play direfund atau di-chargeback, Voided Purchases API adalah cara Anda mengetahuinya

Sebuah refund di Google Play tidak mengetuk pintu Anda. Uangnya berpindah, pelanggan tetap membuka aplikasi, dan kecuali Anda memeriksanya, tidak ada yang berubah di sisi Anda. Voided Purchases API adalah tempat Anda memeriksanya. API ini memberi Anda daftar pesanan yang dibatalkan, direfund, atau di-chargeback, sehingga Anda bisa mencabut akses ke hal yang tidak lagi dibayar pelanggan. Arahkan sebuah scheduled job ke sana, baca daftarnya, putus entitlement-nya. Itulah keseluruhan alurnya.

Ada satu jebakan yang menyandung sebagian besar tim, dan itu bukan di dalam kode. Hanya pesanan yang direvoke yang muncul di sini. Jika Anda merefund sebuah pembelian di Play Console tanpa mencentang opsi revoke, pesanan itu tidak akan pernah sampai ke API ini, dan job Anda berjalan mulus sementara pelanggan yang direfund tetap menyimpan semua yang Anda jual kepadanya. Artikel ini membahas API ini field demi field, angka-angka yang membatasinya, dan di mana uang bocor ketika Anda melewatkannya.

Apa yang sebenarnya dikembalikan Voided Purchases API

API ini menjawab satu pertanyaan: pesanan mana untuk aplikasi ini yang baru-baru ini dibatalkan. Sebuah pembatalan (void) mencakup tiga hasil yang semuanya berakhir dengan pelanggan mendapatkan uangnya kembali. Sebuah cancellation, sebuah refund, atau sebuah chargeback. Ini berlaku untuk produk dalam aplikasi sekali beli dan untuk langganan, dan Anda memilih cakupannya dengan satu parameter. Setel type ke 0 dan Anda hanya mendapatkan pembelian produk dalam aplikasi yang dibatalkan, yang merupakan default. Setel ke 1 dan Anda mendapatkan pembelian dalam aplikasi yang dibatalkan dan pembelian langganan yang dibatalkan sekaligus.

Setiap entri dalam daftar adalah sebuah objek voided purchase. Field-nya sedikit dan setiap field penting.

Field pada sebuah voided purchase

Baca voidedReason sebelum Anda bertindak

voidedReason adalah field yang mengubah daftar mentah menjadi sebuah keputusan. Sebuah refund karena penyesalan pembeli dan sebuah chargeback bank sama-sama masuk ke daftar yang sama, tetapi keduanya bukan peristiwa yang sama, dan harga baru di bulan Agustus membuat salah satunya mahal. Berikut himpunan lengkapnya.

Jendela 30 hari adalah jebakan yang mengosongkan daftar Anda

Voided Purchases API hanya bisa menampilkan pembelian yang dibatalkan dari 30 hari terakhir. Parameter startTime secara default bernilai waktu saat ini dikurangi 30 hari, dan tidak bisa disetel lebih lama dari itu. endTime secara default bernilai sekarang. Jadi endpoint ini adalah jendela satu bulan yang bergulir, bukan sebuah arsip.

Konsekuensinya gamblang. Jika polling job Anda rusak dan tidak ada yang menyadarinya selama lima minggu, pembatalan dari minggu pertama sudah kedaluwarsa dari API. Tidak ada panggilan yang bisa membawanya kembali. Anda tidak akan mencabut pesanan itu, dan Anda bahkan tidak akan tahu bahwa pesanan itu pernah ada kecuali Anda menangkapnya dengan cara lain. API ini adalah jaring pengaman dengan lubang seukuran gangguan terburuk Anda.

Opsi revoke menentukan apakah sebuah pesanan bahkan muncul

Ini adalah alasan paling umum sebuah tim melaporkan API ini rusak. Hanya pesanan yang direvoke yang dikembalikan. Refund yang dimulai pengguna, pembatalan, chargeback, dan refund yang dimulai Google selalu direvoke, jadi selalu muncul. Refund yang dimulai developer berbeda. Ketika Anda merefund sebuah pesanan sendiri, melalui Play Console atau Orders API, Anda memilih apakah juga akan merevoke-nya. Refund tanpa revoke, dan pesanan itu selesai dengan pelanggan tetapi tidak pernah muncul di Voided Purchases API.

Aturan yang mengikutinya sederhana. Jika niat Anda adalah menarik akses, lakukan refund dengan opsi revoke aktif. Jika tidak, Anda sudah mengembalikan uang dan membiarkan pintu terbuka, dan revocation job Anda, sebaik apa pun ditulis, tidak punya apa pun untuk ditindaklanjuti.

Cara melakukan polling tanpa melampaui kuota

Endpoint ini memiliki rate limit, dan batasnya cukup rendah sehingga loop yang naif akan menabraknya. Anda mendapatkan 6,000 kueri per hari, dihitung dalam Pacific Time, dan tidak lebih dari 30 kueri dalam setiap periode 30 detik. Anggaran itu memadai untuk polling berbasis jendela dan tidak ramah bagi desain satu-permintaan-per-pesanan.

Jendela kueri dan continuation token

maxResults secara default bernilai 1,000, yang juga merupakan batas atasnya. Ketika sebuah jendela memuat lebih dari satu halaman pembatalan, respons membawa sebuah objek tokenPagination dengan nextPageToken. Kirimkan kembali token itu pada panggilan berikutnya untuk menelusuri halaman-halaman. Setel startTime dan endTime untuk membatasi jendela yang Anda pedulikan, telusuri halaman hingga token habis, lalu majukan jendelanya. Pola itu menjaga Anda tetap di dalam batas burst 30 detik dan batas harian sekaligus.

Real-time developer notifications menutup celahnya

Polling setiap hari masih menyisakan hingga satu hari kebutaan, dan jendela 30 hari menghukum celah yang panjang. Real-time developer notifications menghilangkan jeda itu. Google mempublikasikan sebuah VoidedPurchaseNotification ke sebuah topik Cloud Pub/Sub milik Anda pada saat sebuah pembelian dibatalkan, dan backend Anda mengonsumsinya dalam hitungan detik. Pesannya kecil.

Berapa biayanya bagi Anda dalam bentuk uang

API ini adalah pipa saluran, tetapi alasan untuk memasangnya adalah tagihan. Setiap pembatalan dalam daftar itu memetakan ke sebuah angka nyata, dan dua di antaranya menjadi lebih mahal.

Tagihan chargeback jatuh ke Anda mulai 3 Agustus 2026

Mulai 3 Agustus 2026, Google mengalihkan biaya sebuah chargeback ke developer. Anda kehilangan harga pembelian dan Anda membayar biaya chargeback bank di atasnya. voidedReason bernilai 7 tidak lagi sekadar penjualan yang hilang, itu adalah sebuah item baris dengan biaya yang menyertainya. Anda tidak bisa membalikkan sebuah chargeback, itu final di pihak bank, tetapi Anda bisa menghentikan pendarahan setelahnya. Menangkap pembatalan dengan cepat memungkinkan Anda mencabut entitlement dan, untuk apa pun yang masih Anda kirimkan, berhenti membelanjakan untuk pelanggan yang direfund lalu dibalikkan.

Anda terus membayar untuk melayani pelanggan yang sudah direfund

Harga pembelian lenyap begitu sebuah pembatalan muncul. Yang masih Anda kendalikan adalah biaya untuk terus memberikan layanan. Setiap jam sebuah entitlement yang direfund tetap aktif, Anda terus membayar untuk hal-hal yang tidak lagi didanai pelanggan: komputasi, panggilan API model, penyimpanan, dan pembayaran kreator atau mitra apa pun yang terkait dengan penggunaan mereka. Sebuah sistem pencabutan yang digerakkan oleh API ini adalah cara Anda mematikan meteran itu. Lewati itu, dan Anda mendanai produk untuk orang-orang yang sudah dipulihkan oleh toko.

Friendly fraud adalah pola yang layak ditelusuri trennya

voidedReason bernilai 5 atau 6 bukan kejadian sekali saja. Fraud dan friendly fraud mengelompok berdasarkan akun, berdasarkan perangkat, dan terkadang berdasarkan promosi. API memberi Anda voidedSource dan voidedReason pada setiap pembatalan, yang cukup untuk menelusuri tren penyalahgunaan berdasarkan akun alih-alih memperlakukan setiap pembalikan sebagai biaya yang terisolasi. Seorang pelanggan yang melakukan chargeback dua kali memberi tahu Anda sesuatu yang tidak disampaikan oleh refund pertama.

Memasangnya dengan cara RefundHalt

Modelnya kecil begitu Anda memegang semua kepingannya. Dengarkan VoidedPurchaseNotification secara real time agar tidak ada yang menunggu satu hari penuh. Panggil Voided Purchases API sebagai sumber kebenaran, dengan kunci orderId agar perpanjangan langganan tidak pernah tertukar. Baca voidedSource dan voidedReason agar sebuah chargeback ditangani berbeda dari sebuah refund penyesalan. Lakukan polling dengan jadwal yang cukup rapat sehingga jendela 30 hari tidak pernah menggigit, dan refund dengan opsi revoke aktif kapan pun niat Anda adalah memutus akses.

Ini adalah bagian yang dijalankan RefundHalt untuk Anda. RefundHalt mengonsumsi notifikasi real-time, merekonsiliasi setiap pembatalan terhadap API, mencabut pesanan yang tepat alih-alih seluruh produk, dan memisahkan sebuah chargeback bank dari sebuah refund biasa sehingga yang mahal ditandai, bukan terkubur. Anda mendapatkan akses yang dicabut dalam hitungan detik dan sebuah catatan tentang siapa yang membatalkan apa dan mengapa, tanpa perlu membangun sendiri sebuah pipeline Pub/Sub dan sebuah polling job.