Panduan integrasi dalam aplikasi untuk pembayaran eksternal

Dokumen ini menjelaskan cara mengintegrasikan API Library Layanan Penagihan Play untuk menawarkan pembayaran eksternal di aplikasi yang memenuhi syarat. Untuk mempelajari program ini lebih lanjut, lihat persyaratan program.

Penyiapan Play Billing Library

Tambahkan dependensi Play Billing Library ke aplikasi Android Anda. Untuk menggunakan API pembayaran eksternal, Anda harus menggunakan versi 8.3 atau yang lebih tinggi. Jika Anda perlu bermigrasi dari versi sebelumnya, ikuti petunjuk dalam panduan migrasi untuk melakukan upgrade sebelum memulai integrasi.

Melakukan inisialisasi klien penagihan

Langkah-langkah pertama dalam proses integrasi sama dengan langkah-langkah yang dijelaskan dalam panduan integrasi Layanan Penagihan Google Play, dengan beberapa modifikasi saat melakukan inisialisasi BillingClient Anda:

• Anda perlu memanggil metode enableBillingProgram(EnableBillingProgramParams) baru untuk menunjukkan bahwa Anda ingin menawarkan pembayaran eksternal.
• Anda harus mendaftarkan DeveloperProvidedBillingListener untuk menangani kasus ketika pengguna memilih membayar di situs Anda atau aplikasi pembayaran.

Contoh berikut menunjukkan inisialisasi BillingClient dengan modifikasi ini:

val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // Handle new Google Play purchase.
    }

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

Menghubungkan ke Google Play

Setelah melakukan inisialisasi BillingClient, hubungkan ke Google Play seperti yang dijelaskan dalam Menghubungkan ke Google Play.

Memeriksa kelayakan pengguna

Setelah terhubung ke Google Play, Anda dapat memeriksa apakah pengguna memenuhi syarat untuk program pembayaran eksternal dengan memanggil metode isBillingProgramAvailableAsync(). Metode ini akan menampilkan BillingResponseCode.OK jika pengguna memenuhi syarat. Contoh berikut menunjukkan cara memeriksa kelayakan:

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return
        }

        // External payments are available. Can proceed with generating an
        // external transaction token.
})

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

Lihat bagian penanganan respons untuk mengetahui detail tentang cara aplikasi Anda merespons kode respons lainnya. Jika menggunakan ekstensi Kotlin, Anda dapat menggunakan coroutine Kotlin sehingga tidak perlu menentukan pemroses terpisah.

Menampilkan produk yang tersedia

Anda dapat menampilkan produk yang tersedia kepada pengguna dengan cara yang sama seperti integrasi sistem penagihan Google Play. Setelah pengguna melihat produk yang tersedia untuk dibeli dan memilih produk yang akan dibeli, luncurkan alur pembayaran eksternal seperti yang dijelaskan di bagian meluncurkan alur pembayaran eksternal.

Menyiapkan token transaksi eksternal

Untuk melaporkan transaksi eksternal ke Google Play, Anda harus memiliki token transaksi eksternal yang dihasilkan dari Play Billing Library. Token transaksi eksternal baru harus dibuat setiap kali pengguna mengunjungi situs atau aplikasi eksternal melalui API pembayaran eksternal. Hal ini dapat dilakukan dengan memanggil createBillingProgramReportingDetailsAsync API. Token harus dibuat tepat sebelum launchBillingFlow dipanggil.

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
    }
})

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

Jika menggunakan ekstensi Kotlin, Anda dapat menggunakan coroutine Kotlin sehingga Anda tidak perlu menentukan pemroses terpisah.

Meluncurkan alur pembayaran eksternal

Luncurkan alur pembayaran eksternal dengan memanggil launchBillingFlow() mirip dengan meluncurkan alur pembelian dengan integrasi sistem penagihan Google Play, tetapi dengan parameter tambahan DeveloperBillingOptionParams yang diberikan untuk menunjukkan bahwa aplikasi Anda ingin mengaktifkan alur pembayaran eksternal untuk pembelian ini.

DeveloperBillingOptionParams harus berisi hal berikut:

