Pengingat: Mulai 2 Agustus 2022, semua aplikasi baru harus menggunakan Library Penagihan versi 4 atau yang lebih baru. Pada 1 November 2022, semua update untuk aplikasi yang ada harus menggunakan Library Penagihan versi 4 atau yang lebih baru. Pelajari lebih lanjut.

Referensi AIDL Layanan Penagihan Google Play

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Peringatan: AIDL tidak digunakan lagi dan akan dihapus dalam rilis mendatang. Untuk menerapkan fitur penagihan bagi Google Play, gunakan Library Layanan Penagihan Google Play.

Dokumentasi ini menyajikan informasi referensi teknis terkait penggunaan AIDL Layanan Penagihan Google Play.

Kode Respons Server

Tabel berikut berisi semua kode respons server yang dikirimkan dari Google Play ke aplikasi Anda. Google Play mengirim kode respons secara bersamaan sebagai bilangan bulat yang dipetakan ke kunci RESPONSE_CODE di Bundle respons. Aplikasi Anda harus menangani semua kode respons ini.

Tabel 1. Ringkasan kode respons untuk panggilan AIDL Layanan Penagihan Google Play.

Kode Respons Nilai Deskripsi
BILLING_RESPONSE_RESULT_OK 0 Berhasil
BILLING_RESPONSE_RESULT_USER_CANCELED 1 Pengguna menekan kembali atau membatalkan dialog
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 Sambungan jaringan melemah
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 Versi AIDL Layanan Penagihan Google Play tidak didukung untuk jenis yang diminta
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Produk yang diminta tidak tersedia untuk dibeli
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Argumen yang tidak valid diberikan ke API. Error ini juga dapat mengindikasikan bahwa aplikasi tidak ditandatangani dengan benar atau tidak disiapkan dengan tepat untuk penagihan, atau tidak memiliki zin yang diperlukan dalam manifesnya.
BILLING_RESPONSE_RESULT_ERROR 6 Error fatal selama tindakan API
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Kegagalan membeli karena item sudah dimiliki
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Kegagalan melakukan pemakaian karena item tidak dimiliki

Referensi AIDL Layanan Penagihan Google Play - Dukungan

Bagian ini menjelaskan metode untuk memperoleh informasi tentang jenis dukungan penagihan yang tersedia untuk aplikasi Anda.

Metode isBillingSupported()

Metode ini menandakan apakah:

  • Versi API yang diberikan didukung untuk aplikasi Anda.
  • Google Play mendukung penagihan di negara pengguna.
  • Sistem penagihan Google Play diaktifkan dalam paket aplikasi Anda.
  • Aplikasi Anda dapat menggunakan jenis item yang diberikan untuk tujuan penagihan.

Tabel 2. Parameter isBillingSupported().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 3 dan yang lebih baru.

Metode isBillingSupportedExtraParams()

Metode ini identik dengan isBillingSupported(), kecuali Anda dapat meneruskan argumen keempat, Bundle, yang dapat berisi parameter ekstra.

Tabel 3. Parameter isBillingSupportedExtraParams().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.
extraParams Bundle

Kumpulan parameter tambahan yang menentukan lebih lanjut jenis sistem penagihan Google Play yang didukung oleh aplikasi.

Paket ini dapat berisi kunci opsional yang disebut vr yang memiliki nilai boolean. Tanda ini menentukan apakah aplikasi ini mendukung alur pembelian virtual reality (VR).

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 7 dan yang lebih baru.

Referensi AIDL Layanan Penagihan Google Play - Detail

AIDL Layanan Penagihan Google Play ditentukan dalam file IInAppBillingService.aidl, yang disertakan dalam aplikasi contoh Versi 3.

Metode getSkuDetails()

Gunakan metode getSkuDetails() ini untuk mendapatkan detail produk dari daftar ID produk yang sesuai.

Tabel 4. Parameter GetSkuDetails().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
type String Jenis item dalam aplikasi ("inapp" untuk pembelian satu kali dan "subs" untuk langganan).
skusBundle Bundle Paket yang berisi StringArrayList SKU dengan kunci ITEM_ID_LIST.

