Panduan integrasi backend untuk monetisasi di luar Layanan Penagihan Google Play

Google Play Developer API menyertakan fungsi tambahan untuk melaporkan transaksi dari program penagihan dan penautan. Panduan ini menjelaskan cara melaporkan transaksi dari program penagihan ini.

Ada beberapa komponen yang mungkin diperlukan untuk menangani transaksi eksternal dari backend Anda. Untuk membangunnya, Anda perlu menyiapkan integrasi backend seperti yang ditunjukkan dalam Mengonfigurasi Google Play Developer API. Untuk membangun fungsi backend developer yang tidak spesifik untuk penagihan dan program penautan, lihat sistem penagihan Google Play.

Glosarium istilah

Konvensi istilah yang diikuti panduan ini:

• Program penagihan dan penautan: Program yang memfasilitasi pembelian konten digital atau download aplikasi di luar Google Play. Hal ini mencakup program penagihan alternatif dan penawaran eksternal.
• API transaksi eksternal: API yang digunakan untuk melaporkan transaksi untuk program penagihan dan penautan yang memenuhi syarat.
• Transaksi eksternal: Transaksi yang memenuhi syarat yang terjadi di luar aplikasi sebagaimana ditentukan oleh persyaratan program. Hal ini termasuk pembelian konten digital dan download aplikasi.
• Token transaksi eksternal: Token yang diberikan melalui Play Billing Library untuk Anda gunakan saat pengguna menyelesaikan transaksi eksternal. Token ini digunakan untuk memberi tahu Google Play tentang transaksi eksternal yang berhasil.
• ID transaksi eksternal: ID unik yang dibuat oleh Anda untuk mengidentifikasi transaksi eksternal.

Melaporkan transaksi eksternal baru ke Google Play

Integrasikan dengan externaltransactions API untuk melaporkan transaksi yang terjadi di luar sistem penagihan Google Play di negara yang didukung, termasuk transaksi $0 yang dihasilkan dari pembelian uji coba gratis dan penginstalan aplikasi. Anda hanya boleh memulai dan melaporkan transaksi pada program penagihan dan link untuk negara pengguna yang memenuhi syarat sebagaimana diizinkan berdasarkan pedoman penagihan alternatif atau penawaran eksternal. Jika tidak, panggilan API akan ditolak. Batasan ini berlaku untuk semua transaksi, termasuk pembelian baru, perpanjangan, penambahan saldo, upgrade, downgrade, dan download aplikasi.

Pelaporan transaksi eksternal

Anda harus memanggil externaltransactions API untuk melaporkan transaksi eksternal setelah pembayaran diotorisasi melalui program penagihan dan penautan. Hal ini berlaku untuk semua transaksi, termasuk tagihan awal, perpanjangan, pengembalian dana, dan lainnya. Lihat panduan untuk program penagihan dan penautan masing-masing untuk persyaratan pelaporan.

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 harus 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 eksklusif, atau informasi rahasia sebagai bagian dari ID transaksi eksternal ini.

Melaporkan transaksi awal

Setiap kali pembelian baru atau download aplikasi berhasil dalam program penagihan dan penautan, Anda harus memanggil externaltransactions API.

externalTransactionToken yang diterima oleh aplikasi melalui callback UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener, atau BillingProgramReportingDetailsListener diperlukan sebagai bagian dari isi permintaan untuk download aplikasi, pembelian satu kali, dan transaksi pertama kali dalam pembelian berulang (seperti langganan). Hal ini disebut transaksi awal. Setelah transaksi awal, laporkan 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:

1. Developer mengonfigurasi dan mengaktifkan penagihan alternatif dalam aplikasi mereka.
2. Pengguna 1 berada di Korea Selatan, negara yang didukung, dan mencoba membeli product1, seharga 12.634,10 KRW per bulan, dengan penawaran uji coba gratis selama satu bulan.
3. Aplikasi meluncurkan alur pembelian dengan ProductDetails untuk product1 dan penawaran yang dipilih pengguna.
4. Pengguna 1 memilih sistem penagihan alternatif developer.
5. UserChoiceBillingListener menerima nilai my_token sebagai externalTransactionToken.
6. Kemudian, developer akan mengirimkan informasi terkait ke backend mereka (nilai externalTransactionToken dan produk yang dibeli). Kemudian, mereka akan meluncurkan alur pembelian untuk product1 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.
7. 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"
 }
}

