React Native

Ini adalah checkout SDK React Native resmi dari Dodo Payments, @dodopayments/react-native-checkout. SDK ini membuka hosted checkout Dodo di tampilan browser native dan mengembalikan hasil bertipe. Catatan: terdapat package lama yang tidak terkait bernama dodopayments-react-native-sdk (unscoped) dengan API yang sepenuhnya berbeda. Halaman ini hanya mendokumentasikan package scoped resmi yang saat ini digunakan.

Checkout Sessions API

Buat checkout_url yang dibuka SDK ini, dari backend Anda.

Mobile Integration Guide

Lihat bagaimana hal ini menjadi bagian dari alur pembayaran mobile secara keseluruhan.

React Native SDK ini adalah wrapper Turbo Module tipis di atas core Swift dan Kotlin native yang sama. SDK ini membuka SFSafariViewController di iOS dan Chrome Custom Tab di Android, tidak menyimpan API key, serta tidak pernah memanggil Dodo API secara langsung. Semua logika checkout berjalan di browser; SDK hanya mengelola siklus hidup tampilan dan menangkap return URL.

SDK ini hanya memerlukan New Architecture, React Native 0.76+, iOS 16+, dan Android minSdk 24.

Instalasi

Install the Package

Android
iOS
Expo

Package ini ditautkan secara otomatis dan menarik com.dodopayments.api:checkout-android dari Maven.

npm i @dodopayments/react-native-checkout

Tidak diperlukan konfigurasi tambahan; dependency native diselesaikan secara otomatis.

npm i @dodopayments/react-native-checkout
cd ios && pod install

Core Swift disertakan dalam package dan diinstal melalui CocoaPods.

Hanya untuk development build (bukan Expo Go).

npm i @dodopayments/react-native-checkout

Selanjutnya, konfigurasikan app.json Anda (lihat Daftarkan Callback URL Scheme di bawah).

Aplikasi Anda harus mendaftarkan URL scheme untuk menerima return URL dari checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

Di android/app/build.gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

Ganti "myapp" dengan scheme aplikasi Anda.

Di ios/YourApp/Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Anda juga dapat menambahkannya melalui UI Info → URL Types di Xcode.

Plugin konfigurasi milik package tersebut mendaftarkan scheme untuk kedua platform di prebuild. Berikan opsi scheme di app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