Jika metode getSkuDetails() berhasil, maka Google Play akan mengirimkan Bundle respons. Hasil kueri disimpan di Bundle dalam String ArrayList yang dipetakan ke kunci DETAILS_LIST. Tiap String dalam daftar detail berisi detail produk untuk satu produk dalam format JSON. Kolom dalam string JSON dengan detail produk diringkas dalam tabel 5.

Tabel 5. Deskripsi kolom JSON dengan detail item produk yang ditampilkan dari permintaan getSkuDetails().

Kunci Deskripsi
productId ID produk untuk produk.
type Nilai harus inapp untuk produk dalam aplikasi atau subs untuk langganan.
price Harga format item, termasuk tanda mata uangnya. Harga tidak termasuk pajak.
price_amount_micros Harga dalam unit mikro, dengan 1.000.000 unit mikro setara dengan satu unit mata uang. Misalnya, jika price adalah "€7.99", maka price_amount_micros adalah "7990000". Nilai ini melambangkan harga yang sudah dilokalkan dan dibulatkan untuk mata uang tertentu.
price_currency_code Kode mata uang ISO 4217 untuk price. Misalnya, jika price ditentukan dalam pound sterling Inggris, price_currency_code adalah "GBP".
title Judul produk.
description Deskripsi produk.
subscriptionPeriod Periode langganan, yang ditentukan dalam format ISO 8601. Misalnya, P1W sama dengan satu minggu, P1M sama dengan satu bulan, P3M sama dengan tiga bulan P6M sama dengan enam bulan, dan P1Y sama dengan satu tahun.

Catatan: Ditampilkan hanya untuk langganan.
freeTrialPeriod Periode uji coba yang dikonfigurasi di Konsol Google Play, yang ditentukan dalam format ISO 8601. Misalnya P7D sama dengan tujuh hari. Untuk mempelajari kelayakan uji coba gratis lebih lanjut, lihat Langganan dalam Aplikasi.

Catatan: Ditampilkan hanya untuk langganan dengan periode uji coba yang telah dikonfigurasi.

introductoryPrice Harga perkenalan terformat untuk langganan, termasuk tanda mata uang, seperti €3.99. Harga tidak termasuk pajak.

Catatan: Ditampilkan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.
introductoryPriceAmountMicros Harga perkenalan dalam unit mikro. Mata uangnya sama dengan price_currency_code.

Catatan: Ditampilkan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.
introductoryPricePeriod Periode penagihan harga perkenalan, yang ditentukan dalam format ISO 8601.

Catatan: Dikembalikan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.
introductoryPriceCycles Jumlah periode penagihan langganan yang memberikan harga perkenalan kepada pengguna, seperti 3.

Catatan: Ditampilkan hanya untuk langganan dengan periode perkenalan yang telah dikonfigurasi.

Metode getBuyIntent()

Metode ini menampilkan bilangan bulat kode respons yang dipetakan ke kunci RESPONSE_CODE, dan PendingIntent untuk meluncurkan alur pembelian item dalam aplikasi yang dipetakan ke kunci BUY_INTENT, sebagaimana dijelaskan dalam Menerapkan Layanan Penagihan Google Play. Saat menerima PendingIntent, Google Play mengirim respons Intent beserta data untuk pesanan pembelian tersebut. Data yang ditampilkan dalam Intent respons dirangkum pada tabel 6.

Catatan: Daripada menggunakan metode ini, sebaiknya Anda menggunakan getBuyIntentExtraParams(), yang menyediakan fungsi tambahan.

Tabel 6. Data respons dari permintaan pembelian Google Play.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika pembelian berhasil, error jika tidak.
INAPP_PURCHASE_DATA String dalam format JSON yang berisi detail tentang pesanan pembelian. Lihat tabel 7 untuk deskripsi kolom JSON.
INAPP_DATA_SIGNATURE String yang berisi tanda tangan data pembelian yang ditandatangani dengan kunci pribadi developer. Tanda tangan data menggunakan skema RSASSA-PKCS1-v1_5.

