Overlay Checkout

Overlay checkout mở một cửa sổ modal phía trên trang của bạn. Khách hàng nhập thông tin thanh toán trong modal, trong khi trang của bạn vẫn hiển thị phía sau. Khi đóng modal, quyền điều khiển được trả về trang của bạn. Khi hoàn tất thanh toán, họ sẽ được chuyển hướng đến return_url.

Modal overlay checkout hiển thị phía trên trang sản phẩm

Interactive Demo

Xem overlay checkout hoạt động qua bản demo trực tiếp của chúng tôi.

Bắt đầu nhanh

Cài đặt SDK, khởi tạo SDK và mở checkout bằng URL checkout từ 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"
});

Tích hợp từng bước

Install the SDK

Cài đặt qua npm, yarn hoặc pnpm:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Gọi Initialize một lần khi ứng dụng tải, thường là trong component chính hoặc entry point của ứng dụng:

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

Luôn khởi tạo SDK trước khi mở checkout. Chỉ khởi tạo một lần khi ứng dụng tải, không khởi tạo trước mỗi lần thử checkout.

Create a Checkout Button

Tạo một component để mở 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

Sử dụng component nút checkout trong ứng dụng của bạn:

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

Tạo các trang để xử lý việc chuyển hướng checkout sau thanh toán:

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

Khởi động development server:

npm run dev

Kiểm thử quy trình checkout:
- Nhấp vào nút checkout
- Xác minh modal xuất hiện
- Kiểm thử quy trình thanh toán bằng thông tin xác thực test
- Xác nhận các chuyển hướng hoạt động chính xác

Bạn sẽ thấy các sự kiện checkout được ghi trong console của trình duyệt.

Go Live

Khi sẵn sàng cho production:

Thay đổi mode thành 'live':

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

Cập nhật các URL checkout để sử dụng checkout session trực tiếp từ backend của bạn
Kiểm thử toàn bộ quy trình trong production
Theo dõi các sự kiện và lỗi

Tham chiếu API

Khởi tạo

Gọi Initialize một lần để thiết lập SDK:

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

DodoPayments.Initialize(options);

Tùy chọn	Kiểu	Bắt buộc	Mô tả
`mode`	`"test" \| "live"`	Có	Mode môi trường: `"test"` cho development, `"live"` cho production
`displayType`	`"overlay" \| "inline"`	Không	Loại hiển thị: `"overlay"` cho modal checkout (mặc định), `"inline"` cho embedded checkout
`onEvent`	`function`	Có	Callback function để xử lý các sự kiện checkout

Mở Checkout

Mở 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);

