Langsung ke konten utama

Ikhtisar

SDK Checkout Dodo Payments menyediakan cara yang mulus untuk mengintegrasikan overlay pembayaran kami ke dalam aplikasi web Anda. Dibangun dengan TypeScript dan standar web modern, ini menawarkan solusi yang kuat untuk menangani pembayaran dengan penanganan peristiwa real-time dan tema yang dapat disesuaikan.
Gambar Sampul Overlay Checkout

Demo

Demo Interaktif

Lihat checkout overlay dalam aksi dengan demo langsung kami.

Memulai dengan Cepat

Mulai dengan SDK Checkout Dodo Payments hanya dalam beberapa baris kode:
import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
Dapatkan URL checkout Anda dari API buat sesi checkout.

Panduan Integrasi Langkah-demi-Langkah

1

Instal SDK

Instal SDK Checkout Dodo Payments menggunakan manajer paket pilihan Anda:
npm install dodopayments-checkout
2

Inisialisasi SDK

Inisialisasi SDK di aplikasi Anda, biasanya di komponen utama atau titik masuk aplikasi:
import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});
Selalu inisialisasi SDK sebelum mencoba membuka checkout. Inisialisasi harus dilakukan sekali saat aplikasi Anda dimuat.
3

Buat Komponen Tombol Checkout

Buat komponen yang membuka overlay checkout:
// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}
4

Tambahkan Checkout ke Halaman Anda

Gunakan komponen tombol checkout di aplikasi Anda:
// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}
5

Tangani Halaman Sukses dan Gagal

Buat halaman untuk menangani pengalihan checkout:
// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}
6

Uji Integrasi Anda

  1. Mulai server pengembangan Anda:
npm run dev
  1. Uji alur checkout:
    • Klik tombol checkout
    • Verifikasi overlay muncul
    • Uji alur pembayaran menggunakan kredensial uji
    • Konfirmasi pengalihan berfungsi dengan benar
Anda harus melihat peristiwa checkout tercatat di konsol browser Anda.
7

Go Live

Saat Anda siap untuk produksi:
  1. Ubah mode ke 'live':
DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. Perbarui URL checkout Anda untuk menggunakan sesi checkout langsung dari backend Anda
  2. Uji alur lengkap di produksi
  3. Pantau peristiwa dan kesalahan

Referensi API

Konfigurasi

Opsi Inisialisasi

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}
OpsiTipeDiperlukanDeskripsi
mode"test" | "live"YaMode lingkungan: 'test' untuk pengembangan, 'live' untuk produksi
displayType"overlay" | "inline"TidakTipe tampilan: 'overlay' untuk checkout modal (default), 'inline' untuk checkout tersemat
onEventfunctionYaFungsi callback untuk menangani peristiwa checkout

Opsi Checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}
OpsiTipeDiperlukanDeskripsi
checkoutUrlstringYaURL sesi checkout dari API buat sesi checkout
options.showTimerbooleanTidakTampilkan atau sembunyikan timer checkout. Defaultnya adalah true. Ketika dinonaktifkan, Anda akan menerima peristiwa checkout.link_expired ketika sesi berakhir.
options.showSecurityBadgebooleanTidakTampilkan atau sembunyikan badge keamanan. Defaultnya adalah true.
options.manualRedirectbooleanTidakKetika diaktifkan, checkout tidak akan secara otomatis mengalihkan setelah selesai. Sebagai gantinya, Anda akan menerima peristiwa checkout.status dan checkout.redirect_requested untuk menangani pengalihan sendiri.

Metode

Buka Checkout

Membuka overlay checkout dengan URL sesi checkout yang ditentukan.
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
Anda juga dapat memberikan opsi tambahan untuk menyesuaikan perilaku checkout:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});
Saat menggunakan manualRedirect, tangani penyelesaian checkout di callback onEvent:
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Tutup Checkout

Menutup overlay checkout secara programatis.
DodoPayments.Checkout.close();

Periksa Status

Mengembalikan apakah overlay checkout saat ini terbuka.
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Peristiwa

SDK menyediakan peristiwa waktu nyata yang dapat Anda dengarkan melalui callback onEvent:

Data Peristiwa Status Checkout

Ketika manualRedirect diaktifkan, Anda menerima peristiwa checkout.status dengan data berikut:
interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Data Peristiwa Pengalihan Checkout Diminta

Ketika manualRedirect diaktifkan, Anda menerima peristiwa checkout.redirect_requested dengan data berikut:
interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}
DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});
Tipe PeristiwaDeskripsi
checkout.openedOverlay checkout telah dibuka
checkout.payment_page_openedHalaman pembayaran telah ditampilkan
checkout.customer_details_submittedDetail pelanggan dan penagihan telah diserahkan
checkout.closedOverlay checkout telah ditutup
checkout.redirectCheckout akan melakukan pengalihan
checkout.errorTerjadi kesalahan selama checkout
checkout.link_expiredDitembak ketika sesi checkout berakhir. Hanya diterima ketika showTimer diatur ke false.
checkout.statusDitembak ketika manualRedirect diaktifkan. Berisi status checkout (succeeded, failed, atau processing).
checkout.redirect_requestedDitembak ketika manualRedirect diaktifkan. Berisi URL untuk mengalihkan pelanggan.

Opsi Implementasi

Instalasi Package Manager

Instal melalui npm, yarn, atau pnpm seperti yang ditunjukkan dalam Panduan Integrasi Langkah-demi-Langkah.

Implementasi CDN

Untuk integrasi cepat tanpa langkah build, Anda dapat menggunakan CDN kami:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Kustomisasi Tema