• billingProgram ditetapkan ke program penagihan EXTERNAL_PAYMENTS
• linkURI ditetapkan ke tujuan link
• launchMode disetel ke LAUNCH_IN_EXTERNAL_BROWSER_OR_APP jika Google Play harus meluncurkan link atau CALLER_WILL_LAUNCH_LINK jika aplikasi Anda akan meluncurkan link.

Saat aplikasi Anda memanggil launchBillingFlow() dengan DeveloperBillingOptionParams yang diberikan, sistem penagihan Google Play akan menjalankan pemeriksaan berikut:

• Sistem akan memeriksa apakah negara Google Play pengguna adalah negara yang mendukung pembayaran eksternal (yaitu negara yang didukung). Jika negara Google Play pengguna didukung, Google Play akan memeriksa apakah pembayaran eksternal diaktifkan berdasarkan konfigurasi BillingClient dan apakah DeveloperBillingOptionParams diberikan.
  • Jika pembayaran eksternal telah diaktifkan, alur pembelian akan menampilkan UX pilihan pengguna.
  • Jika pembayaran eksternal tidak diaktifkan, alur pembelian akan menampilkan UX sistem penagihan Google Play standar, tanpa pilihan pengguna.
• Jika negara Google Play pengguna bukan negara yang didukung, alur pembelian akan menampilkan UX sistem penagihan Google Play standar, tanpa pilihan pengguna.

Cuplikan berikut menunjukkan cara membuat DeveloperBillingOptionParams:

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase")
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

Menangani pilihan pengguna

Cara Anda menangani alur pembelian lainnya berbeda-beda bergantung pada apakah pengguna memilih sistem penagihan Google Play atau membayar di situs Anda.

Saat pengguna memilih untuk membayar di situs Anda atau di aplikasi pembayaran

Jika pengguna memilih untuk membayar di situs Anda, Google Play akan memanggil DeveloperProvidedBillingListener untuk memberi tahu aplikasi bahwa pengguna memilih untuk membayar di situs Anda atau di aplikasi pembayaran. Secara khusus, metode onUserSelectedDeveloperBilling() akan dipanggil.

Jika aplikasi Anda menyetel launchMode ke LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play akan meluncurkan link. Jika launchMode disetel ke CALLER_WILL_LAUNCH_LINK, aplikasi Anda bertanggung jawab untuk meluncurkan link. Saat menautkan pengguna ke aplikasi pembayaran, Anda bertanggung jawab untuk memeriksa apakah pengguna telah menginstal aplikasi pembayaran di perangkatnya.

Gunakan token ini untuk melaporkan transaksi apa pun yang dihasilkan dari pilihan ini, seperti yang dijelaskan dalam panduan integrasi backend.

Saat pengguna memilih sistem penagihan Google Play

Jika pengguna memilih sistem penagihan Google Play, mereka akan melanjutkan pembelian melalui Google Play.

• Lihat Memproses pembelian dalam panduan integrasi library untuk mengetahui informasi selengkapnya tentang cara menangani pembelian dalam aplikasi baru melalui sistem penagihan Google Play.
• Lihat Langganan baru dalam panduan pengelolaan langganan untuk mendapatkan panduan tambahan tentang pembelian langganan.

Menangani perubahan pada langganan

Untuk developer yang menggunakan pembayaran eksternal, pembelian harus diproses melalui sistem penagihan Google Play atau dilaporkan dengan externalTransactionId, bergantung pada pilihan pengguna. Perubahan pada langganan yang ada dan diproses melalui situs developer dapat dilakukan melalui sistem penagihan yang sama hingga masa berlakunya habis.

Bagian ini menjelaskan cara menangani beberapa skenario perubahan langganan yang umum.

Alur upgrade dan downgrade

Perubahan paket langganan, termasuk alur upgrade dan downgrade, harus ditangani secara berbeda, bergantung pada apakah langganan awalnya dibeli melalui sistem penagihan Google Play atau melalui situs developer.

Add-on yang bergantung pada langganan yang ada, menggunakan metode pembayaran yang sama, dan menyelaraskan tagihan berulang ditangani sebagai upgrade. Untuk add-on lainnya, pengguna harus dapat memilih sistem penagihan yang ingin mereka gunakan. Mulai pengalaman pembelian baru dengan menggunakan launchBillingFlow(), seperti yang dijelaskan dalam meluncurkan alur pembayaran eksternal.

