Overlay Checkout - Dodo Payments Documentation

Tổng quan

SDK Thanh toán Dodo cung cấp một cách tích hợp liền mạch để đưa overlay thanh toán của chúng tôi vào ứng dụng web của bạn. Được xây dựng bằng TypeScript và các tiêu chuẩn web hiện đại, nó cung cấp một giải pháp mạnh mẽ để xử lý thanh toán với việc xử lý sự kiện theo thời gian thực và các chủ đề tùy chỉnh.

Demo

Interactive Demo

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

Bắt đầu nhanh

Bắt đầu với SDK Thanh toán Dodo chỉ trong vài dòng mã:

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

Lấy URL thanh toán từ API tạo phiên thanh toán.

Hướng dẫn tích hợp từng bước

Install the SDK

Cài đặt SDK Thanh toán Dodo bằng cách sử dụng trình quản lý gói ưa thích của bạn:

npm install dodopayments-checkout

yarn add dodopayments-checkout

pnpm add dodopayments-checkout

Initialize the SDK

Khởi tạo SDK trong ứng dụng của bạn, thường là trong thành phần chính hoặc điểm vào ứng dụng:

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

Luôn khởi tạo SDK trước khi cố mở thanh toán. Việc khởi tạo chỉ nên diễn ra một lần khi ứng dụng của bạn tải lên.

Create a Checkout Button Component

Tạo một thành phần mở overlay thanh toán:

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

Sử dụng thành phần nút thanh toán 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 Success and Failure Pages

Tạo các trang để xử lý chuyển hướng 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

Bắt đầu máy chủ phát triển của bạn:

npm run dev

Kiểm tra quy trình thanh toán:
- Nhấp vào nút thanh toán
- Xác minh overlay xuất hiện
- Kiểm tra quy trình thanh toán bằng cách sử dụng thông tin xác thực thử nghiệm
- 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 thanh toán được ghi lại trong bảng điều khiển trình duyệt.

Go Live

Khi bạn đã sẵn sàng cho sản xuất:

Thay đổi chế độ thành 'live':

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

Cập nhật các URL thanh toán của bạn để sử dụng các phiên thanh toán trực tiếp từ backend của bạn
Kiểm tra quy trình hoàn chỉnh trong sản xuất
Giám sát các sự kiện và lỗi

Tài liệu API

Cấu hình

Tùy chọn khởi tạo

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

Tùy chọn	Loại	Bắt buộc	Mô tả
`mode`	`"test" \| "live"`	Có	Chế độ môi trường: `'test'` cho phát triển, `'live'` cho sản xuất
`displayType`	`"overlay" \| "inline"`	Không	Loại hiển thị: `'overlay'` cho thanh toán modal (mặc định), `'inline'` cho thanh toán nhúng
`onEvent`	`function`	Có	Hàm gọi lại để xử lý các sự kiện thanh toán

Tùy chọn thanh toán

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

Lựa chọn	Loại	Bắt buộc	Mô tả
`checkoutUrl`	`string`	Có	URL phiên thanh toán từ API tạo phiên thanh toán
`options.showTimer`	`boolean`	Không	Hiện hoặc ẩn đồng hồ đếm ngược. Mặc định là `true`. Khi bị vô hiệu, bạn sẽ nhận được sự kiện `checkout.link_expired` khi phiên hết hạn.
`options.showSecurityBadge`	`boolean`	Không	Hiện hoặc ẩn huy hiệu bảo mật. Mặc định là `true`.

Phương thức

Mở thanh toán

Mở overlay thanh toán với URL phiên thanh toán đã chỉ định.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Bạn cũng có thể truyền thêm tùy chọn để tùy chỉnh hành vi thanh toán:

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

Đóng Checkout

Đóng giao diện thanh toán bằng lập trình.

DodoPayments.Checkout.close();

Kiểm tra Trạng thái

Trả về trạng thái giao diện thanh toán hiện đang mở hay không.

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

