Overlay Checkout - Dodo Payments Documentation

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.

Demo

Interactive Demo

Lihat overlay checkout beraksi 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 create checkout session API.

Panduan Integrasi Langkah-demi-Langkah

Install the SDK

Instal SDK Checkout Dodo Payments menggunakan manajer paket pilihan Anda:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the 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.

Create a Checkout Button Component

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>
  );
}

Add Checkout to Your Page

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>
  );
}

Handle Success and Failure Pages

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>
  );
}

Test Your Integration

Mulai server pengembangan Anda:

npm run dev

Uji alur checkout:
- Klik tombol checkout
- Verifikasi overlay muncul
- Uji alur pembayaran menggunakan kredensial uji
- Konfirmasi pengalihan berfungsi dengan benar

Anda harus melihat event checkout tercatat di konsol browser Anda.

Go Live

Saat Anda siap untuk produksi:

Ubah mode menjadi 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Perbarui URL checkout Anda untuk menggunakan sesi checkout langsung dari backend Anda
Uji alur lengkap di produksi
Pantau peristiwa dan kesalahan

Referensi API

Konfigurasi

Opsi Inisialisasi

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

Opsi	Tipe	Wajib	Deskripsi
`mode`	`"test" \| "live"`	Ya	Mode lingkungan: `'test'` untuk pengembangan, `'live'` untuk produksi
`displayType`	`"overlay" \| "inline"`	Tidak	Jenis tampilan: `'overlay'` untuk modal checkout (default), `'inline'` untuk embedded checkout
`onEvent`	`function`	Ya	Fungsi callback untuk menangani event checkout

Opsi Checkout

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}

Opsi	Jenis	Diperlukan	Deskripsi
`checkoutUrl`	`string`	Ya	URL sesi checkout dari API create checkout session
`options.showTimer`	`boolean`	Tidak	Tampilkan atau sembunyikan timer checkout. Defaultnya adalah `true`. Bila dinonaktifkan, Anda akan menerima event `checkout.link_expired` ketika sesi berakhir.
`options.showSecurityBadge`	`boolean`	Tidak	Tampilkan atau sembunyikan badge keamanan. Defaultnya adalah `true`.

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,
  },
});

Tutup Checkout

Menutup overlay checkout secara programatik.

DodoPayments.Checkout.close();

Cek Status

Mengembalikan apakah overlay checkout saat ini terbuka.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Events

SDK menyediakan event real-time yang dapat Anda dengarkan melalui callback onEvent:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        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;
    }
  }
});

Jenis Event	Deskripsi
`checkout.opened`	Overlay checkout telah dibuka
`checkout.form_ready`	Formulir checkout siap menerima input pengguna. Berguna untuk menyembunyikan status loading.
`checkout.payment_page_opened`	Halaman pembayaran telah ditampilkan
`checkout.customer_details_submitted`	Detail pelanggan dan penagihan telah dikirimkan
`checkout.closed`	Overlay checkout telah ditutup
`checkout.redirect`	Checkout akan melakukan redirect
`checkout.error`	Terjadi kesalahan selama checkout
`checkout.link_expired`	Terpicu ketika sesi checkout berakhir. Hanya diterima saat `showTimer` diatur ke `false`.

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 meneruskan 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.

Opsi themeConfig di sisi klien sudah tidak digunakan lagi dan akan dihapus pada versi mayor berikutnya dari Checkout SDK (v2.0.0). Penggunaannya akan mencatat peringatan penghentian penggunaan di konsol browser. Sebagai gantinya, konfigurasikan tema saat membuat sesi checkout melalui API menggunakan parameter customization.theme_config — lihat Kustomisasi Tema Checkout — atau secara visual melalui halaman Design di dashboard. Tema yang dikonfigurasi pada sesi berlaku untuk checkout overlay, inline, dan hosted.

Bagian ini membahas konfigurasi tema di sisi klien yang sudah tidak digunakan lagi menggunakan Checkout SDK. Pendekatan yang direkomendasikan adalah mengonfigurasi tema di sisi server saat membuat sesi checkout melalui API menggunakan parameter theme_config. Lihat Kustomisasi Tema Checkout untuk konfigurasi tingkat API, atau gunakan halaman Design di dashboard untuk mengonfigurasi tema secara visual dengan pratinjau langsung.

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 Sebagian Tema

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,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Tipe TypeScript

Bagi 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 Error

SDK menyediakan informasi error terperinci melalui sistem event. Selalu terapkan penanganan error yang tepat dalam callback onEvent Anda:

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 event checkout.error untuk memberikan pengalaman pengguna yang baik saat terjadi error.

Praktik Terbaik

Inisialisasi sekali: Inisialisasikan SDK sekali saat aplikasi dimuat, bukan pada setiap percobaan checkout
Penanganan error: Selalu terapkan penanganan error yang tepat dalam callback event Anda
Mode pengujian: Gunakan mode test selama pengembangan dan beralih ke live hanya jika siap untuk produksi
Penanganan event: Tangani semua event yang relevan untuk pengalaman pengguna yang lengkap
URL yang valid: Selalu gunakan URL checkout yang valid dari API create checkout session
TypeScript: Gunakan TypeScript untuk keamanan tipe dan pengalaman developer yang lebih baik
Status pemuatan: Tampilkan status pemuatan saat checkout dibuka untuk meningkatkan UX
Pengelolaan timer: Nonaktifkan timer (showTimer: false) jika Anda ingin menangani kedaluwarsa sesi secara manual