Langganan yang dibeli melalui situs developer atau aplikasi pembayaran

Untuk langganan yang awalnya dibeli melalui situs developer atau aplikasi pembayaran setelah pilihan pengguna, pengguna yang meminta upgrade atau downgrade harus melanjutkan melalui situs developer atau aplikasi pembayaran tanpa melalui pengalaman pilihan pengguna lagi.

Untuk melakukannya, panggil launchBillingFlow() saat pengguna meminta upgrade atau downgrade. Daripada menentukan parameter lain di objek SubscriptionUpdateParams, gunakan setOriginalExternalTransactionId(), yang memberikan ID transaksi eksternal untuk pembelian asli.

DeveloperBillingOptionParams juga harus diberikan dalam panggilan ini. Cara ini tidak menampilkan layar pilihan pengguna, mengingat pilihan pengguna untuk pembelian asli dipertahankan untuk upgrade dan downgrade. Anda harus membuat token transaksi eksternal baru untuk transaksi ini seperti yang dijelaskan di sini.

Setelah upgrade atau downgrade dilakukan menggunakan situs developer atau aplikasi pembayaran, Anda harus melaporkan transaksi baru menggunakan token transaksi eksternal yang diperoleh melalui panggilan sebelumnya untuk pembelian langganan baru.

Langganan yang dibeli melalui sistem penagihan Google Play

Demikian pula, pengguna yang membeli langganan mereka saat ini melalui sistem penagihan Google Play setelah pilihan pengguna akan melihat alur Penagihan Google Play standar. DeveloperBillingOptionParams tidak boleh ditetapkan dalam panggilan ke launchBillingFlow.

Pembatalan dan pemulihan langganan

Pengguna harus dapat membatalkan langganan mereka kapan saja. Saat pengguna membatalkan langganan, penghentian hak dapat ditangguhkan hingga periode berbayar berakhir. Misalnya, jika pengguna membatalkan langganan bulanan pada pertengahan bulan, mereka dapat terus mengakses layanan selama sisa ~2 minggu hingga aksesnya dihapus. Selama periode ini, langganan masih aktif secara teknis, sehingga pengguna dapat menggunakan layanan.

Tidak jarang pengguna memutuskan untuk membatalkan pembatalan selama periode aktif ini. Dalam panduan ini, hal ini disebut pemulihan. Bagian berikut menjelaskan cara menangani skenario pemulihan dalam integrasi API pembayaran eksternal Anda.

Langganan yang dibeli melalui situs developer

Jika memiliki ID transaksi eksternal untuk langganan yang dibatalkan, Anda tidak perlu memanggil launchBillingFlow() untuk memulihkan langganan, sehingga tidak boleh digunakan untuk jenis aktivasi ini. Jika pengguna memulihkan langganan mereka saat masih dalam periode aktif langganan yang dibatalkan, tidak ada transaksi yang terjadi pada saat itu. Anda dapat terus melaporkan perpanjangan saat siklus saat ini berakhir dan perpanjangan berikutnya terjadi. Hal ini mencakup kasus saat pengguna menerima kredit atau harga perpanjangan khusus sebagai bagian dari pemulihan (misalnya, promosi untuk mendorong pengguna agar melanjutkan langganannya).

Langganan yang dibeli melalui sistem penagihan Google Play

Umumnya, pengguna dapat memulihkan langganan di sistem penagihan Google Play. Untuk langganan yang dibatalkan yang awalnya dibeli di sistem penagihan Google Play, pengguna dapat memilih untuk mengurungkan pembatalan saat langganan masih aktif melalui fitur Berlangganan lagi Google Play. Dalam hal ini, Anda akan menerima Notifikasi Developer Real Time SUBSCRIPTION_RESTARTED di backend Anda, dan token pembelian baru tidak diterbitkan—token asli akan digunakan untuk melanjutkan langganan. Untuk mempelajari cara mengelola pemulihan di sistem penagihan Google Play, lihat Pemulihan di panduan pengelolaan langganan.