Tabel 7 menjelaskan kolom JSON yang dikembalikan dalam data respons untuk pesanan pembelian.

Tabel 7. Deskripsi kolom JSON untuk INAPP_PURCHASE_DATA.

Kolom Deskripsi
autoRenewing Menandakan apakah langganan otomatis diperpanjang. Jika true, langganan aktif, dan akan diperpanjang secara otomatis pada tanggal penagihan berikutnya. Jika false, menandakan bahwa pengguna telah membatalkan langganan. Pengguna memiliki akses ke konten langganan hingga tanggal penagihan berikutnya dan akan kehilangan akses pada waktu tersebut, kecuali pengguna mengaktifkan kembali perpanjangan otomatis (atau secara manual melakukan perpanjangan, seperti dijelaskan di Perpanjangan Manual). Jika Anda menawarkan masa tenggang, nilai ini tetap ditetapkan ke true untuk semua langganan, selama masa tenggang belum berakhir. Tanggal penagihan berikutnya diperpanjang secara dinamis setiap hari hingga akhir masa tenggang atau hingga pengguna memperbaiki metode pembayarannya.
orderId ID pesanan unik untuk transaksi. ID ini sesuai dengan ID pesanan pembayaran Google.
packageName Paket aplikasi tempat asal pembelian.
productId Kode produk item. Setiap item memiliki ID produk, yang harus Anda tentukan pada daftar produk aplikasi di Konsol Google Play.
purchaseTime Waktu produk dibeli, dalam milidetik sejak waktu acuan (1 Jan 1970).
purchaseState Status pembelian pesanan. Status ini selalu mengembalikan 0 (dibeli).
developerPayload String yang ditentukan developer yang berisi informasi tambahan tentang pesanan. Anda dapat menentukan nilai untuk kolom ini saat melakukan permintaan getBuyIntent.
purchaseToken Token yang secara unik mengidentifikasi pembelian untuk pasangan item dan pengguna tertentu.

Metode consumePurchase()

Memakai pembelian yang sesuai dengan token pembelian yang diberikan. Metode ini akan menyebabkan dihapusnya item dari semua respons berikutnya terhadap getPurchases() dan memungkinkan pembelian kembali item dengan SKU yang sama.

Tabel 8. Parameter consumePurchase().

Kunci Jenis Deskripsi
apiVersion int Nomor versi AIDL Layanan Penagihan Google Play yang digunakan aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
purchaseToken String Token dalam JSON informasi pembelian yang mengidentifikasi pembelian yang akan dipakai.

Metode ini menampilkan RESULT_OK(0) dari pemakaian yang berhasil, dan kode respons yang sesuai jika terjadi kegagalan.

Metode getBuyIntentToReplaceSkus()

Metode ini digunakan untuk mengupgrade atau mendowngrade pembelian langganan. Metode ini mirip dengan getBuyIntent(), namun metode ini mengambil daftar dengan persis satu SKU yang telah dibeli yang akan diganti dengan SKU yang sedang dibeli. Saat pengguna menyelesaikan pembelian, Google Play menukar SKU lama dan memberikan kredit kepada pengguna dengan nilai waktu langganannya yang tidak terpakai secara prorata. Google Play menerapkan kredit ini ke langganan baru, dan akan mulai menagih pengguna untuk langganan baru setelah kredit habis terpakai.

Catatan: Daripada menggunakan metode ini, sebaiknya Anda menggunakan getBuyIntentExtraParams(), yang menyediakan fungsi tambahan.

Metode ini ditambahkan pada AIDL Layanan Penagihan Google Play versi 5. Untuk memverifikasi bahwa metode ini dilaporkan, kirim permintaan AIDL isBillingSupported.

Catatan: Anda hanya dapat menggunakan metode ini untuk pembelian langganan. Jika parameter type yang diteruskan bukan "subs", metode ini akan menampilkan BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Selain itu, SKU yang diteruskan mungkin tidak menyertakan SKU untuk langganan musiman.

