Google Play Developer API kini menyertakan fungsi tambahan untuk melaporkan transaksi dari sistem penagihan alternatif. Panduan ini menjelaskan cara menggunakan fungsi baru untuk melaporkan transaksi penagihan alternatif.
Ada beberapa komponen yang mungkin diperlukan untuk menangani pembelian dalam aplikasi Anda dari backend. Untuk mem-build-nya, Anda perlu menyiapkan integrasi backend seperti yang ditunjukkan dalam Mengonfigurasi Google Play Developer API. Untuk semua fungsi backend developer yang tidak spesifik untuk API penagihan alternatif, petunjuk dari dokumentasi sistem penagihan Google Play berlaku.
Melaporkan transaksi eksternal baru ke Google Play
Mengintegrasikan dengan
Externaltransactions APIs
untuk melaporkan transaksi yang terjadi di luar sistem penagihan Google Play di
Korea Selatan, termasuk transaksi $0 yang dihasilkan dari pembelian uji coba gratis.
Transaksi pada sistem penagihan alternatif hanya boleh dilaporkan untuk
negara pengguna yang memenuhi syarat, dan dalam kasus lain, panggilan API gagal. Batasan ini
berlaku untuk semua transaksi, termasuk pembelian baru, perpanjangan,
penambahan saldo, upgrade, downgrade, dan lainnya.
Pelaporan transaksi eksternal
Anda harus memanggil Externaltransactions API
untuk melaporkan transaksi eksternal
setelah pembayaran diotorisasi melalui sistem penagihan alternatif.
Hal ini berlaku untuk semua transaksi, termasuk tagihan awal, perpanjangan, pengembalian dana,
dan lainnya. Semua transaksi harus dilaporkan dalam waktu 24 jam setelah
transaksi terjadi.
Setiap transaksi eksternal dilaporkan dengan ID transaksi eksternal. Untuk pembelian berulang (seperti langganan yang dapat diperpanjang otomatis), Anda harus mengirimkan ID transaksi eksternal yang terkait dengan transaksi pertama dalam pembelian berulang sebagai parameter untuk transaksi berikutnya, termasuk pengembalian dana. Tindakan ini akan mencatat rangkaian transaksi untuk pembelian tersebut. Anda mengirim ID transaksi eksternal baru untuk pembelian saat produk berubah (seperti upgrade atau downgrade), atau jika transaksi berulang dibatalkan atau habis masa berlakunya dan produk yang sama dibeli lagi nanti. Anda tidak boleh menyertakan informasi identitas pribadi apa pun sebagai bagian dari ID transaksi eksternal ini.
Melaporkan pembelian baru
Setiap kali pembelian baru berhasil dalam sistem penagihan alternatif,
panggilan ke Externaltransactions
API diperlukan. Untuk pembelian baru ini,
Anda harus menyediakan externalTransactionId
unik yang terkait dengan
pembelian di backend sebagai parameter kueri. externalTransactionId
ini
tidak dapat digunakan kembali dalam ID paket aplikasi yang sama.
externalTransactionToken
yang diterima oleh aplikasi melalui
callback AlternativeBillingListener
juga diperlukan sebagai bagian dari isi permintaan
untuk pembelian satu kali dan transaksi pertama kali dalam pembelian berulang
(seperti langganan). Dalam kedua kasus itu, ini disebut transaksi
awal. Setelah transaksi awal, externalTransactionToken
tidak lagi diperlukan, dan Anda melaporkan transaksi berikutnya (seperti
perpanjangan langganan) dengan memberikan externalTransactionId
unik yang baru. Lihat
Melaporkan transaksi berikutnya untuk pembelian guna mengetahui detail
selengkapnya tentang cara melaporkan transaksi berikutnya.
Contoh:
- Developer mengonfigurasi dan mengaktifkan penagihan alternatif dalam aplikasi mereka.
- Pengguna 1 berada di Korea Selatan dan mencoba membeli
product1
seharga 12634,10 KRW/bulan, dengan penawaran uji coba gratis satu bulan. - Aplikasi meluncurkan alur pembelian dengan
ProductDetails
untukproduct1
dan penawaran yang dipilih pengguna. - Pengguna 1 memilih sistem penagihan alternatif developer.
AlternativeBillingListener
menerima nilaimy_token
sebagaiexternalTransactionToken
.- Kemudian, developer akan mengirimkan informasi terkait ke backend mereka
(nilai
externalTransactionToken
dan produk yang dibeli). Kemudian, mereka akan meluncurkan alur pembelian untukproduct
dalam sistem penagihan alternatif. Transaksi ini diberi ID transaksi unik pada sisi developer yang digunakan untuk melaporkannya ke Google Play: 123-456-789. ID transaksi diperlukan, meskipun pengguna menerima uji coba gratis. - Setelah transaksi untuk pembelian terjadi dalam sistem penagihan alternatif, developer melaporkan transaksi ke Google Play dengan permintaan berikut. Awalnya, transaksi ini dilaporkan sebagai transaksi nol dolar karena pengguna mendapatkan satu bulan gratis.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"external_subscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
Melaporkan transaksi berikutnya untuk pembelian
Dalam beberapa kasus, ada lebih dari satu pembayaran pengguna yang terkait dengan pembelian eksternal
yang sama (misalnya, perpanjangan langganan atau penambahan saldo paket prabayar).
Anda dapat melaporkan transaksi berikutnya dengan menggunakan API
yang sama di Externaltransactions
. Seperti dijelaskan dalam Melaporkan pembelian
baru, externalTransactionToken
tidak diperlukan untuk
transaksi berikutnya. Sebagai gantinya, externalTransactionId
unik yang baru akan dikirim
sebagai parameter kueri untuk setiap transaksi perpanjangan atau penambahan saldo, dengan ID
transaksi awal yang disertakan di kolom initialExternalTransactionId
.
Mengikuti contoh sebelumnya:
Perpanjangan pertama Pengguna 1 terjadi pada sistem penagihan alternatif. ID transaksi asli adalah 123-456-789.
Developer melaporkan pengulangan transaksi di parameter kueri URL sebagai ID transaksi eksternal untuk transaksi baru ini, sekaligus merujuk ID transaksi eksternal dari transaksi awal di kolom
initialExternalTransactionId
.
Contoh permintaan:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
"originalPreTaxAmount" : {
"priceMicros": "12634000000",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "1263000000",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId": "123-456-789",
"external_subscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
Melaporkan upgrade atau downgrade
Untuk melaporkan upgrade atau downgrade saat pengguna memiliki langganan dalam
sistem penagihan alternatif, Anda menggunakan endpoint dan fungsi yang sama di
Externaltransactions
API, yang mengirimkan externalTransactionToken
yang
diberikan ke aplikasi untuk transaksi upgrade atau downgrade. Cara kerjanya
serupa dengan melaporkan pembelian baru.
Melaporkan pengembalian dana pembelian ke Google Play
Mengintegrasikan dengan Externaltransactions
API untuk melaporkan transaksi
yang dikembalikan dananya kepada pengguna di luar sistem penagihan Google Play. Agar Play dapat
mengidentifikasi dengan benar transaksi mana yang telah dikembalikan dananya, Anda harus menyertakan
externalTransactionId
yang sesuai untuk transaksi yang dilaporkan sebelumnya sebagai
bagian dari parameter URL.
Saat melaporkan pengembalian dana pembelian langganan, referensikan
externalTransactionId
pengulangan spesifik langganan yang
dikembalikan dananya.
Contoh: Misalkan langganan memiliki transaksi berikut:
Transaksi awal dengan ID transaksi eksternal ABC.1234-5678-9012-34567
Transaksi berulang pertama dengan ID transaksi eksternal ABC.1234-5678-9012-34567..0
Transaksi berulang kedua dengan ID transaksi eksternal ABC.1234-5678-9012-34567..1
Untuk melaporkan pengembalian dana semua transaksi untuk langganan, Anda harus membuat tiga permintaan pengembalian dana terpisah: satu untuk transaksi awal dan dua untuk transaksi berikutnya.
Metode ini menerima pengembalian dana penuh (dengan jumlah yang sama dengan yang dibayarkan pengguna dalam transaksi eksternal asli) dan pengembalian dana sebagian (dengan jumlah yang lebih kecil dari yang dibayarkan pengguna dalam transaksi eksternal asli). Untuk pengembalian dana sebagian, Anda harus menentukan jumlah sebelum pajak yang dananya dikembalikan.
Kuota API
Externaltransactions
API tunduk pada
kuota API harian
untuk semua panggilan, seperti endpoint lainnya di Google Play Developer API.
Selain itu, Externaltransactions
API memiliki batas 1.200 Kueri Per Menit
(QPM) pada panggilan ke Externaltransactions.createexternaltransaction
atau
Externaltransactions.refundexternaltransaction
. Panggilan ke
Externaltransactions.getexternaltransaction
tidak mengurangi
batas 1.200 QPM ini.