Overlay Checkout

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

Demo Interaktif

Lihat checkout overlay dalam aksi 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 API buat sesi checkout.

Panduan Integrasi Langkah-demi-Langkah

Instal SDK

Instal SDK Checkout Dodo Payments menggunakan manajer paket pilihan Anda:

npm install dodopayments-checkout

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

Buat Komponen Tombol Checkout

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

Tambahkan Checkout ke Halaman Anda

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

Tangani Halaman Sukses dan Gagal

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

Uji Integrasi Anda

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 peristiwa 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	Diperlukan	Deskripsi
`mode`	`"test" \| "live"`	Ya	Mode lingkungan: `'test'` untuk pengembangan, `'live'` untuk produksi
`displayType`	`"overlay" \| "inline"`	Tidak	Tipe tampilan: `'overlay'` untuk checkout modal (default), `'inline'` untuk checkout tersemat
`onEvent`	`function`	Ya	Fungsi callback untuk menangani peristiwa checkout

Opsi Checkout

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

Opsi	Tipe	Diperlukan	Deskripsi
`checkoutUrl`	`string`	Ya	URL sesi checkout dari API buat sesi checkout
`options.showTimer`	`boolean`	Tidak	Tampilkan atau sembunyikan timer checkout. Defaultnya adalah `true`. Ketika dinonaktifkan, Anda akan menerima peristiwa `checkout.link_expired` ketika sesi berakhir.
`options.showSecurityBadge`	`boolean`	Tidak	Tampilkan atau sembunyikan lencana keamanan. Defaultnya adalah `true`.
`options.manualRedirect`	`boolean`	Tidak	Ketika diaktifkan, checkout tidak akan secara otomatis mengalihkan setelah selesai. Sebagai gantinya, Anda akan menerima peristiwa `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 peristiwa waktu nyata yang dapat Anda dengarkan melalui callback onEvent:

Data Peristiwa Status Checkout

Ketika manualRedirect diaktifkan, Anda menerima peristiwa checkout.status dengan data berikut:

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

Data Peristiwa Pengalihan Checkout Diminta

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

Tipe Peristiwa	Deskripsi
`checkout.opened`	Overlay checkout telah dibuka
`checkout.payment_page_opened`	Halaman pembayaran telah ditampilkan
`checkout.customer_details_submitted`	Detail pelanggan dan penagihan telah diserahkan
`checkout.closed`	Overlay checkout telah ditutup
`checkout.redirect`	Checkout akan melakukan pengalihan
`checkout.error`	Terjadi kesalahan selama checkout
`checkout.link_expired`	Ditembak ketika sesi checkout berakhir. Hanya diterima ketika `showTimer` diatur ke `false`.
`checkout.status`	Ditembak ketika `manualRedirect` diaktifkan. Berisi status checkout (`succeeded`, `failed`, atau `processing`).
`checkout.redirect_requested`	Ditembak ketika `manualRedirect` diaktifkan. Berisi URL untuk mengalihkan 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>

Dukungan TypeScript

SDK ditulis dalam TypeScript dan mencakup definisi tipe yang komprehensif. Semua API publik sepenuhnya diketik untuk pengalaman pengembang yang lebih baik dan dukungan IntelliSense.

import { DodoPayments, CheckoutEvent } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    // event is fully typed
    console.log(event.event_type, event.data);
  },
});

Penanganan Kesalahan

SDK menyediakan informasi kesalahan yang rinci melalui sistem peristiwa. Selalu terapkan penanganan kesalahan yang tepat di 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 peristiwa checkout.error untuk memberikan pengalaman pengguna yang baik ketika kesalahan terjadi.

Praktik Terbaik

Inisialisasi sekali: Inisialisasi SDK sekali saat aplikasi Anda dimuat, tidak pada setiap upaya checkout
Penanganan kesalahan: Selalu terapkan penanganan kesalahan yang tepat di callback peristiwa Anda
Mode pengujian: Gunakan mode test selama pengembangan dan beralih ke live hanya ketika siap untuk produksi
Penanganan peristiwa: Tangani semua peristiwa yang relevan untuk pengalaman pengguna yang lengkap
URL yang valid: Selalu gunakan URL checkout yang valid dari API buat sesi checkout
TypeScript: Gunakan TypeScript untuk keamanan tipe yang lebih baik dan pengalaman pengembang
Status pemuatan: Tampilkan status pemuatan saat checkout dibuka untuk meningkatkan UX
Pengalihan manual: Gunakan manualRedirect ketika Anda memerlukan kontrol kustom atas navigasi pasca-checkout
Manajemen timer: Nonaktifkan timer (showTimer: false) jika Anda ingin menangani kedaluwarsa sesi secara manual

Pemecahan Masalah

Checkout tidak terbuka

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 dari API buat sesi checkout
Verifikasi konektivitas jaringan

Peristiwa tidak terjadi

Kemungkinan penyebab:

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

Solusi:

Konfirmasi penangan peristiwa diatur dengan benar di Initialize()
Periksa konsol browser untuk kesalahan JavaScript
Verifikasi inisialisasi SDK selesai dengan sukses
Uji dengan penangan peristiwa sederhana terlebih dahulu

Masalah styling

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

Mengaktifkan Apple Pay

Apple Pay memungkinkan pelanggan untuk menyelesaikan pembayaran dengan cepat dan aman menggunakan metode pembayaran yang disimpan. Ketika diaktifkan, pelanggan dapat meluncurkan modal Apple Pay langsung dari overlay checkout di perangkat yang didukung.

Apple Pay didukung di iOS 17+, iPadOS 17+, dan Safari 17+ di macOS.

Untuk mengaktifkan Apple Pay untuk domain Anda di produksi, ikuti langkah-langkah berikut:

Unduh dan unggah file asosiasi domain Apple Pay

Unduh file asosiasi domain Apple Pay.Unggah file ke server web Anda di /.well-known/apple-developer-merchantid-domain-association. Misalnya, jika situs web Anda adalah example.com, buat file tersedia di https://example.com/well-known/apple-developer-merchantid-domain-association.

Minta aktivasi Apple Pay

Kirim email ke [email protected] dengan informasi berikut:

URL domain produksi Anda (misalnya, https://example.com)
Permintaan untuk mengaktifkan Apple Pay untuk domain Anda

Anda akan menerima konfirmasi dalam 1-2 hari kerja setelah Apple Pay diaktifkan untuk domain Anda.

Verifikasi ketersediaan Apple Pay

Setelah menerima konfirmasi, uji Apple Pay di checkout Anda:

Buka checkout Anda di perangkat yang didukung (iOS 17+, iPadOS 17+, atau Safari 17+ di macOS)
Verifikasi bahwa tombol Apple Pay muncul sebagai opsi pembayaran
Uji alur pembayaran lengkap

Apple Pay harus diaktifkan untuk domain Anda sebelum muncul sebagai opsi pembayaran di produksi. Hubungi dukungan sebelum go live jika Anda berencana untuk menawarkan Apple Pay.

Dukungan Browser

SDK Dodo Payments Checkout mendukung browser berikut:

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

Overlay vs Inline Checkout

Pilih jenis checkout yang tepat untuk kasus penggunaan Anda:

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

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

Sumber Daya Terkait

Checkout Inline

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

API Sesi Checkout

Buat sesi checkout untuk mendukung pengalaman checkout Anda.

Webhooks

Tangani peristiwa pembayaran di sisi server dengan webhooks.

Panduan Integrasi

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

Demo Interaktif

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

Dukungan TypeScript

Penanganan Kesalahan

Praktik Terbaik

Pemecahan Masalah

Mengaktifkan Apple Pay

Dukungan Browser

Overlay vs Inline Checkout

Sumber Daya Terkait

Checkout Inline

API Sesi Checkout

Webhooks

Panduan Integrasi

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Ikhtisar

​Demo

Demo Interaktif

​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

​Dukungan TypeScript

​Penanganan Kesalahan

​Praktik Terbaik

​Pemecahan Masalah

​Mengaktifkan Apple Pay

​Dukungan Browser

​Overlay vs Inline Checkout

​Sumber Daya Terkait

Checkout Inline

API Sesi Checkout

Webhooks

Panduan Integrasi

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

Dukungan TypeScript

Penanganan Kesalahan

Praktik Terbaik

Pemecahan Masalah

Mengaktifkan Apple Pay

Dukungan Browser

Overlay vs Inline Checkout

Sumber Daya Terkait