Metode ini menampilkan bilangan bulat kode respons yang dipetakan ke kunci RESPONSE_CODE, dan PendingIntent untuk meluncurkan alur pembelian untuk langganan dalam aplikasi yang dipetakan ke kunci BUY_INTENT. Saat menerima PendingIntent, Google Play mengirim respons Intent beserta data untuk pesanan pembelian tersebut. Data yang ditampilkan dalam respons Intent dirangkum pada tabel 9.

Tabel 9. Data respons dari permintaan pembelian AIDL Layanan Penagihan Google Play Versi 5.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika pembelian berhasil. Jika pembelian gagal, kode error akan muncul.
INAPP_PURCHASE_DATA String dalam format JSON yang berisi detail tentang pesanan pembelian. Lihat tabel 6 untuk deskripsi kolom JSON.
INAPP_DATA_SIGNATURE String yang berisi tanda tangan data pembelian yang ditandatangani oleh developer dengan kunci pribadinya. Tanda tangan data menggunakan skema RSASSA-PKCS1-v1_5.

Metode getBuyIntentExtraParams()

Metode ini memulai permintaan pembelian. Metode ini adalah varian dari metode getBuyIntent(), dan mengambil parameter extraParams tambahan. Parameter ini adalah Bundle kunci dan nilai opsional yang memengaruhi operasi metode sebagaimana ditampilkan pada tabel 10.

Tabel 10. Parameter tambahan getBuyIntentExtraParams().

Kunci Jenis Deskripsi
skusToReplace List<String> Daftar opsional dengan satu SKU yang akan diupgrade atau didowngrade oleh pengguna. Teruskan kolom ini jika pembelian mengupgrade atau mendowngrade langganan yang sudah ada. SKU yang ditentukan diganti dengan SKU yang sedang dibeli oleh pengguna. Google Play menggantikan SKU yang ditentukan di awal siklus penagihan berikutnya.
replaceSkusProration boolean

Menentukan apakah pengguna harus diberikan kredit atas waktu langganan yang tidak terpakai pada SKU yang sedang diupgrade atau didowngrade. Jika Anda menetapkan kolom ini ke true, Google Play menukar SKU lama dan memberikan kredit kepada pengguna dengan nilai waktu langganannya yang tidak terpakai secara prorata. Google Play menerapkan kredit ini ke langganan baru, dan akan mulai menagih pengguna untuk langganan baru setelah kredit habis terpakai.

Jika Anda menyetel kolom ini ke false, pengguna tidak menerima kredit untuk waktu langganan yang tidak terpakai, dan tanggal pengulangan tidak berubah.

Nilai default adalah true. Diabaikan jika Anda tidak meneruskan skusToReplace.

accountId String

String obfuscation opsional secara unik teratribusi dengan akun pengguna di aplikasi Anda. Jika Anda meneruskan nilai ini, Google Play dapat menggunakannya untuk mendeteksi aktivitas yang tidak wajar, seperti banyak perangkat yang melakukan pembelian di akun yang sama dalam waktu singkat.

Kolom ini mirip dengan developerId karena mewakili satu pengguna, tetapi perhatikan bahwa jika Anda memiliki banyak aplikasi, pengguna yang sama dapat memiliki accountId berbeda untuk setiap aplikasi, padahal developerId harus mengidentifikasi secara unik satu pengguna di semua aplikasi Anda.

Jangan gunakan ID developer Konsol Google Play atau ID Google pengguna untuk kolom ini. Selain itu, kolom ini tidak boleh berisi ID pengguna dalam cleartext. Sebaiknya gunakan hash satu arah untuk membuat string dari ID pengguna, dan simpan string yang di-hash di kolom ini.

developerId String

String obfuscation opsional yang secara unik teratribusi dengan akun pengguna di seluruh aplikasi Anda. Kolom ini mirip dengan accountId karena mewakili satu pengguna. Namun, kolom ini harus sama di semua aplikasi Anda untuk pengguna yang sama, sedangkan accountId mungkin unik untuk setiap aplikasi, bahkan untuk pengguna yang sama.

