Overlay Checkout

Overlay checkout membuka jendela modal di atas halaman Anda. Pelanggan memasukkan detail pembayaran mereka di dalam modal sementara halaman Anda tetap terlihat di belakangnya. Saat mereka menutup modal, kendali kembali ke halaman Anda. Saat mereka menyelesaikan pembayaran, mereka akan dialihkan ke return_url.

Modal overlay checkout ditampilkan di atas halaman produk

Interactive Demo

Lihat overlay checkout beraksi melalui demo live kami.

Mulai Cepat

Instal SDK, inisialisasikan, lalu buka checkout dengan URL checkout dari create checkout session API:

import { DodoPayments } from "dodopayments-checkout";

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

DodoPayments.Checkout.open({
  checkoutUrl: "https://test.checkout.dodopayments.com/session/cks_123"
});

Integrasi Langkah demi Langkah

Install the SDK

Instal melalui npm, yarn, atau pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Panggil Initialize sekali saat aplikasi dimuat, biasanya di komponen utama atau entry point aplikasi Anda:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.error":
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Selalu inisialisasikan SDK sebelum membuka checkout. Inisialisasikan sekali saat aplikasi dimuat, bukan sebelum setiap percobaan checkout.

Create a Checkout Button

Buat komponen yang membuka modal 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(() => {
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        if (event.event_type === "checkout.opened") {
          setIsLoading(false);
        }
        if (event.event_type === "checkout.error") {
          setIsLoading(false);
          console.error("Checkout error:", event.data?.message);
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    setIsLoading(true);
    try {
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://test.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 the Button 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 Redirects

Buat halaman untuk menangani pengalihan checkout setelah pembayaran:

// 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

Jalankan development server Anda:

npm run dev

Uji alur checkout:
- Klik tombol checkout
- Pastikan modal muncul
- Uji alur pembayaran menggunakan kredensial pengujian
- Pastikan pengalihan berfungsi dengan benar

Anda akan melihat event checkout tercatat di browser console.

Go Live

Saat siap untuk production:

Ubah mode menjadi 'live':

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

Perbarui URL checkout Anda agar menggunakan live checkout sessions dari backend Anda
Uji seluruh alur di production
Pantau event dan error

Referensi API

Inisialisasi

Panggil Initialize sekali untuk menyiapkan SDK:

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

DodoPayments.Initialize(options);

Opsi	Tipe	Wajib	Deskripsi
`mode`	`"test" \| "live"`	Ya	Mode environment: `"test"` untuk development, `"live"` untuk production
`displayType`	`"overlay" \| "inline"`	Ya	Tipe tampilan: `"overlay"` untuk modal checkout (default), `"inline"` untuk embedded checkout
`onEvent`	`function`	Ya	Fungsi callback untuk menangani event checkout

Buka Checkout

Buka modal checkout:

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
    themeConfig?: ThemeConfig;
    payButtonText?: string;
    fontSize?: FontSize;
    fontWeight?: FontWeight;
  };
}

DodoPayments.Checkout.open(options);

Opsi	Tipe	Wajib	Deskripsi
`checkoutUrl`	`string`	Ya	URL checkout session dari create checkout session API
`options.showTimer`	`boolean`	Tidak	Tampilkan atau sembunyikan timer session. Defaultnya adalah `true`. Saat dinonaktifkan, Anda menerima event `checkout.link_expired` ketika session berakhir.
`options.showSecurityBadge`	`boolean`	Tidak	Tampilkan atau sembunyikan security badge. Defaultnya adalah `true`
`options.manualRedirect`	`boolean`	Tidak	Saat `true`, cegah pengalihan otomatis. Checkout memancarkan `checkout.status` dengan hasil pembayaran dan `checkout.redirect_requested` dengan URL yang harus dibuka, lalu Anda menangani navigasi
`options.themeConfig`	`ThemeConfig`	Tidak	Deprecated. Konfigurasikan theme di sisi server saat membuat checkout session
`options.payButtonText`	`string`	Tidak	Teks kustom untuk tombol pembayaran
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	Tidak	Ukuran font global untuk checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	Tidak	Ketebalan font global untuk checkout

Tutup Checkout

Tutup modal secara programatis:

DodoPayments.Checkout.close();

Periksa Status

Periksa apakah modal sedang terbuka:

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

Event

Dengarkan event checkout melalui callback onEvent yang diteruskan ke Initialize:

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Modal has opened
        break;
      case "checkout.form_ready":
        // Form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page is displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer details submitted
        break;
      case "checkout.closed":
        // Modal has closed
        break;
      case "checkout.redirect":
        // Checkout will redirect
        break;
      case "checkout.error":
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Session expired (only when showTimer is false)
        break;
    }
  }
});

