> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overlay Checkout

> Perpustakaan TypeScript modern untuk menyematkan checkout overlay Dodo Payments dan mendengarkan peristiwa checkout secara real-time.

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

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/cover-images/overlay-checkout.png?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=15d90c695e92914a9d54b10509d6fe47" alt="Overlay Checkout Cover Image" style={{ maxHeight: '500px', width: 'auto' }} width="3826" height="2160" data-path="images/cover-images/overlay-checkout.png" />
</Frame>

## Demo

<Card title="Interactive Demo" icon="play" href="https://atlas.dodopayments.com/pricing">
  Lihat overlay checkout beraksi dengan demo langsung kami.
</Card>

## Memulai dengan Cepat

Mulai dengan SDK Checkout Dodo Payments hanya dalam beberapa baris kode:

```typescript theme={null}
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"
});
```

<Tip>
  Dapatkan URL checkout Anda dari [create checkout session API](/api-reference/checkout-sessions/create).
</Tip>

## Panduan Integrasi Langkah-demi-Langkah

<Steps>
  <Step title="Install the SDK">
    Instal SDK Checkout Dodo Payments menggunakan manajer paket pilihan Anda:

    <CodeGroup>
      ```bash npm theme={null}
      npm install dodopayments-checkout
      ```

      ```bash yarn theme={null}
      yarn add dodopayments-checkout
      ```

      ```bash pnpm theme={null}
      pnpm add dodopayments-checkout
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize the SDK">
    Inisialisasi SDK di aplikasi Anda, biasanya di komponen utama atau titik masuk aplikasi:

    ```typescript theme={null}
    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;
        }
      },
    });
    ```

    <Warning>
      Selalu inisialisasi SDK sebelum mencoba membuka checkout. Inisialisasi harus dilakukan sekali saat aplikasi Anda dimuat.
    </Warning>
  </Step>

  <Step title="Create a Checkout Button Component">
    Buat komponen yang membuka overlay checkout:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Add Checkout to Your Page">
    Gunakan komponen tombol checkout di aplikasi Anda:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Handle Success and Failure Pages">
    Buat halaman untuk menangani pengalihan checkout:

    ```typescript theme={null}
    // 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>
      );
    }
    ```
  </Step>

  <Step title="Test Your Integration">
    1. Mulai server pengembangan Anda:

    ```bash theme={null}
    npm run dev
    ```

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

    <Check>
      Anda harus melihat event checkout tercatat di konsol browser Anda.
    </Check>
  </Step>

  <Step title="Go Live">
    Saat Anda siap untuk produksi:

    1. Ubah mode menjadi `'live'`:

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

    2. Perbarui URL checkout Anda untuk menggunakan sesi checkout langsung dari backend Anda
    3. Uji alur lengkap di produksi
    4. Pantau peristiwa dan kesalahan
  </Step>
</Steps>

## Referensi API

### Konfigurasi

#### Opsi Inisialisasi

```typescript theme={null}
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

```typescript theme={null}
interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
  };
}
```

| Opsi                        | Jenis     | Diperlukan | Deskripsi                                                                                                                                                       |
| --------------------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkoutUrl`               | `string`  | Ya         | URL sesi checkout dari [API create checkout session](/api-reference/checkout-sessions/create)                                                                   |
| `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.

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});
```

Anda juga dapat memberikan opsi tambahan untuk menyesuaikan perilaku checkout:

```typescript theme={null}
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
  },
});
```

#### Tutup Checkout

Menutup overlay checkout secara programatik.

```typescript theme={null}
DodoPayments.Checkout.close();
```

#### Cek Status

Mengembalikan apakah overlay checkout saat ini terbuka.

```typescript theme={null}
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean
```

### Events

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

```typescript theme={null}
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](#step-by-step-integration-guide).

### Implementasi CDN

Untuk integrasi cepat tanpa langkah build, Anda dapat menggunakan CDN kami:

```html theme={null}
<!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.

<Info>
  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](/features/checkout#checkout-theme-customization) untuk konfigurasi tingkat API, atau gunakan [halaman Desain](/features/design) di dashboard untuk mengonfigurasi tema secara visual dengan pratinjau langsung.
</Info>

#### Konfigurasi Tema Dasar

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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");
    }
  }
});
```

<Warning>
  Selalu tangani event `checkout.error` untuk memberikan pengalaman pengguna yang baik ketika terjadi kesalahan.
</Warning>

## Praktik Terbaik

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

## Pemecahan Masalah

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Mengaktifkan Dompet Digital

Untuk informasi detil tentang pengaturan Google Pay dan dompet digital lainnya, lihat halaman <a href="/features/payment-methods/digital-wallets">Dompet Digital</a>.

<Note>
  Apple Pay belum didukung dalam overlay checkout. Dukungan untuk Apple Pay segera hadir.
</Note>

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

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

## Sumber Daya Terkait

<CardGroup cols={2}>
  <Card title="Inline Checkout" icon="credit-card" href="/developer-resources/inline-checkout">
    Tanam checkout langsung ke dalam halaman Anda untuk pengalaman yang sepenuhnya terintegrasi.
  </Card>

  <Card title="Checkout Sessions API" icon="code" href="/api-reference/checkout-sessions/create">
    Buat sesi checkout untuk mendukung pengalaman checkout Anda.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer-resources/webhooks">
    Tangani event pembayaran pada sisi server dengan webhook.
  </Card>

  <Card title="Integration Guide" icon="book" href="/developer-resources/integration-guide">
    Panduan lengkap untuk mengintegrasikan Dodo Payments.
  </Card>
</CardGroup>

Untuk bantuan lebih lanjut, kunjungi [komunitas Discord](https://discord.gg/bYqAp4ayYh) kami atau hubungi tim dukungan pengembang kami.