Anda dapat menyesuaikan tampilan checkout dengan mengirimkan objek themeConfig dalam parameter options saat membuka checkout. Konfigurasi tema mendukung mode terang dan gelap, memungkinkan Anda untuk menyesuaikan warna, batas, teks, tombol, dan radius batas.

Konfigurasi Tema Dasar

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Konfigurasi Tema Lengkap

Semua properti tema yang tersedia:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Hanya Mode Terang

Jika Anda hanya ingin menyesuaikan tema terang:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Hanya Mode Gelap

Jika Anda hanya ingin menyesuaikan tema gelap:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Penggantian Tema Parsial

Anda dapat mengganti hanya properti tertentu. Checkout akan menggunakan nilai default untuk properti yang tidak Anda tentukan:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Konfigurasi Tema dengan Opsi Lain

Anda dapat menggabungkan konfigurasi tema dengan opsi checkout lainnya:
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Tipe TypeScript

Untuk pengguna TypeScript, semua tipe konfigurasi tema diekspor:
import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Penanganan Kesalahan

SDK menyediakan informasi kesalahan yang detail melalui sistem peristiwa. Selalu terapkan penanganan kesalahan yang tepat di callback onEvent:
DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});
Selalu tangani peristiwa checkout.error untuk memberikan pengalaman pengguna yang baik ketika kesalahan terjadi.

Praktik Terbaik

  1. Inisialisasi sekali: Inisialisasi SDK sekali saat aplikasi Anda dimuat, bukan pada setiap upaya checkout
  2. Penanganan kesalahan: Selalu terapkan penanganan kesalahan yang tepat di callback peristiwa Anda
  3. Mode pengujian: Gunakan mode test selama pengembangan dan beralih ke live hanya ketika siap untuk produksi
  4. Penanganan peristiwa: Tangani semua peristiwa yang relevan untuk pengalaman pengguna yang lengkap
  5. URL yang valid: Selalu gunakan URL checkout yang valid dari API buat sesi checkout
  6. TypeScript: Gunakan TypeScript untuk keamanan tipe yang lebih baik dan pengalaman pengembang
  7. Status pemuatan: Tampilkan status pemuatan saat checkout dibuka untuk meningkatkan UX
  8. Pengalihan manual: Gunakan manualRedirect ketika Anda memerlukan kontrol kustom atas navigasi pasca-checkout
  9. Manajemen timer: Nonaktifkan timer (showTimer: false) jika Anda ingin menangani kedaluwarsa sesi secara manual

Pemecahan Masalah

Kemungkinan penyebab:
  • SDK tidak diinisialisasi sebelum memanggil open()
  • URL checkout tidak valid
  • Kesalahan JavaScript di konsol
  • Masalah konektivitas jaringan
Solusi:
  • Verifikasi inisialisasi SDK terjadi sebelum membuka checkout
  • Periksa kesalahan di konsol
  • Pastikan URL checkout valid dan dari API sesi checkout yang dibuat
  • Verifikasi konektivitas jaringan
Kemungkinan penyebab:
  • Penangan acara tidak diatur dengan benar
  • Kesalahan JavaScript mencegah propagasi acara
  • SDK tidak diinisialisasi dengan benar
Solusi:
  • Konfirmasi bahwa penangan peristiwa dikonfigurasi dengan benar di Initialize()
  • Periksa konsol browser untuk kesalahan JavaScript
  • Verifikasi bahwa inisialisasi SDK selesai dengan sukses
  • Uji dengan penangan peristiwa yang sederhana terlebih dahulu
Kemungkinan penyebab:
  • Konflik CSS dengan gaya aplikasi Anda
  • Pengaturan tema tidak diterapkan dengan benar
  • Masalah desain responsif
Solusi:
  • Periksa konflik CSS di DevTools browser
  • Verifikasi pengaturan tema sudah benar
  • Uji pada berbagai ukuran layar
  • Pastikan tidak ada konflik z-index dengan overlay

Mengaktifkan Dompet Digital

Untuk informasi lebih detail tentang cara mengatur Apple Pay, Google Pay, dan dompet digital lainnya, lihat halaman Dompet Digital.

Pengaturan Cepat untuk Apple Pay

1

Unduh file asosiasi domain

2

Minta aktivasi

Kirim email ke support@dodopayments.com dengan URL domain produksi Anda dan minta aktivasi Apple Pay.
3

Uji setelah konfirmasi

Setelah dikonfirmasi, verifikasi bahwa Apple Pay muncul di checkout dan uji alur pembelian secara lengkap.
Apple Pay memerlukan verifikasi domain sebelum muncul di produksi. Hubungi dukungan sebelum pergi live jika Anda berencana untuk menawarkan Apple Pay.

Dukungan Browser

SDK Checkout Dodo Payments mendukung browser berikut:
  • Chrome (terbaru)
  • Firefox (terbaru)
  • Safari (terbaru)
  • Edge (terbaru)
  • IE11+

Checkout Overlay vs Inline

Pilih tipe checkout yang tepat untuk kasus penggunaan Anda:
FiturOverlay CheckoutInline Checkout
Kedalaman integrasiModal di atas halamanSepenuhnya terintegrasi di halaman
Kontrol tata letakTerbatasKontrol penuh
BrandingTerpisah dari halamanMulus
Usaha implementasiLebih rendahLebih tinggi
Terbaik untukIntegrasi cepat, halaman yang adaHalaman checkout kustom, alur konversi tinggi
Gunakan overlay checkout untuk integrasi yang lebih cepat dengan perubahan minimal pada halaman yang sudah ada. Gunakan inline checkout saat Anda ingin kontrol maksimal atas pengalaman checkout dan branding yang mulus.

Sumber Daya Terkait

Untuk bantuan lebih lanjut, kunjungi komunitas Discord kami atau hubungi tim dukungan pengembang kami.