Skip to main content
Halaman ini membahas SDK checkout React Native resmi Dodo Payments, @dodopayments/react-native-checkout. SDK ini membuka checkout hosted Dodo Payments dalam tampilan browser native dan mengembalikan hasil bertipe. Paket yang lebih lama, dodopayments-react-native-sdk (tanpa scope), memiliki API yang berbeda. Halaman ini hanya mendokumentasikan paket dengan scope.

Checkout Sessions API

Buat checkout_url yang dibuka SDK ini dari backend Anda.

Mobile Integration Guide

Lihat bagaimana SDK ini menjadi bagian dari alur pembayaran mobile secara lengkap.
SDK React Native adalah Turbo Module yang membungkus SDK checkout native iOS dan Android. SDK ini membuka SFSafariViewController di iOS dan Custom Tab di Android. SDK ini tidak menyimpan API key dan tidak memiliki logika checkout sendiri, sehingga tidak pernah memanggil API Dodo Payments. Checkout berjalan di tampilan browser. SDK menampilkan dan menutup tampilan tersebut serta membaca hasil dari return URL.
SDK ini hanya mendukung New Architecture. SDK ini memerlukan React Native 0.77 atau yang lebih baru, iOS 16 atau yang lebih baru, dan Android minSdk 24. Aplikasi Android Anda harus dibangun dengan compileSdk 34 atau yang lebih baru.

Instalasi

1

Install the Package

Paket ini terhubung secara otomatis dan mengambil com.dodopayments.api:checkout-android dari Maven Central.
Dependensi native diselesaikan secara otomatis, sehingga tidak diperlukan langkah instalasi lainnya.
Kustomisasi tampilan memerlukan versi 1.2.0 atau yang lebih baru.
2

Register a Callback URL Scheme

Daftarkan URL scheme agar sistem operasi mengarahkan return URL checkout kembali ke aplikasi Anda.
Tetapkan scheme sebagai manifest placeholder di android/app/build.gradle:
android/app/build.gradle
Ganti "myapp" dengan scheme aplikasi Anda.
Di setiap platform, tetapkan URL yang sama dengan return_url milik checkout session saat backend Anda membuat session. SDK mencocokkan return URL berdasarkan scheme, host, dan path. URL tersebut tidak perlu memuat halaman sungguhan.

Penggunaan

Panggil DodoCheckout.start dengan checkout_url dari backend Anda:
onEvent menerima event dengan type berupa checkout.opened, checkout.return_received, atau checkout.closed. Gunakan hanya untuk logging, jangan untuk menentukan hasil.

Meneruskan Return URL

iOS memerlukan listener Linking untuk menangani return URL, karena SFSafariViewController tidak dapat menangkap return URL miliknya sendiri. Di Android, handleOpenURL tidak melakukan apa pun dan mengembalikan false, karena Android SDK menangkap redirect secara native. Anda dapat mendaftarkan listener di kedua platform.
Di iOS, handleOpenURL mengembalikan true saat URL tersebut merupakan milik checkout yang sedang berlangsung, dan false untuk URL lainnya.

Arti Hasil

SDK membangun hasil dari query parameters pada return URL.
result.status adalah petunjuk UI, bukan bukti pembayaran. Konfirmasikan setiap pembayaran dari backend Anda, menggunakan webhook payment.succeeded atau subscription.active.
CheckoutStatus
wajib
Salah satu dari lima nilai berikut:
  • succeeded: return URL memiliki status=succeeded (pembayaran satu kali) atau status=active (subscription).
  • failed: pembayaran ditolak (status=failed).
  • cancelled: customer menutup tampilan browser sebelum return URL diterima. SDK tidak mengetahui hasilnya, dan pembayaran mungkin berhasil, jadi jangan tampilkan layar kegagalan. Rekonsiliasikan abandoned session sebagai gantinya.
  • pending: pembayaran diselesaikan kemudian (status=processing atau nilai requires_* lainnya), atau parameter status tidak ada atau tidak dikenali. Rekonsiliasikan seperti cancelled.
  • expired: checkout session kedaluwarsa (status=expired).
string
Parameter query payment_id, jika return URL menyertakannya. Tampilkan di UI Anda, tetapi jangan gunakan untuk memberikan akses. Lihat Verifikasi Pembayaran.
string
Parameter query subscription_id. Ditetapkan untuk subscription checkout.
string[]
Parameter query license_key. Ditetapkan saat checkout menyertakan produk license key.
string
Parameter query email. Ditetapkan saat checkout mengambil alamat email.
Record<string, string>
Setiap query parameter dari return URL, apa adanya.

Verifikasi Pembayaran