Anda juga dapat memicu pemulihan di sistem penagihan Google Play dari aplikasi dengan memanggil launchBillingFlow(). Lihat Sebelum akhir masa berlaku langganan - dalam aplikasi untuk mendapatkan penjelasan tentang cara melakukannya. Dalam kasus pengguna yang melalui alur pilihan pengguna untuk pembelian asli (yang dibatalkan tetapi masih aktif), sistem akan otomatis mendeteksi pilihan pengguna dan menampilkan antarmuka pengguna untuk memulihkan pembelian ini. Mereka diminta untuk mengonfirmasi pembelian kembali langganan melalui Google Play, tetapi tidak perlu melalui alur pilihan pengguna lagi. Dalam hal ini, token pembelian baru akan dikeluarkan untuk pengguna. Backend Anda akan menerima Notifikasi Developer Real Time SUBSCRIPTION_PURCHASED, dan nilai linkedPurchaseToken untuk status pembelian baru akan ditetapkan seperti dalam kasus upgrade atau downgrade, dengan token pembelian lama untuk langganan yang dibatalkan.

Berlangganan lagi

Jika langganan benar-benar berakhir, baik karena pembatalan atau penolakan pembayaran tanpa pemulihan (penangguhan akun yang telah habis masa berlakunya), pengguna harus berlangganan lagi jika ingin memulai ulang hak.

Berlangganan lagi juga dapat diaktifkan melalui aplikasi dengan memprosesnya seperti halnya pendaftaran standar. Pengguna harus dapat memilih sistem penagihan yang ingin mereka gunakan. launchBillingFlow() dapat dipanggil dalam kasus ini, seperti yang dijelaskan dalam meluncurkan alur pembayaran eksternal.

Penanganan respons

Jika terjadi error, metode isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync(), launchBillingFlow() mungkin memberikan BillingResponseCode selain BillingResponseCode.OK. Pertimbangkan penanganan kode respons ini sebagai berikut:

• BillingResponseCode.ERROR: Ini adalah error internal. Jangan melanjutkan transaksi atau membuka situs eksternal. Coba lagi dengan memanggil API lagi.
• BillingResponseCode.FEATURE_NOT_SUPPORTED: API pembayaran eksternal tidak didukung oleh Play Store di perangkat saat ini. Jangan melanjutkan transaksi atau membuka situs eksternal.
• BillingResponseCode.DEVELOPER_ERROR: Terjadi error pada permintaan. Gunakan pesan debug untuk mengidentifikasi dan memperbaiki error sebelum melanjutkan.
• BillingResponseCode.USER_CANCELED: Jangan lanjutkan pembukaan situs atau aplikasi eksternal. Panggil launchBillingFlow() lagi untuk menampilkan dialog informasi kepada pengguna saat Anda mencoba mengarahkan pengguna ke luar aplikasi lagi.
• BillingResponseCode.BILLING_UNAVAILABLE: Transaksi tidak memenuhi syarat untuk pembayaran eksternal, sehingga penagihan developer tidak akan tersedia dalam program ini. Hal ini disebabkan karena pengguna tidak berada di negara yang memenuhi syarat untuk program ini atau akun Anda belum berhasil terdaftar dalam program ini. Jika disebabkan oleh pendaftaran belum berhasil, periksa status pendaftaran Anda di Konsol Play.
• BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: Ini adalah error sementara yang harus ditangani dengan kebijakan percobaan ulang yang sesuai. Jika SERVICE_DISCONNECTED ditampilkan, buat kembali koneksi dengan Google Play sebelum mencoba lagi.

Menguji link pembayaran eksternal

Penguji lisensi harus digunakan untuk menguji integrasi pembayaran eksternal Anda. Anda tidak akan ditagih untuk transaksi yang telah dimulai oleh akun penguji lisensi. Lihat Menguji penagihan via Google Play dengan pemberian lisensi aplikasi untuk mengetahui informasi selengkapnya tentang mengonfigurasi penguji lisensi.

Langkah berikutnya

Setelah menyelesaikan integrasi dalam aplikasi, Anda siap untuk mengintegrasikan backend.