Event	Deskripsi
`checkout.opened`	Modal telah dibuka
`checkout.form_ready`	Form siap menerima input pengguna. Gunakan ini untuk menyembunyikan loading state
`checkout.payment_page_opened`	Halaman pembayaran ditampilkan
`checkout.customer_details_submitted`	Detail pelanggan dan penagihan dikirim
`checkout.closed`	Modal telah ditutup
`checkout.redirect`	Checkout akan dialihkan (misalnya ke halaman bank)
`checkout.error`	Terjadi error selama checkout
`checkout.link_expired`	Checkout session berakhir. Hanya diterima ketika `showTimer` diatur ke `false`.

Implementasi CDN

Untuk integrasi cepat tanpa build step, muat SDK dari CDN:

<!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>
  
  <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
  <script>
    DodoPaymentsCheckout.DodoPayments.Initialize({
      mode: "test",
      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://test.checkout.dodopayments.com/session/cks_123"
      });
    }
  </script>
</body>
</html>

Kustomisasi Theme

Opsi themeConfig di sisi client deprecated dan akan dihapus pada major version berikutnya dari Checkout SDK (v2.0.0). Penggunaannya akan mencatat peringatan deprecated di browser console. Sebagai gantinya, konfigurasikan theme saat membuat checkout session melalui API menggunakan parameter customization.theme_config — lihat Checkout Theme Customization — atau secara visual di Design page pada dashboard. Theme yang dikonfigurasi dalam session berlaku untuk overlay, inline, dan hosted checkout.

Bagian ini membahas konfigurasi theme di sisi client yang deprecated menggunakan Checkout SDK. Pendekatan yang direkomendasikan adalah mengonfigurasi theme di sisi server saat membuat checkout session melalui API menggunakan parameter theme_config. Lihat Checkout Theme Customization untuk konfigurasi tingkat API, atau gunakan Design page di dashboard untuk mengonfigurasi theme secara visual dengan live preview.

Jika Anda harus menggunakan konfigurasi theme di sisi client, teruskan themeConfig dalam parameter options:

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

Properti Theme

Semua properti theme yang tersedia untuk mode light dan dark:

interface ThemeConfig {
  light?: {
    bgPrimary?: string;              // Primary background
    bgSecondary?: string;            // Secondary background (tabs, etc.)
    borderPrimary?: string;          // Primary border
    borderSecondary?: string;        // Secondary border
    textPrimary?: string;            // Primary text
    textSecondary?: string;          // Secondary text
    textPlaceholder?: string;        // Placeholder text
    textError?: string;              // Error text
    textSuccess?: string;            // Success text
    buttonPrimary?: string;          // Primary button background
    buttonPrimaryHover?: string;     // Primary button hover
    buttonTextPrimary?: string;      // Primary button text
    buttonSecondary?: string;        // Secondary button background
    buttonSecondaryHover?: string;   // Secondary button hover
    buttonTextSecondary?: string;    // Secondary button text
    inputFocusBorder?: string;       // Input focus border
  };
  dark?: {
    // Same properties as light mode
  };
  radius?: string;                   // Border radius (e.g., "8px")
}

Penanganan Error

Selalu terapkan penanganan error 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);
      // Show user-friendly error message
      // Optionally retry the checkout
    }
    if (event.event_type === "checkout.link_expired") {
      console.warn("Checkout session has expired");
      // Create a new checkout session and try again
    }
  }
});