Saat melaporkan transaksi awal, perhatikan hal-hal berikut:

• subscriptionType dapat berupa RECURRING (untuk langganan yang diperpanjang otomatis) atau PREPAID (untuk langganan prabayar).
• OtherRecurringProduct harus digunakan untuk merepresentasikan pembelian satu kali yang memerlukan beberapa pembayaran atau pembayaran yang tertunda. Misalnya, praorder mungkin memiliki transaksi awal $0 yang diikuti dengan transaksi kedua di kemudian hari untuk harga SKU saat praorder dipenuhi. Lihat Melaporkan transaksi berikutnya untuk pembelian guna mengetahui detail selengkapnya tentang cara melaporkan transaksi berikutnya.
• Anda harus memberikan ExternalOfferDetails saat melaporkan transaksi penawaran eksternal awal. Tindakan ini tidak diperlukan untuk transaksi berikutnya.

Jika Anda melakukan transaksi dengan pengguna di India yang pajaknya bergantung pada wilayah administratifnya (seperti negara bagian atau provinsi), sertakan wilayah 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"
 }
}

Penawaran eksternal

Jika transaksi yang dilaporkan berada dalam program penawaran eksternal, Anda harus menetapkan kolom externalOfferDetails jika transaksi adalah transaksi satu kali atau transaksi pertama dari rangkaian transaksi berulang:

• Saat melaporkan transaksi download aplikasi, tetapkan linkType ke LINK_TO_APP_DOWNLOAD dan berikan nilai yang sesuai untuk installedAppPackage dan installedAppCategory. Lihat Melaporkan download aplikasi untuk mengetahui detailnya.
• Saat melaporkan transaksi penawaran konten digital, tetapkan linkType ke LINK_TO_DIGITAL_CONTENT.
• Setelah aplikasi eksternal diinstal melalui program penawaran eksternal, Anda harus melaporkan transaksi yang dilakukan di aplikasi eksternal. Saat melaporkan transaksi ini, tautkan transaksi ini ke peristiwa download aplikasi asli:
  • Berikan externalTransactionToken dari peristiwa download aplikasi.
  • Di kolom externalOfferDetails, tetapkan appDownloadEventExternalTransactionId ke externalTransactionId dari peristiwa download aplikasi. Kolom lain di externalOfferDetails tidak wajib diisi.

Contoh permintaan transaksi di aplikasi eksternal yang didownload melalui penawaran eksternal:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "currency": "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode": "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
 }
}

Detail biaya layanan Play yang diperbarui untuk berbagai jenis transaksi dapat ditemukan di bagian Perubahan pada program penawaran eksternal untuk pengguna di Wilayah Ekonomi Eropa (EEA).

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:

1. Perpanjangan pertama Pengguna 1 terjadi pada sistem penagihan alternatif. ID transaksi awal adalah 123-456-789.
2. 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.

Melaporkan download aplikasi

Untuk melaporkan penginstalan aplikasi dalam sistem penagihan penawaran eksternal, Anda harus memanggil Externaltransactions.createexternaltransaction, mengirimkan externalTransactionToken yang diberikan ke aplikasi. Laporkan ini sebagai transaksi satu kali tanpa biaya; proses ini mirip dengan melaporkan transaksi awal. Pastikan untuk menyertakan ExternalOfferDetails dalam isi permintaan.

Contoh permintaan:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": "my_token",
 },
 "userTaxAddress" : {
   "regionCode": "US"
 }
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

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 sebelumnya 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 perlu dimigrasikan, bagilah migrasi langganan ke dalam beberapa hari atau minta penambahan kuota.

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"
 }
}

Persyaratan untuk program partner Play

Developer yang berpartisipasi dalam program partner seperti Program Pengalaman Media Play harus memberikan transaction_program_code saat melaporkan transaksi eksternal. Jika Anda adalah developer yang memenuhi syarat, hubungi Manajer Pengembangan Bisnis Anda untuk mengetahui informasi selengkapnya tentang cara menyetel kolom 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 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 dikembalikan.

Kuota API

Externaltransactions API tunduk pada kuota API 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.