Jangan gunakan ID developer Konsol Google Play atau ID Google pengguna untuk kolom ini. Selain itu, kolom ini tidak boleh berisi ID pengguna dalam cleartext. Sebaiknya gunakan hash satu arah untuk membuat string dari ID pengguna, dan simpan string yang di-hash di kolom ini.

vr boolean

Menentukan apakah intent yang diberikan melambangkan awal alur pembelian virtual reality (VR).

Catatan: Agar parameter tambahan ini berpengaruh pada aplikasi Anda, Anda harus menggunakan AIDL Layanan Penagihan Google Play Versi 7, atau API yang lebih baru.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 6 dan yang lebih baru.

Metode getPurchases()

Metode ini mengembalikan produk yang saat ini tidak dipakai, yang dimiliki oleh pengguna, termasuk item yang dibeli dan item yang diperoleh dengan menukarkan kode promo. Tabel 11 mencantumkan data respons yang ditampilkan di Bundle.

Tabel 11. Data respons dari permintaan getPurchases.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika permintaan berhasil, dan error jika tidak.
INAPP_PURCHASE_ITEM_LIST StringArrayList yang berisi daftar ID produk pembelian dari aplikasi ini.
INAPP_PURCHASE_DATA_LIST StringArrayList yang berisi detail untuk pembelian dari aplikasi ini. Lihat tabel 13 untuk daftar informasi mendetail yang disimpan di setiap item dalam daftar.
INAPP_DATA_SIGNATURE_LIST StringArrayList yang berisi tanda tangan pembelian dari aplikasi ini.
INAPP_CONTINUATION_TOKEN String yang berisi token kelanjutan untuk mengambil kumpulan produk dalam aplikasi berikutnya yang dimiliki oleh pengguna. String ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan di token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya menampilkan pembelian lainnya dan mungkin token kelanjutan lain.

Metode getPurchaseHistory()

Metode ini menampilkan pembelian terbaru yang dilakukan oleh pengguna untuk setiap SKU, meski pembelian tersebut telah berakhir, dibatalkan, atau terpakai. Tabel 12 mencantumkan data respons yang ditampilkan di Bundle:

Tabel 12. Data respons dari permintaan getPurchaseHistory.

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika permintaan berhasil, dan error jika tidak.
INAPP_PURCHASE_ITEM_LIST StringArrayList yang berisi daftar ID produk pembelian dari aplikasi ini.
INAPP_PURCHASE_DATA_LIST StringArrayList yang berisi detail untuk pembelian terbaru dari aplikasi ini. Lihat tabel 6 untuk daftar informasi mendetail yang disimpan di setiap item INAPP_PURCHASE_DATA dalam daftar.
INAPP_DATA_SIGNATURE_LIST StringArrayList yang berisi tanda tangan pembelian dari aplikasi ini.
INAPP_CONTINUATION_TOKEN String yang berisi token kelanjutan untuk mengambil kumpulan produk dalam aplikasi berikutnya yang dimiliki oleh pengguna. String ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan di token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya menampilkan pembelian lainnya dan mungkin token kelanjutan lain.

Tabel 13. Deskripsi kolom JSON untuk histori pembelian yang ditampilkan oleh getPurchaseHistory().

Kolom Deskripsi
productId Kode produk item. Setiap item memiliki ID produk, yang harus Anda tentukan pada daftar produk aplikasi di Konsol Google Play.
purchaseTime Waktu produk dibeli, dalam milidetik sejak waktu acuan (1 Jan 1970).
developerPayload String yang ditentukan developer yang berisi informasi tambahan tentang pesanan. Anda dapat menentukan nilai untuk kolom ini saat melakukan permintaan getBuyIntent.
purchaseToken Token yang secara unik mengidentifikasi pembelian untuk pasangan item dan pengguna tertentu.

Catatan: Metode getPurchaseHistory() memiliki overhead yang lebih tinggi daripada getPurchases(), karena memerlukan panggilan ke server Google Play. Sebaiknya gunakan getPurchases() jika Anda tidak begitu memerlukan histori pembelian pengguna.

Metode ini tersedia dalam AIDL Layanan Penagihan Google Play versi 6 dan yang lebih baru.