Sự kiện

SDK cung cấp sự kiện theo thời gian thực mà bạn có thể nghe qua 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;
    }
  }
});

Loại Sự kiện	Mô tả
`checkout.opened`	Giao diện thanh toán đã được mở
`checkout.form_ready`	Biểu mẫu thanh toán đã sẵn sàng nhận thông tin từ người dùng. Hữu ích để ẩn trạng thái tải.
`checkout.payment_page_opened`	Trang thanh toán đã được hiển thị
`checkout.customer_details_submitted`	Thông tin khách hàng và hóa đơn đã được gửi
`checkout.closed`	Giao diện thanh toán đã được đóng
`checkout.redirect`	Thanh toán sẽ thực hiện chuyển hướng
`checkout.error`	Xảy ra lỗi trong quá trình thanh toán
`checkout.link_expired`	Kích hoạt khi phiên thanh toán hết hạn. Chỉ nhận được khi `showTimer` được đặt thành `false`.

Tùy chọn Triển khai

Cài đặt Trình quản lý Gói

Cài đặt qua npm, yarn, hoặc pnpm như được trình bày trong Hướng dẫn Tích hợp Từng Bước.

Triển khai CDN

Để tích hợp nhanh mà không cần bước xây dựng, bạn có thể sử dụng CDN của chúng tôi:

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

Tùy chỉnh Giao diện

Bạn có thể tùy chỉnh giao diện thanh toán bằng cách truyền đối tượng themeConfig vào tham số options khi mở thanh toán. Cấu hình giao diện hỗ trợ cả chế độ sáng và tối, cho phép bạn tùy chỉnh màu sắc, viền, văn bản, nút, và bán kính viền.

Tùy chọn themeConfig phía client đã deprecated và sẽ bị xóa trong phiên bản major tiếp theo của Checkout SDK (v2.0.0). Việc truyền tùy chọn này sẽ ghi lại 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 qua API bằng tham số customization.theme_config — xem Tùy chỉnh Checkout Theme — hoặc thực hiện trực quan trên trang Design trong dashboard. Các theme được cấu hình cho session áp dụng như nhau cho overlay checkout, inline checkout 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. Phương pháp đượ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 Tùy chỉnh Checkout Theme để biết cách cấu hình ở cấp API, hoặc sử dụng trang Design trong dashboard để cấu hình theme trực quan với bản xem trước trực tiếp.

Cấu hình Theme cơ bản

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

Cấu hình Theme đầy đủ

Tất cả thuộc tính theme hiện có:

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

Chỉ chế độ sáng

Nếu bạn chỉ muốn tùy chỉnh theme sáng:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Chỉ chế độ tối

Nếu bạn chỉ muốn tùy chỉnh theme tối:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Ghi đè một phần Theme

Bạn chỉ có thể ghi đè các thuộc tính cụ thể. Checkout sẽ sử dụng các giá trị mặc định cho những thuộc tính bạn không chỉ định:

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

Cấu hình Theme cùng các tùy chọn khác

Bạn có thể kết hợp cấu hình theme với các tùy chọn checkout khác:

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

Kiểu TypeScript

Đối với người dùng TypeScript, tất cả các kiểu cấu hình theme đều được export:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Xử lý lỗi

SDK cung cấp thông tin lỗi chi tiết thông qua hệ thống event. Luôn triển khai xử lý lỗi phù hợp trong callback onEvent của bạn:

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

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

Các phương pháp hay nhất

Khởi tạo một lần: Khởi tạo SDK một lần khi ứng dụng tải, không phải mỗi lần thử checkout
Xử lý lỗi: Luôn triển khai xử lý lỗi phù hợp trong event callback
Chế độ test: Sử dụng chế độ test trong quá trình phát triển và chỉ chuyển sang live khi sẵn sàng cho production
Xử lý event: Xử lý tất cả event liên quan để mang lại trải nghiệm người dùng hoàn chỉnh
URL hợp lệ: Luôn sử dụng các URL checkout hợp lệ từ API create checkout session
TypeScript: Sử dụng TypeScript để có type safety và trải nghiệm phát triển tốt hơn
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ý timer: Tắt timer (showTimer: false) nếu bạn muốn tự xử lý việc session hết hạn