Selalu tangani event checkout.error untuk memberikan pengalaman pengguna yang baik saat terjadi error.

Praktik Terbaik

Inisialisasikan sekali: Panggil Initialize sekali saat aplikasi dimuat, bukan sebelum setiap checkout
Penanganan error: Terapkan penanganan error yang tepat dalam event callback Anda
Mode pengujian: Gunakan mode "test" selama development dan beralih ke "live" hanya saat siap untuk production
Penanganan event: Tangani semua event yang relevan untuk pengalaman pengguna yang lengkap
URL yang valid: Selalu gunakan URL checkout yang valid dari create checkout session API
TypeScript: Gunakan TypeScript untuk keamanan tipe dan pengalaman developer yang lebih baik
Loading state: Tampilkan loading state saat checkout sedang dibuka untuk meningkatkan UX
Pengelolaan timer: Nonaktifkan timer (showTimer: false) jika Anda ingin menangani kedaluwarsa session secara manual

Pemecahan Masalah

Events not firing

Kemungkinan penyebab:

Event handler tidak disiapkan dengan benar
Error JavaScript mencegah propagasi event
SDK tidak diinisialisasikan dengan benar

Solusi:

Pastikan event handler dikonfigurasi dengan benar di Initialize()
Periksa browser console untuk mengetahui 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 theme tidak diterapkan dengan benar
Masalah desain responsif

Solusi:

Periksa konflik CSS di browser DevTools
Pastikan pengaturan theme sudah benar
Uji pada berbagai ukuran layar
Pastikan tidak ada konflik z-index dengan modal

Dompet Digital

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

Apple Pay belum didukung di overlay checkout.

Dukungan Browser

Dodo Payments Checkout SDK mendukung:

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

Overlay vs Inline Checkout

Pilih tipe checkout yang tepat untuk kebutuhan Anda:

Fitur	Overlay	Inline
Kedalaman integrasi	Modal di atas halaman	Sepenuhnya tertanam di halaman
Kontrol tata letak	Terbatas	Kontrol penuh
Branding	Terpisah dari halaman	Sesuai dengan halaman Anda
Upaya implementasi	Lebih rendah	Lebih tinggi
Cocok untuk	Integrasi cepat, halaman yang sudah ada	Halaman checkout kustom, alur dengan konversi tinggi

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

Sumber Daya Terkait

Inline Checkout

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

Checkout Sessions API

Buat checkout sessions untuk mendukung pengalaman checkout Anda.

Webhooks

Tangani event pembayaran di sisi server menggunakan webhooks.

Integration Guide

Panduan lengkap untuk mengintegrasikan Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Mulai Cepat

Integrasi Langkah demi Langkah

Referensi API

Inisialisasi

Buka Checkout

Tutup Checkout

Periksa Status

Event

Implementasi CDN

Kustomisasi Theme

Properti Theme

Penanganan Error

Praktik Terbaik

Pemecahan Masalah

Dompet Digital

Dukungan Browser

Overlay vs Inline Checkout

Sumber Daya Terkait

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Mulai Cepat

​Integrasi Langkah demi Langkah

​Referensi API

​Inisialisasi

​Buka Checkout

​Tutup Checkout

​Periksa Status

​Event

​Implementasi CDN

​Kustomisasi Theme

​Properti Theme

​Penanganan Error

​Praktik Terbaik

​Pemecahan Masalah

​Dompet Digital

​Dukungan Browser

​Overlay vs Inline Checkout

​Sumber Daya Terkait

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Mulai Cepat

Integrasi Langkah demi Langkah

Referensi API

Inisialisasi

Buka Checkout

Tutup Checkout

Periksa Status

Event

Implementasi CDN

Kustomisasi Theme

Properti Theme

Penanganan Error

Praktik Terbaik

Pemecahan Masalah

Dompet Digital

Dukungan Browser

Overlay vs Inline Checkout

Sumber Daya Terkait