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.

Bagian ini mencakup konfigurasi tema client-side menggunakan Checkout SDK. Anda juga dapat mengonfigurasi tema server-side saat membuat sesi checkout melalui API menggunakan parameter theme_config. Lihat Kustomisasi Tema Checkout untuk konfigurasi tingkat API, atau gunakan halaman Desain 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 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,
    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 terperinci melalui sistem event. Selalu terapkan penanganan kesalahan 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 ketika terjadi kesalahan.

Praktik Terbaik

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

Pemecahan Masalah

Checkout not opening

Kemungkinan penyebab:

SDK tidak diinisialisasi sebelum memanggil open()
URL checkout yang tidak valid
Kesalahan JavaScript dalam konsol
Masalah konektivitas jaringan

Solusi:

Verifikasi inisialisasi SDK terjadi sebelum membuka checkout
Periksa kesalahan konsol
Pastikan URL checkout valid dan dari API create checkout session
Verifikasi konektivitas jaringan

Events not firing

Kemungkinan penyebab:

Penangan event tidak diatur dengan benar
Kesalahan JavaScript yang mencegah propagasi event
SDK tidak diinisialisasi dengan benar

Solusi:

Pastikan penangan event dikonfigurasi dengan benar dalam Initialize()
Periksa kesalahan JavaScript dalam konsol browser
Verifikasi inisialisasi SDK selesai dengan sukses
Uji dengan penangan event yang sederhana terlebih dahulu

Styling issues

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 benar
Uji pada berbagai ukuran layar
Pastikan tidak ada konflik z-index dengan overlay

Mengaktifkan Dompet Digital

Untuk informasi detil tentang pengaturan Google Pay dan dompet digital lainnya, lihat halaman Dompet Digital.

Apple Pay belum didukung dalam overlay checkout. Dukungan untuk Apple Pay segera hadir.

Dukungan Browser

Dodo Payments Checkout SDK mendukung browser berikut:

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

Overlay vs Inline Checkout

Pilih tipe checkout yang tepat untuk kasus penggunaan Anda:

Fitur	Overlay Checkout	Inline Checkout
Kedalaman integrasi	Modal di atas halaman	Tertanam sepenuhnya di halaman
Kontrol tata letak	Terbatas	Kontrol penuh
Branding	Terpisah dari halaman	Mulus
Upaya implementasi	Lebih rendah	Lebih tinggi
Terbaik untuk	Integrasi cepat, halaman yang ada	Halaman checkout kustom, alur konversi tinggi

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

Sumber Daya Terkait

Inline Checkout

Tanam checkout langsung ke dalam halaman Anda untuk pengalaman yang sepenuhnya terintegrasi.

Checkout Sessions API

Buat sesi checkout untuk mendukung pengalaman checkout Anda.

Webhooks

Tangani event pembayaran pada sisi server dengan webhook.

Integration Guide

Panduan lengkap untuk mengintegrasikan Dodo Payments.

Untuk bantuan lebih lanjut, kunjungi komunitas Discord kami atau hubungi tim dukungan pengembang 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 Tema Parsial

​Konfigurasi Tema dengan Opsi Lain

​Tipe TypeScript

​Penanganan Kesalahan

​Praktik Terbaik

​Pemecahan Masalah

​Mengaktifkan Dompet Digital

​Dukungan Browser

​Overlay vs Inline Checkout

​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 Tema Parsial

Konfigurasi Tema dengan Opsi Lain

Tipe TypeScript

Penanganan Kesalahan

Praktik Terbaik

Pemecahan Masalah

Mengaktifkan Dompet Digital

Dukungan Browser

Overlay vs Inline Checkout

Sumber Daya Terkait