Pemecahan Masalah

Checkout not opening

Kemungkinan penyebab:

SDK belum diinisialisasi sebelum memanggil open()
URL checkout tidak valid
Error JavaScript di konsol
Masalah konektivitas jaringan

Solusi:

Pastikan inisialisasi SDK dilakukan sebelum membuka checkout
Periksa error di konsol
Pastikan URL checkout valid dan berasal dari API create checkout session
Periksa konektivitas jaringan

Events not firing

Kemungkinan penyebab:

Event handler belum disiapkan dengan benar
Error JavaScript yang mencegah propagasi event
SDK tidak diinisialisasi dengan benar

Solusi:

Pastikan event handler dikonfigurasi dengan benar di Initialize()
Periksa konsol browser untuk error JavaScript
Pastikan inisialisasi SDK berhasil diselesaikan
Uji terlebih dahulu dengan event handler sederhana

Styling issues

Kemungkinan penyebab:

Konflik CSS dengan style aplikasi Anda
Pengaturan tema tidak diterapkan dengan benar
Masalah desain responsif

Solusi:

Periksa konflik CSS di DevTools browser
Pastikan pengaturan tema sudah benar
Uji pada ukuran layar yang berbeda
Pastikan tidak ada konflik z-index dengan overlay

Mengaktifkan Dompet Digital

Untuk informasi terperinci tentang penyiapan Google Pay dan dompet digital lainnya, lihat halaman Dompet Digital.

Apple Pay belum didukung di checkout overlay. Dukungan untuk Apple Pay akan segera tersedia.

Dukungan Browser

Dodo Payments Checkout SDK mendukung browser berikut:

Chrome (terbaru)
Firefox (terbaru)
Safari (terbaru)
Edge (terbaru)
IE11+

Checkout Overlay vs Inline

Pilih tipe checkout yang tepat untuk kebutuhan Anda:

Fitur	Checkout Overlay	Checkout Inline
Kedalaman integrasi	Modal di atas halaman	Sepenuhnya disematkan di halaman
Kontrol tata letak	Terbatas	Kontrol penuh
Branding	Terpisah dari halaman	Mulus
Upaya implementasi	Lebih rendah	Lebih tinggi
Cocok untuk	Integrasi cepat, halaman yang sudah ada	Halaman checkout khusus, alur konversi tinggi

Gunakan checkout overlay untuk integrasi yang lebih cepat dengan perubahan minimal pada halaman yang sudah ada. Gunakan checkout inline jika Anda menginginkan kontrol maksimum atas pengalaman checkout dan branding yang mulus.

Sumber Daya Terkait

Inline Checkout

Sematkan checkout langsung ke halaman Anda untuk pengalaman yang sepenuhnya terintegrasi.

Checkout Sessions API

Buat sesi checkout untuk mendukung pengalaman checkout Anda.

Webhooks

Tangani event pembayaran di sisi server dengan webhook.

Integration Guide

Panduan lengkap untuk mengintegrasikan Dodo Payments.

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

​Ikhtisar

​Demo

Interactive Demo

​Memulai dengan Cepat

​Panduan Integrasi Langkah-demi-Langkah

​Referensi API

​Konfigurasi

​Opsi Inisialisasi

​Opsi Checkout

​Metode

​Buka Checkout

​Tutup Checkout

​Cek Status

​Events

​Opsi Implementasi

​Instalasi Package Manager

​Implementasi CDN

​Kustomisasi Tema

​Konfigurasi Tema Dasar

​Konfigurasi Tema Lengkap

​Hanya Mode Terang

​Hanya Mode Gelap

​Penggantian Sebagian Tema

​Konfigurasi Tema dengan Opsi Lain

​Tipe TypeScript

​Penanganan Error

​Praktik Terbaik

​Pemecahan Masalah

​Mengaktifkan Dompet Digital

​Dukungan Browser

​Checkout Overlay vs Inline

​Sumber Daya Terkait

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Ikhtisar

Demo

Memulai dengan Cepat

Panduan Integrasi Langkah-demi-Langkah

Referensi API

Konfigurasi

Opsi Inisialisasi

Opsi Checkout

Metode

Buka Checkout

Tutup Checkout

Cek Status

Events

Opsi Implementasi

Instalasi Package Manager

Implementasi CDN

Kustomisasi Tema

Konfigurasi Tema Dasar

Konfigurasi Tema Lengkap

Hanya Mode Terang

Hanya Mode Gelap

Penggantian Sebagian Tema

Konfigurasi Tema dengan Opsi Lain

Tipe TypeScript

Penanganan Error

Praktik Terbaik

Pemecahan Masalah

Mengaktifkan Dompet Digital

Dukungan Browser

Checkout Overlay vs Inline

Sumber Daya Terkait