Google Play Developer API kini menyertakan fungsi untuk melaporkan transaksi dari penagihan alternatif atau penawaran eksternal. Panduan ini menjelaskan cara melaporkan alternatif penagihan atau penawaran eksternal.
Ada beberapa komponen yang mungkin diperlukan untuk menangani pembelian dalam aplikasi Anda dari backend. Untuk membangunnya, Anda perlu menyiapkan integrasi backend seperti yang ditunjukkan dalam Mengonfigurasi Google Play Developer API. Sebagai semua fungsi backend developer yang tidak spesifik untuk penagihan alternatif atau API penawaran eksternal, 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
negara yang didukung, termasuk transaksi $0 yang dihasilkan dari uji coba gratis
pembelian. Transaksi pada penagihan alternatif atau sistem penawaran eksternal
sebaiknya hanya dimulai dan dilaporkan untuk negara pengguna yang memenuhi syarat sebagaimana diizinkan
dalam penagihan alternatif atau
program penawaran eksternal, atau panggilan API akan
ditolak. Hal ini berlaku untuk semua transaksi, termasuk pembelian baru, perpanjangan,
tambah saldo, upgrade, downgrade, dan lainnya.
Pelaporan transaksi eksternal
Anda harus memanggil Externaltransactions API
untuk melaporkan transaksi eksternal
setelah pembayaran diotorisasi melalui penagihan alternatif atau
sistem penawaran eksternal. Ini berlaku untuk semua transaksi, termasuk transaksi awal
tagihan, 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 informasi, hak milik, atau informasi rahasia sebagai bagian dari ID transaksi.
Melaporkan pembelian baru
Setiap kali pembelian baru berhasil dalam penagihan alternatif
atau sistem penawaran eksternal, panggilan ke Externaltransactions
API akan
tidak diperlukan. Untuk pembelian baru ini, Anda harus memberikan atribut unik
externalTransactionId
yang terkait dengan pembelian di backend Anda sebagai kueri
. externalTransactionId
ini tidak dapat digunakan kembali dalam
ID paket.
externalTransactionToken
yang diterima oleh aplikasi melalui
UserChoiceBillingListener
, AlternativeBillingOnlyReportingDetailsListener
,
atau callback ExternalOfferReportingDetailsListener
juga diperlukan sebagai bagian dari
isi permintaan untuk pembelian satu kali dan transaksi pertama kali dalam
pembelian berulang (seperti langganan). Dalam kedua kasus tersebut, ini disebut
transaksi awal. Setelah transaksi awal,
externalTransactionToken
tidak lagi diperlukan, dan Anda akan melaporkan
transaksi (seperti perpanjangan langganan) dengan memberikan penawaran unik
externalTransactionId
. Lihat Melaporkan transaksi berikutnya untuk pembelian
untuk mengetahui detail selengkapnya tentang cara melaporkan transaksi berikutnya.
Contoh:
- Developer mengonfigurasi dan mengaktifkan penagihan alternatif dalam aplikasi mereka.
- Pengguna 1 berada di Korea Selatan, negara yang didukung, dan mencoba membeli
product1
, seharga 12.634,10 KRW/bulan, dengan penawaran uji coba gratis selama satu bulan. - Aplikasi meluncurkan alur pembelian dengan
ProductDetails
untukproduct1
dan penawaran yang dipilih pengguna. - Pengguna 1 memilih sistem penagihan alternatif developer.
UserChoiceBillingListener
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 untukproduct1
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",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
Jika melakukan transaksi dengan pengguna yang bertempat tinggal di India, dengan pajak yang bervariasi bergantung pada wilayah administratifnya (seperti negara bagian atau provinsi), pastikan untuk menyertakan area tersebut di bagian userTaxAddress. Lihat daftar string yang telah ditentukan sebelumnya dalam panduan referensi API untuk wilayah administratif yang berlaku.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "INR"
},
"transactionTime" : "2023-11-01T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken": "my_token",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
# Tax varies in India based on state, so include that information in
# administrativeArea
"regionCode": "IN"
"administrativeArea": "KERALA"
}
}
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 awal 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",
"externalSubscription" {
"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.
Bermigrasi dari pelaporan manual transaksi penagihan alternatif
Untuk memigrasikan langganan aktif yang dimulai saat Anda menawarkan penagihan
alternatif tanpa pelaporan otomatis, buat transaksi baru tanpa biaya menggunakan
kolom migratedTransactionProgram
, bukan menentukan
initialExternalTransactionId
atau externalTransactionToken
. Tetapkan
transactionTime
ke waktu saat pengguna pertama kali mendaftar untuk setiap langganan
aktif. Setelah itu, laporkan setiap transaksi berikutnya untuk
langganan ini seperti biasa melalui API, sehingga memberikan
initialExternalTransactionId
yang digunakan di atas untuk membuat transaksi perpanjangan.
Setelah langganan dimigrasikan, Anda tidak perlu lagi melaporkan
transaksi berikutnya secara manual untuk langganan, asalkan transaksi tersebut
dilaporkan melalui metode otomatis yang dijelaskan di halaman ini.
Saat memigrasikan langganan, perhatikan batas kuota yang diterapkan untuk memastikan migrasi tidak menyebabkan gangguan kuota. Jika banyak langganan memerlukan dimigrasikan, sebarkan ke beberapa hari atau minta peningkatan dalam kuota kami.
Kolom migratedTransactionProgram
hanya dapat digunakan saat bermigrasi dari
pelaporan manual. Kolom ini tidak akan digunakan lagi jika pelaporan manual tidak lagi
didukung.
Contoh permintaan:
# Note that the externalTransactionId specified here will used to report subsequent
# transactions.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
# Be sure to set the price to 0 for this transaction since it does not reflect
# an actual subscription renewal.
"originalPreTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "0",
"currency": "KRW"
},
# The transaction time should be set to when the user signed up for this
# subscription.
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"migratedTransactionProgram": "USER_CHOICE_BILLING",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
Melaporkan program partner Play
Developer yang berpartisipasi dalam program partner seperti
Program Pengalaman Media Google Play harus menyediakan
transaction_program_code
saat melaporkan transaksi eksternal. Jika Anda
developer yang memenuhi syarat, hubungi Pengelola Pengembangan Bisnis Anda untuk mengetahui
informasi tentang cara
menetapkan {i>field<i} ini.
Melaporkan pengembalian dana pembelian ke Google Play
Integrasikan dengan Externaltransactions
API untuk melaporkan transaksi yang dananya
dikembalikan kepada pengguna di luar sistem penagihan Google Play. Agar Play dapat mengidentifikasi dengan benar
transaksi mana yang dananya telah dikembalikan, 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 atas 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 laporan transaksi) dan pengembalian dana sebagian (dengan jumlah yang lebih kecil dari yang dibayarkan pengguna dalam laporan eksternal transaksi). Untuk pengembalian dana sebagian, Anda harus menentukan jumlah yang dikembalikan yang belum dikenakan pajak.
Kuota API
Externaltransactions
API tunduk pada kuota API harian
untuk semua panggilan, sama 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.