Khắc phục sự cố

Checkout not opening

Nguyên nhân có thể xảy ra:

SDK chưa được khởi tạo trước khi gọi open()
URL checkout không hợp lệ
Lỗi JavaScript trong console
Sự cố kết nối mạng

Giải pháp:

Xác minh SDK được khởi tạo trước khi mở checkout
Kiểm tra lỗi trong console
Đảm bảo URL checkout hợp lệ và đến từ API create checkout session
Kiểm tra kết nối mạng

Events not firing

Nguyên nhân có thể xảy ra:

Event handler chưa được thiết lập đúng cách
Lỗi JavaScript ngăn event propagation
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 thử với một event handler đơn giản

Styling issues

Nguyên nhân có thể xảy ra:

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
Vấn đề về thiết kế responsive

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 overlay

Bật Digital Wallet

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

Apple Pay hiện chưa được hỗ trợ trong overlay checkout. Tính năng hỗ trợ Apple Pay sẽ sớm được ra mắt.

Trình duyệt được hỗ trợ

Dodo Payments Checkout SDK hỗ trợ các trình duyệt sau:

Chrome (mới nhất)
Firefox (mới nhất)
Safari (mới nhất)
Edge (mới nhất)
IE11+

Overlay Checkout 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 Checkout	Inline Checkout
Mức độ tích hợp	Modal nằm trên trang	Được nhúng hoàn toàn trong 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	Liền mạch
Công sức triển khai	Thấp hơn	Cao hơn
Phù hợp nhất với	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 liền mạch.

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

​Tổng quan

​Demo

Interactive Demo

​Bắt đầu nhanh

​Hướng dẫn tích hợp từng bước

​Tài liệu API

​Cấu hình

​Tùy chọn khởi tạo

​Tùy chọn thanh toán

​Phương thức

​Mở thanh toán

​Đóng Checkout

​Kiểm tra Trạng thái

​Sự kiện

​Tùy chọn Triển khai

​Cài đặt Trình quản lý Gói

​Triển khai CDN

​Tùy chỉnh Giao diện

​Cấu hình Theme cơ bản

​Cấu hình Theme đầy đủ

​Chỉ chế độ sáng

​Chỉ chế độ tối

​Ghi đè một phần Theme

​Cấu hình Theme cùng các tùy chọn khác

​Kiểu TypeScript

​Xử lý lỗi

​Các phương pháp hay nhất

​Khắc phục sự cố

​Bật Digital Wallet

​Trình duyệt được hỗ trợ

​Overlay Checkout và Inline Checkout

​Tài nguyên liên quan

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Tổng quan

Demo

Bắt đầu nhanh

Hướng dẫn tích hợp từng bước

Tài liệu API

Cấu hình

Tùy chọn khởi tạo

Tùy chọn thanh toán

Phương thức

Mở thanh toán

Đóng Checkout

Kiểm tra Trạng thái

Sự kiện

Tùy chọn Triển khai

Cài đặt Trình quản lý Gói

Triển khai CDN

Tùy chỉnh Giao diện

Cấu hình Theme cơ bản

Cấu hình Theme đầy đủ

Chỉ chế độ sáng

Chỉ chế độ tối

Ghi đè một phần Theme

Cấu hình Theme cùng các tùy chọn khác

Kiểu TypeScript

Xử lý lỗi

Các phương pháp hay nhất

Khắc phục sự cố

Bật Digital Wallet

Trình duyệt được hỗ trợ

Overlay Checkout và Inline Checkout

Tài nguyên liên quan