Tùy chọn	Kiểu	Bắt buộc	Mô tả
`checkoutUrl`	`string`	Có	URL checkout session từ create checkout session API
`options.showTimer`	`boolean`	Không	Hiển thị hoặc ẩn bộ hẹn giờ của session. Mặc định là `true`. Khi bị vô hiệu hóa, bạn nhận được sự kiện `checkout.link_expired` khi session hết hạn.
`options.showSecurityBadge`	`boolean`	Không	Hiển thị hoặc ẩn huy hiệu bảo mật. Mặc định là `true`
`options.manualRedirect`	`boolean`	Không	Khi là `true`, ngăn chuyển hướng tự động. Checkout phát ra `checkout.status` cùng kết quả thanh toán và `checkout.redirect_requested` cùng URL cần mở; bạn sẽ tự xử lý điều hướng
`options.themeConfig`	`ThemeConfig`	Không	Đã deprecated. Thay vào đó, cấu hình theme phía server khi tạo checkout session
`options.payButtonText`	`string`	Không	Văn bản tùy chỉnh cho nút thanh toán
`options.fontSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	Không	Cỡ font toàn cục cho checkout
`options.fontWeight`	`"normal" \| "medium" \| "bold" \| "extraBold"`	Không	Độ đậm font toàn cục cho checkout

Đóng Checkout

Đóng modal bằng lập trình:

DodoPayments.Checkout.close();

Kiểm tra trạng thái

Kiểm tra xem modal hiện có đang mở hay không:

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

Sự kiện

Lắng nghe các sự kiện checkout thông qua callback onEvent được truyền vào 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;
    }
  }
});

Sự kiện	Mô tả
`checkout.opened`	Modal đã mở
`checkout.form_ready`	Form sẵn sàng để người dùng nhập. Dùng sự kiện này để ẩn trạng thái loading
`checkout.payment_page_opened`	Trang thanh toán được hiển thị
`checkout.customer_details_submitted`	Thông tin khách hàng và thanh toán được gửi
`checkout.closed`	Modal đã đóng
`checkout.redirect`	Checkout sẽ chuyển hướng (ví dụ: đến trang ngân hàng)
`checkout.error`	Đã xảy ra lỗi trong quá trình checkout
`checkout.link_expired`	Checkout session đã hết hạn. Chỉ nhận được sự kiện này khi `showTimer` được đặt thành `false`.

Triển khai CDN

Để tích hợp nhanh mà không cần build step, hãy tải SDK từ 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>

Tùy chỉnh Theme

Tùy chọn themeConfig phía client đã deprecated và sẽ bị xóa trong major version tiếp theo của Checkout SDK (v2.0.0). Việc truyền tùy chọn này sẽ ghi cảnh báo deprecated trong console của trình duyệt. Thay vào đó, hãy cấu hình theme khi tạo checkout session thông qua API bằng tham số customization.theme_config — xem Checkout Theme Customization — hoặc tùy chỉnh trực quan trên Design page trong dashboard. Theme được cấu hình theo session áp dụng cho overlay, inline và hosted checkout.

Phần này trình bày cách cấu hình theme phía client đã deprecated bằng Checkout SDK. Cách được khuyến nghị là cấu hình theme phía server khi tạo checkout session qua API bằng tham số theme_config. Xem Checkout Theme Customization để biết cách cấu hình ở cấp API hoặc sử dụng Design page trong dashboard để cấu hình theme trực quan với bản xem trước trực tiếp.

Nếu bắt buộc phải sử dụng cấu hình theme phía client, hãy truyền themeConfig trong tham số 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",
    },
  },
});

Thuộc tính Theme

Tất cả thuộc tính theme hiện có cho mode sáng và tối:

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

Xử lý lỗi

Luôn triển khai xử lý lỗi trong callback onEvent:

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

Luôn xử lý sự kiện checkout.error để mang lại trải nghiệm tốt cho người dùng khi xảy ra lỗi.

Phương pháp hay nhất

Khởi tạo một lần: Gọi Initialize một lần khi ứng dụng tải, không gọi trước mỗi checkout
Xử lý lỗi: Triển khai xử lý lỗi phù hợp trong event callback
Test mode: Sử dụng mode "test" trong quá trình phát triển và chỉ chuyển sang "live" khi sẵn sàng cho production
Xử lý sự kiện: Xử lý tất cả sự kiện liên quan để mang lại trải nghiệm hoàn chỉnh cho người dùng
URL hợp lệ: Luôn sử dụng URL checkout hợp lệ từ create checkout session API
TypeScript: Sử dụng TypeScript để tăng độ an toàn kiểu và cải thiện trải nghiệm developer
Trạng thái loading: Hiển thị trạng thái loading trong khi checkout đang mở để cải thiện UX
Quản lý bộ hẹn giờ: Vô hiệu hóa bộ hẹn giờ (showTimer: false) nếu bạn muốn tự xử lý việc session hết hạn

Khắc phục sự cố

Events not firing

Nguyên nhân có thể:

Event handler chưa được thiết lập đúng
Lỗi JavaScript ngăn chặn việc truyền sự kiện
SDK chưa được khởi tạo chính xác

Giải pháp:

Xác nhận event handler được cấu hình đúng trong Initialize()
Kiểm tra console của trình duyệt để tìm lỗi JavaScript
Xác minh quá trình khởi tạo SDK đã hoàn tất thành công
Trước tiên hãy kiểm thử bằng một event handler đơn giản

Styling issues

Nguyên nhân có thể:

CSS xung đột với style của ứng dụng
Cài đặt theme chưa được áp dụng chính xác
Sự cố responsive design

Giải pháp:

Kiểm tra xung đột CSS trong DevTools của trình duyệt
Xác minh cài đặt theme chính xác
Kiểm thử trên các kích thước màn hình khác nhau
Đảm bảo không có xung đột z-index với modal

Ví điện tử

Để biết thông tin chi tiết về cách thiết lập Google Pay và các ví điện tử khác, hãy xem trang Digital Wallets.

Apple Pay hiện chưa được hỗ trợ trong overlay checkout.

Hỗ trợ trình duyệt

Dodo Payments Checkout SDK hỗ trợ:

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

Overlay và Inline Checkout

Chọn loại checkout phù hợp với trường hợp sử dụng của bạn:

Tính năng	Overlay	Inline
Mức độ tích hợp	Modal phía trên trang	Được nhúng hoàn toàn vào trang
Khả năng kiểm soát bố cục	Hạn chế	Toàn quyền kiểm soát
Branding	Tách biệt với trang	Phù hợp với trang của bạn
Công sức triển khai	Thấp hơn	Cao hơn
Phù hợp nhất cho	Tích hợp nhanh, các trang hiện có	Trang checkout tùy chỉnh, quy trình có tỷ lệ chuyển đổi cao

Sử dụng overlay checkout để tích hợp nhanh hơn với ít thay đổi nhất cho các trang hiện có. Sử dụng inline checkout khi bạn muốn kiểm soát tối đa trải nghiệm checkout và duy trì branding nhất quán.

Tài nguyên liên quan

Inline Checkout

Nhúng checkout trực tiếp vào trang để có trải nghiệm tích hợp hoàn toàn.

Checkout Sessions API

Tạo checkout session để cung cấp các trải nghiệm checkout.

Webhooks

Xử lý các sự kiện thanh toán phía server bằng webhook.

Integration Guide

Hướng dẫn đầy đủ về cách tích hợp Dodo Payments.

Để được hỗ trợ thêm, hãy truy cập cộng đồng Discord hoặc liên hệ với đội ngũ hỗ trợ developer của chúng tôi.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Interactive Demo

Bắt đầu nhanh

Tích hợp từng bước

Tham chiếu API

Khởi tạo

Mở Checkout

Đóng Checkout

Kiểm tra trạng thái

Sự kiện

Triển khai CDN

Tùy chỉnh Theme

Thuộc tính Theme

Xử lý lỗi

Phương pháp hay nhất

Khắc phục sự cố

Ví điện tử

Hỗ trợ trình duyệt

Overlay và Inline Checkout

Tài nguyên liên quan

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Interactive Demo

​Bắt đầu nhanh

​Tích hợp từng bước

​Tham chiếu API

​Khởi tạo

​Mở Checkout

​Đóng Checkout

​Kiểm tra trạng thái

​Sự kiện

​Triển khai CDN

​Tùy chỉnh Theme

​Thuộc tính Theme

​Xử lý lỗi

​Phương pháp hay nhất

​Khắc phục sự cố

​Ví điện tử

​Hỗ trợ trình duyệt

​Overlay và Inline Checkout

​Tài nguyên liên quan

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Bắt đầu nhanh

Tích hợp từng bước

Tham chiếu API

Khởi tạo

Mở Checkout

Đóng Checkout

Kiểm tra trạng thái

Sự kiện

Triển khai CDN

Tùy chỉnh Theme

Thuộc tính Theme

Xử lý lỗi

Phương pháp hay nhất

Khắc phục sự cố

Ví điện tử

Hỗ trợ trình duyệt

Overlay và Inline Checkout

Tài nguyên liên quan