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

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;
    manualRedirect?: boolean;
  };
}

Opsi	Tipe	Wajib	Deskripsi
`checkoutUrl`	`string`	Ya	URL sesi checkout dari create checkout session API
`options.showTimer`	`boolean`	Tidak	Tampilkan atau sembunyikan timer checkout. Defaultnya adalah `true`. Ketika dinonaktifkan, Anda akan menerima event `checkout.link_expired` saat sesi kedaluwarsa.
`options.showSecurityBadge`	`boolean`	Tidak	Tampilkan atau sembunyikan lencana keamanan. Defaultnya adalah `true`.
`options.manualRedirect`	`boolean`	Tidak	Saat diaktifkan, checkout tidak akan mengalihkan secara otomatis setelah selesai. Sebagai gantinya, Anda akan menerima event `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 Anda:

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 event waktu nyata yang bisa Anda dengarkan melalui callback onEvent:

Data Peristiwa Status Checkout

Saat manualRedirect diaktifkan, Anda menerima event checkout.status dengan data berikut:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Data Peristiwa Pengalihan Checkout Diminta

Saat manualRedirect diaktifkan, Anda menerima event 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.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;
      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;
    }
  }
});

Jenis Event	Deskripsi
`checkout.opened`	Overlay checkout telah dibuka
`checkout.form_ready`	Form checkout siap menerima input pengguna. Berguna untuk menyembunyikan status pemuatan.
`checkout.payment_page_opened`	Halaman pembayaran telah ditampilkan
`checkout.customer_details_submitted`	Detail pelanggan dan tagihan telah diserahkan
`checkout.closed`	Overlay checkout telah ditutup
`checkout.redirect`	Checkout akan melakukan pengalihan
`checkout.error`	Terjadi kesalahan selama checkout
`checkout.link_expired`	Dipicu saat sesi checkout kedaluwarsa. Hanya diterima ketika `showTimer` disetel ke `false`.
`checkout.status`	Dipicu saat `manualRedirect` diaktifkan. Berisi status checkout (`succeeded`, `failed`, atau `processing`).
`checkout.redirect_requested`	Dipicu saat `manualRedirect` diaktifkan. Berisi URL untuk mengarahkan 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 meneruskan objek themeConfig dalam parameter options saat membuka checkout. Konfigurasi tema mendukung mode terang dan gelap, memungkinkan Anda menyesuaikan warna, border, teks, tombol, dan radius border.

Bagian ini membahas konfigurasi tema di sisi klien menggunakan SDK Checkout. Anda juga dapat 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 Desain di dasbor 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 menimpa 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

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 kesalahan rinci 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 kesalahan.

Praktik Terbaik

Inisialisasi sekali: Inisialisasi SDK sekali saat aplikasi Anda dimuat, bukan setiap kali mencoba checkout
Penanganan error: Selalu terapkan penanganan error yang tepat di callback event Anda
Mode pengujian: Gunakan mode test selama pengembangan dan beralih ke live hanya ketika siap untuk produksi
Penanganan event: Tangani semua event relevan untuk pengalaman pengguna yang lengkap
URL Valid: Selalu gunakan URL checkout valid dari create checkout session API
TypeScript: Gunakan TypeScript untuk keamanan tipe yang lebih baik dan pengalaman pengembang yang lebih baik
Status pemuatan: Tampilkan status pemuatan saat checkout sedang dibuka untuk meningkatkan UX
Pengalihan manual: Gunakan manualRedirect ketika Anda memerlukan kontrol khusus atas navigasi pasca-checkout
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 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 berasal dari create checkout session API
Verifikasi konektivitas jaringan

Events not firing

Kemungkinan penyebab:

Pengelola event tidak disiapkan dengan benar
Kesalahan JavaScript yang mencegah propagasi event
SDK tidak diinisialisasi dengan benar

Solusi:

Pastikan pengelola event dikonfigurasi dengan benar di Initialize()
Periksa konsol browser untuk kesalahan JavaScript
Verifikasi inisialisasi SDK selesai dengan sukses
Uji dengan pengelola event 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 sudah benar
Uji pada ukuran layar berbeda
Pastikan tidak ada konflik z-index dengan overlay

Mengaktifkan Dompet Digital

Untuk informasi detail tentang menyiapkan Google Pay dan dompet digital lainnya, lihat halaman Dompet Digital.

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

Dukungan Browser

SDK Checkout Dodo Payments mendukung browser berikut:

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

Overlay vs Inline Checkout

Pilih jenis checkout yang tepat untuk kasus penggunaan Anda:

Fitur	Overlay Checkout	Inline Checkout
Kedalaman integrasi	Modal di atas halaman	Sepenuhnya tertanam 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 overlay checkout untuk integrasi yang lebih cepat dengan perubahan minimal pada halaman Anda saat ini. Gunakan inline checkout saat Anda menginginkan kontrol maksimal atas pengalaman checkout dan branding yang mulus.

Sumber Terkait

Inline Checkout

Sisipkan 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 webhooks.

Integration Guide

Panduan lengkap untuk mengintegrasikan Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Ikhtisar

​Demo

Interactive Demo

​Memulai dengan Cepat

​Panduan Integrasi Langkah-demi-Langkah

​Referensi API

​Konfigurasi

​Opsi Inisialisasi

​Opsi Checkout

​Metode

​Buka Checkout

​Tutup Checkout

​Periksa Status

​Peristiwa

​Data Peristiwa Status Checkout

​Data Peristiwa Pengalihan Checkout Diminta

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

​Praktik Terbaik

​Pemecahan Masalah

​Mengaktifkan Dompet Digital

​Dukungan Browser

​Overlay vs Inline Checkout

​Sumber 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

Periksa Status

Peristiwa

Data Peristiwa Status Checkout

Data Peristiwa Pengalihan Checkout Diminta

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 Error

Praktik Terbaik

Pemecahan Masalah

Mengaktifkan Dompet Digital

Dukungan Browser

Overlay vs Inline Checkout

Sumber Terkait