Webhooks

Dodo Payments memanggil backend Anda saat pembayaran berhasil atau subscription aktif.

Get Payment Detail

Cari paymentId dengan secret key Anda untuk memeriksa statusnya.
Berikan akses hanya setelah salah satu hal berikut mengonfirmasi pembayaran. Jangan hanya mengandalkan result.status.

Kustomisasi Tampilan

Untuk mengubah toolbar, tombol, dan skema warna browser checkout, berikan customization ke start(...). Android Custom Tabs dan SFSafariViewController di iOS menyediakan kontrol native yang berbeda, sehingga opsi dikelompokkan ke dalam objek android dan objek ios. Setiap platform hanya membaca objeknya sendiri. Semua field bersifat opsional. Jika field tidak disertakan, platform akan menerapkan nilai defaultnya sendiri.
string
Warna latar toolbar, sebagai string hex: "#RRGGBB" atau "#AARRGGBB".
string
Warna navigation bar, sebagai string hex.
string
Warna divider di atas navigation bar, sebagai string hex.
'default' | 'back'
default menampilkan ikon sistem “X”. back menampilkan panah kembali yang digambar SDK.
'start' | 'end'
Sisi toolbar tempat tombol tutup muncul.
boolean
Menampilkan ikon share pada toolbar. false menyembunyikannya.
boolean
Menampilkan judul halaman di bawah URL pada toolbar.
boolean
Menyembunyikan toolbar secara otomatis saat halaman di-scroll.
boolean
Menampilkan “Bookmark this page” di menu overflow.
boolean
Menampilkan “Download page” di menu overflow.
'system' | 'light' | 'dark'
light atau dark memaksa tampilan tersebut terlepas dari pengaturan sistem perangkat. system mengikuti pengaturan sistem.
'done' | 'close' | 'cancel'
Gaya tombol dismiss. iOS menentukan apakah tombol tersebut dirender sebagai label atau ikon.
'pageSheet' | 'fullScreen'
pageSheet (default) menampilkan card yang dapat di-swipe ke bawah oleh customer untuk menutupnya. fullScreen memenuhi seluruh layar.
boolean
Memungkinkan toolbar diciutkan saat halaman di-scroll. Pengaturan ini hanya terlihat pengaruhnya ketika presentationStyle adalah fullScreen. Dengan pageSheet, bar tetap berada di posisinya terlepas dari pengaturan ini.
'system' | 'light' | 'dark'
light atau dark memaksa tampilan tersebut terlepas dari pengaturan sistem perangkat. system mengikuti pengaturan sistem.
iOS tidak memiliki opsi warna toolbar, karena properti tint SFSafariViewController yang mendasarinya sudah deprecated sejak iOS 26.

Error

start hanya menolak dengan CheckoutError untuk penggunaan yang salah atau kegagalan platform. Baca alasannya dari error.code. Customer yang membatalkan atau pembayaran yang ditolak selalu merupakan hasil, bukan rejection.
  • INVALID_CHECKOUT_URL: checkoutUrl bukan URL checkout session https (path yang dimulai dengan /session/) pada checkout.dodopayments.com atau test.checkout.dodopayments.com.
  • INVALID_RETURN_URL: returnUrl bukan absolute URL dengan scheme dan host.
  • ALREADY_IN_PROGRESS: checkout lain sedang berjalan. Hanya satu checkout yang dapat berjalan pada satu waktu.
  • PLATFORM_ERROR: kegagalan platform yang tidak terduga. SDK juga melaporkan native error yang tidak dikenali dengan kode ini.

Session yang Ditinggalkan

Native SDK mencatat checkout session saat checkout dimulai, dan menghapus catatan tersebut hanya ketika checkout berakhir dengan succeeded, failed, atau expired. Catatan tersebut tetap ada ketika aplikasi atau JavaScript bundle dihentikan selama checkout, yang menyebabkan promise start hilang, serta setelah hasil cancelled atau pending. Periksa catatan tersebut saat mount berikutnya dan setelah setiap hasil cancelled atau pending:
abandoned.sessionId adalah ID checkout session, yang dimulai dengan cks_. abandoned.createdAt adalah Date saat checkout dimulai. Backend Anda dapat mencari session tersebut menggunakan Dapatkan Checkout Session, yang mengembalikan payment_id dan payment_status. Sebelum pembayaran mencapai status final, perlakukan sebagai pending, bukan gagal.

Terkait

Mobile Integration Guide

Kontrak yang sama untuk Android, iOS, dan Flutter.

Expo Boilerplate

Contoh Expo lengkap dengan integrasi checkout.
Terakhir diubah pada 26 September 2026