Referensi Penagihan via Google Play

Dokumentasi ini menmberikan informasi referensi teknis terkait penggunaan In-app Billing API.

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 In-app Billing API.

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 Billing API 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 menandakan bahwa aplikasi tidak ditandatangani dengan benar atau disiapkan dengan tepat untuk Penagihan via Google Play, atau tidak memiliki izin yang diperlukan di 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 mengonsumsi karena item tidak dimiliki

Referensi API Dukungan Penagihan

Bagian ini menampilkan metode untuk memperoleh informasi tentang jenis dukungan penagihan via Google Play 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.
  • Penagihan diaktifkan di paket aplikasi Anda.
  • Aplikasi Anda dapat menggunakan jenis item yang diberikan untuk tujuan penagihan.

Tabel 2. Paramater isBillingSupported().

Kunci Jenis Deskripsi
apiVersion int Nomor versi In-app Billing API yang digunakan oleh 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 versi 3 dan versi yang lebih baru dari API penagihan via Google Play.

Metode isBillingSupportedExtraParams()

Metode ini sama persis dengan isBillingSupported(), kecuali bahwa dalam metode ini Anda dapat meneruskan argumen keempat, yaitu Bundle, yang dapat berisi parameter ekstra.

Tabel 3. Parameter isBillingSupportedExtraParams().

Kunci Jenis Deskripsi
apiVersion int Nomor versi In-app Billing API yang digunakan oleh 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 ekstra yang menentukan lebih lanjut jenis penagihan via 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 versi 7 dan versi yang lebih baru dari API penagihan via Google Play.

Referensi API Detail Penagihan

In-app Billing API ditentukan dalam file IInAppBillingService.aidl, yang disertakan dengan contoh aplikasi Versi 3.

Metode getSkuDetails()

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

Tabel 4. GetSkuDetails() parameters.

Kunci Jenis Deskripsi
apiVersion int Nomor versi In-app Billing API yang digunakan oleh 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, Google Play 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", 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 pounds sterling Inggris, price_currency_code adalah "GBP".
title Judul produk.
description Deskripsi produk.
subscriptionPeriod Periode langganan, 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: Dikembalikan 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 lebih lanjut tentang kelayakan uji coba gratis, lihat Langganan dalam aplikasi.

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

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

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

introductoryPriceAmountMicros Harga perkenalan dalam unit mikro. Mata uangnya sama dengan price_currency_code.

Catatan: Dikembalikan 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: Dikembalikan 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 yang akan memulai alur pembelian untuk item dalam aplikasi yang dipetakan ke kunci BUY_INTENT, seperti yang dijelaskan dalam Mengimplementasikan Penagihan via Google Play. Saat menerima PendingIntent, Google Play mengirim Intent respons beserta data untuk pesanan pembelian tersebut. Data yang dikembalikan dalam Intent respons dirangkum pada tabel 6.

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

Tabel 6. Data respons dari permintaan pembelian Penagihan via 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.

Field Deskripsi
autoRenewing Menandakan apakah langganan diperpanjang otomatis. Jika true, langganan aktif, dan akan diperpanjang 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 true untuk semua langganan, selama masa tenggang belum berakhir. Tangga 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 oleh 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()

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

Tabel 8. Parameter consumePurchase().

Kunci Jenis Deskripsi
apiVersion int Nomor versi In-app Billing API yang digunakan oleh aplikasi Anda.
packageName String Nama paket aplikasi yang memanggil metode ini.
purchaseToken String Token dalam JSON informasi pembelian yang mengidentifikasi pembelian yang akan dikonsumsi.

Metode ini mengembalikan RESULT_OK(0) dari konsumsi 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(), kecuali bahwa metode ini mengambil daftar dengan 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 gunakan getBuyIntentExtraParams(), yang menyediakan fungsi tambahan.

Metode ini ditambahkan dengan versi 5 API penagihan via Google Play. 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 per season.

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

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

Kunci Deskripsi
RESPONSE_CODE Nilai adalah 0 jika pembelian berhasil. Jika pembelian gagal, berisi kode error.
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 yang terdiri dari kunci dan nilai opsional yang memengaruhi operasi metode sebagaimana ditampilkan pada tabel 10.

Tabel 10. Parameter getBuyIntentExtraParams() ekstra.

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 menyetel 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 yang secara unik terkait dengan akun pengguna di aplikasi Anda. Jika Anda meneruskan nilai ini, Google Play dapat menggunakannya untuk mendeteksi aktivitas yang tidak wajar, seperti banyak perangkat melakukan pembelian di akun yang sama dalam waktu singkat.

Jangan gunakan ID developer 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 ekstra ini dapat memengaruhi aplikasi, Anda harus menggunakan In-app Billing Version 7 API, atau API yang lebih baru.

Metode ini tersedia dalam In-app Billing API versi 6 dan yang lebih baru.

Metode getPurchases()

Metode ini mengembalikan produk yang saat ini tidak dikonsumsi, 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, 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 pembelian dari aplikasi ini. Lihat tabel 6 untuk daftar informasi mendetail yang tersimpan 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. Ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki oleh pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya mengembalikan pembelian lainnya dan mungkin token kelanjutan lain.

Metode getPurchaseHistory()

Metode ini mengembalikan pembelian terbaru yang dilakukan oleh pengguna untuk tiap SKU, meski pembelian tersebut telah berakhir, dibatalkan, atau dikonsumsi. 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, 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 pembelian baru-baru ini dari aplikasi ini. Lihat tabel 6 untuk daftar informasi mendetail yang tersimpan 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. Ini hanya disetel oleh layanan Google Play jika jumlah produk yang dimiliki oleh pengguna sangat banyak. Jika token kelanjutan ada di respons, Anda harus melakukan panggilan lain ke getPurchases dan meneruskan token kelanjutan yang Anda terima. Panggilan getPurchases berikutnya mengembalikan pembelian lainnya dan mungkin token kelanjutan lain.

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

Field 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 oleh 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 In-app Billing API versi 6 dan yang lebih baru.