scheme harus sama dengan yang Anda teruskan sebagai returnUrl (misalnya myappcheckout://return), dan harus berbeda dari expo.scheme. Expo sudah mendaftarkan yang tersebut di MainActivity, dan menggunakannya kembali dapat mengarahkan return checkout ke layar yang salah.Bangun ulang project native setelah mengedit app.json:

npx expo prebuild --clean

Ini hanya berfungsi dengan development builds, bukan Expo Go.Jika android/app/build.gradle dikelola secara manual dan tidak memiliki blok defaultConfig { } standar yang dapat ditemukan plugin, tambahkan placeholder sendiri. Lihat tab Android di atas.

Penggunaan

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

switch (result.status) {
  case 'succeeded': showSuccess(result.paymentId); break;
  case 'failed':    showFailure(); break;
  case 'cancelled': dismiss(); break;
  case 'pending':   showPending(); break;
  case 'expired':   showExpired(); break;
}

Meneruskan Return URL

Listener Linking diperlukan untuk penanganan return URL di iOS. Di Android, handleOpenURL adalah no-op yang menyelesaikan false karena core Android menangani redirect secara native. Listener ini aman untuk didaftarkan tanpa syarat di kedua platform.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

Arti Hasilnya

result.status adalah petunjuk UI, bukan bukti pembayaran. Konfirmasikan setiap pembayaran dari backend Anda, melalui webhook payment.succeeded / subscription.active.

CheckoutStatus

wajib

Salah satu dari succeeded, failed, cancelled, pending, expired.

string

Ditetapkan ketika return URL menyertakannya. Tampilkan di UI, jangan gunakan untuk memberikan akses. Lihat Verifikasi Pembayaran di bawah.

string

Ditetapkan untuk checkout subscription.

string[]

Ditetapkan ketika checkout menyertakan produk license key.

string

Ditetapkan ketika checkout mengambil email.

Record<string, string>

Setiap query parameter dari return URL, secara verbatim.

Verifikasi Pembayaran

Webhooks

Dodo Payments memanggil backend Anda ketika pembayaran berhasil atau subscription diaktifkan.

Get Payment Detail

Cari paymentId dengan secret key Anda untuk memeriksa statusnya secara langsung.

Berikan akses setelah salah satu dari hal tersebut mengonfirmasi pembayaran, jangan pernah hanya berdasarkan result.status.

Kustomisasi Tampilan

Sesuaikan toolbar, tombol, dan skema warna browser checkout melalui customization di start(...). Opsi dikelompokkan berdasarkan platform karena Custom Tab Android dan SFSafariViewController di iOS mengekspos kontrol native yang berbeda. Semua kolom bersifat opsional; jika customization dihilangkan, setiap platform akan menggunakan tampilan defaultnya.

Android — Custom Tab

Warna latar belakang toolbar.

Warna bilah navigasi.

Warna pemisah di atas bilah navigasi.

'default' | 'back'

default menampilkan ikon “X” sistem; back menampilkan panah kembali.

'start' | 'end'

Menentukan di sisi mana tombol tutup muncul pada toolbar.

Menampilkan ikon berbagi pada toolbar.

boolean

Menampilkan judul halaman di bawah URL pada toolbar.

boolean

Memungkinkan toolbar tersembunyi secara otomatis saat halaman digulir.

boolean

Menampilkan “Bookmark this page” di menu luapan.

boolean

Menampilkan “Download page” di menu luapan.

'system' | 'light' | 'dark'

Memaksa tampilan terang atau gelap terlepas dari pengaturan sistem perangkat.

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

Label atau ikon untuk tombol tutup.

'pageSheet' | 'fullScreen'

pageSheet ditampilkan sebagai kartu dengan gestur geser untuk menutup; fullScreen menutupi seluruh layar.

boolean

Memungkinkan toolbar diciutkan saat menggulir. Hanya terlihat ketika presentationStyle adalah fullScreen — pageSheet mempertahankan bilah tetap pada posisinya terlepas dari pengaturan ini.

'system' | 'light' | 'dark'

Memaksa tampilan terang atau gelap terlepas dari pengaturan sistem perangkat.

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

Error

start menolak dengan CheckoutError hanya jika terjadi penyalahgunaan atau kegagalan platform. Pembayaran yang dibatalkan atau ditolak selalu menjadi hasil, bukan exception.

INVALID_CHECKOUT_URL: bukan URL sesi checkout.dodopayments.com.
INVALID_RETURN_URL: bukan URL absolut yang valid.
ALREADY_IN_PROGRESS: checkout sudah berjalan.
PLATFORM_ERROR: kegagalan platform yang tidak terduga.

Sesi yang Ditinggalkan

Jika aplikasi atau bundel JS dihentikan di tengah checkout, promise akan hilang, tetapi lapisan native tetap mempertahankan sesi tersebut. Pulihkan sesi pada mount berikutnya dan rekonsiliasikan dengan backend Anda.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.clearAbandonedSession();
}

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

Instalasi

Penggunaan

Meneruskan Return URL

Arti Hasilnya

Verifikasi Pembayaran

Webhooks

Get Payment Detail

Kustomisasi Tampilan

Error

Sesi yang Ditinggalkan

Terkait

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​Instalasi

​Penggunaan

​Meneruskan Return URL

​Arti Hasilnya

​Verifikasi Pembayaran

Webhooks

Get Payment Detail

​Kustomisasi Tampilan

​Error

​Sesi yang Ditinggalkan

​Terkait

Mobile Integration Guide

Expo Boilerplate

Instalasi

Penggunaan

Meneruskan Return URL

Arti Hasilnya

Verifikasi Pembayaran

Kustomisasi Tampilan

Error

Sesi yang Ditinggalkan

Terkait