Overlay Checkout

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

Demo Tương tác

Xem overlay checkout hoạt động với 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 của bạn từ API tạo phiên thanh toán.

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

Cài đặt 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

Khởi tạo 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ố gắng mở thanh toán. Việc khởi tạo nên diễn ra một lần khi ứng dụng của bạn tải.

Tạo thành phần nút thanh toán

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

Thêm thanh toán vào trang của bạn

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

Xử lý trang thành công và thất bại

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

Kiểm tra tích hợp của bạn

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 nên 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 của bạn.

Đi vào sản xuất

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

Tùy 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 thị hoặc ẩn bộ đếm thời gian thanh toán. Mặc định là `true`. Khi bị vô hiệu hóa, 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 thị hoặc ẩn huy hiệu bảo mật. Mặc định là `true`.
`options.manualRedirect`	`boolean`	Không	Khi được kích hoạt, thanh toán sẽ không tự động chuyển hướng sau khi hoàn tất. Thay vào đó, bạn sẽ nhận được các sự kiện `checkout.status` và `checkout.redirect_requested` để tự xử lý việc chuyển hướng.

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

Khi sử dụng manualRedirect, xử lý việc hoàn tất thanh toán trong hàm callback onEvent của bạn:

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

Đóng Thanh Toán

Đóng overlay thanh toán một cách lập trình.

DodoPayments.Checkout.close();

Kiểm Tra Trạng Thái

Trả về trạng thái hiện tại của overlay thanh toán.

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

Sự Kiện

SDK cung cấp các sự kiện thời gian thực mà bạn có thể lắng nghe thông qua hàm callback onEvent:

Dữ Liệu Sự Kiện Trạng Thái Thanh Toán

Khi manualRedirect được kích hoạt, bạn nhận được sự kiện checkout.status với các dữ liệu sau:

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

Dữ Liệu Sự Kiện Yêu Cầu Chuyển Hướng Thanh Toán

Khi manualRedirect được kích hoạt, bạn nhận được sự kiện checkout.redirect_requested với các dữ liệu sau:

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

Loại Sự Kiện	Mô tả
`checkout.opened`	Overlay thanh toán đã được mở
`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`	Overlay 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`	Được 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`.
`checkout.status`	Được kích hoạt khi `manualRedirect` được kích hoạt. Chứa trạng thái thanh toán (`succeeded`, `failed`, hoặc `processing`).
`checkout.redirect_requested`	Được kích hoạt khi `manualRedirect` được kích hoạt. Chứa URL để chuyển hướng khách hàng.

Tùy Chọn Triển Khai

Cài Đặt Qua Trình Quản Lý Gói

Cài đặt qua npm, yarn hoặc pnpm như được mô tả 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>

Hỗ Trợ TypeScript

SDK được viết bằng TypeScript và bao gồm các định nghĩa kiểu toàn diện. Tất cả các API công khai đều được định kiểu đầy đủ để cải thiện trải nghiệm lập trình viên và hỗ trợ 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);
  },
});

Xử Lý Lỗi

SDK cung cấp thông tin lỗi chi tiết thông qua hệ thống sự kiện. Luôn thực hiện xử lý lỗi đúng cách trong hàm 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ý sự kiện checkout.error để cung cấp trải nghiệm người dùng tốt khi xảy ra lỗi.

Thực Hành Tốt Nhất

Khởi tạo một lần: Khởi tạo SDK một lần khi ứng dụng của bạn tải, không phải trên mỗi lần thử thanh toán
Xử lý lỗi: Luôn thực hiện xử lý lỗi đúng cách trong hàm callback sự kiện của bạn
Chế độ thử nghiệm: Sử dụng chế độ test trong quá trình phát triển và chuyển sang live chỉ khi sẵn sàng cho sản xuất
Xử lý sự kiện: Xử lý tất cả các sự kiện liên quan để có trải nghiệm người dùng hoàn chỉnh
URL hợp lệ: Luôn sử dụng URL thanh toán hợp lệ từ API tạo phiên thanh toán
TypeScript: Sử dụng TypeScript để có độ an toàn kiểu tốt hơn và trải nghiệm lập trình viên tốt hơn
Trạng thái tải: Hiển thị trạng thái tải trong khi thanh toán đang mở để cải thiện UX
Chuyển hướng thủ công: Sử dụng manualRedirect khi bạn cần kiểm soát tùy chỉnh về điều hướng sau thanh toán
Quản lý bộ đếm thời gian: Vô hiệu hóa bộ đếm thời gian (showTimer: false) nếu bạn muốn xử lý việc hết hạn phiên một cách thủ công

Khắc Phục Sự Cố

Thanh toán không mở

Nguyên nhân có thể:

SDK chưa được khởi tạo trước khi gọi open()
URL thanh toán không hợp lệ
Lỗi JavaScript trong bảng điều khiển
Vấn đề kết nối mạng

Giải pháp:

Xác minh rằng SDK đã được khởi tạo trước khi mở thanh toán
Kiểm tra lỗi trong bảng điều khiển
Đảm bảo URL thanh toán hợp lệ và từ API tạo phiên thanh toán
Xác minh kết nối mạng

Sự kiện không được kích hoạt

Nguyên nhân có thể:

Trình xử lý sự kiện chưa được thiết lập đúng cách
Lỗi JavaScript ngăn cản sự lan truyền sự kiện
SDK chưa được khởi tạo đúng cách

Giải pháp:

Xác nhận rằng trình xử lý sự kiện đã được cấu hình đúng trong Initialize()
Kiểm tra bảng điều khiển trình duyệt để tìm lỗi JavaScript
Xác minh rằng SDK đã được khởi tạo thành công
Thử nghiệm với một trình xử lý sự kiện đơn giản trước

Vấn đề về kiểu dáng

Nguyên nhân có thể:

Xung đột CSS với kiểu dáng ứng dụng của bạn
Cài đặt chủ đề không được áp dụng đúng cách
Vấn đề thiết kế đáp ứng

Giải pháp:

Kiểm tra xung đột CSS trong DevTools của trình duyệt
Xác minh rằng cài đặt chủ đề là chính xác
Thử nghiệm 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

Kích Hoạt Apple Pay

Apple Pay cho phép khách hàng hoàn tất thanh toán nhanh chóng và an toàn bằng cách sử dụng các phương thức thanh toán đã lưu. Khi được kích hoạt, khách hàng có thể khởi động modal Apple Pay trực tiếp từ overlay thanh toán trên các thiết bị hỗ trợ.

Apple Pay được hỗ trợ trên iOS 17+, iPadOS 17+ và Safari 17+ trên macOS.

Để kích hoạt Apple Pay cho miền của bạn trong môi trường sản xuất, hãy làm theo các bước sau:

Tải xuống và tải lên tệp liên kết miền Apple Pay

Tải xuống tệp liên kết miền Apple Pay.Tải tệp lên máy chủ web của bạn tại /.well-known/apple-developer-merchantid-domain-association. Ví dụ, nếu trang web của bạn là example.com, hãy làm cho tệp có sẵn tại https://example.com/well-known/apple-developer-merchantid-domain-association.

Yêu cầu kích hoạt Apple Pay

Gửi email đến [email protected] với các thông tin sau:

URL miền sản xuất của bạn (ví dụ: https://example.com)
Yêu cầu kích hoạt Apple Pay cho miền của bạn

Bạn sẽ nhận được xác nhận trong vòng 1-2 ngày làm việc sau khi Apple Pay đã được kích hoạt cho miền của bạn.

Xác minh tính khả dụng của Apple Pay

Sau khi nhận được xác nhận, hãy thử nghiệm Apple Pay trong thanh toán của bạn:

Mở thanh toán của bạn trên một thiết bị hỗ trợ (iOS 17+, iPadOS 17+, hoặc Safari 17+ trên macOS)
Xác minh rằng nút Apple Pay xuất hiện như một tùy chọn thanh toán
Thử nghiệm toàn bộ quy trình thanh toán

Apple Pay phải được kích hoạt cho miền của bạn trước khi nó xuất hiện như một tùy chọn thanh toán trong môi trường sản xuất. Liên hệ với hỗ trợ trước khi ra mắt nếu bạn dự định cung cấp Apple Pay.

Hỗ Trợ Trình Duyệt

SDK Thanh Toán Dodo 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+

Thanh Toán Overlay vs Inline

Chọn loại thanh toán phù hợp cho trường hợp sử dụng của bạn:

Tính năng	Thanh toán Overlay	Thanh toán Inline
Độ sâu tích hợp	Modal trên trang	Hoàn toàn nhúng trong trang
Kiểm soát bố cục	Hạn chế	Kiểm soát đầy đủ
Thương hiệu	Tách biệt khỏi trang	Liền mạch
Nỗ lực triển khai	Thấp hơn	Cao hơn
Tốt nhất cho	Tích hợp nhanh, trang hiện có	Trang thanh toán tùy chỉnh, quy trình chuyển đổi cao

Sử dụng thanh toán overlay để tích hợp nhanh với thay đổi tối thiểu cho các trang hiện có của bạn. Sử dụng thanh toán inline khi bạn muốn kiểm soát tối đa trải nghiệm thanh toán và thương hiệu liền mạch.

Tài Nguyên Liên Quan

Thanh Toán Inline

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

API Phiên Thanh Toán

Tạo các phiên thanh toán để cung cấp trải nghiệm thanh toán của bạn.

Webhooks

Xử lý các sự kiện thanh toán phía máy chủ bằng webhooks.

Hướng Dẫn Tích Hợp

Hướng dẫn hoàn chỉnh để tích hợp Dodo Payments.

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tổng quan

Demo

Demo Tương tác

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 Thanh Toán

Kiểm Tra Trạng Thái

Sự Kiện

Dữ Liệu Sự Kiện Trạng Thái Thanh Toán

Dữ Liệu Sự Kiện Yêu Cầu Chuyển Hướng Thanh Toán

Tùy Chọn Triển Khai

Cài Đặt Qua Trình Quản Lý Gói

Triển Khai CDN

Hỗ Trợ TypeScript

Xử Lý Lỗi

Thực Hành Tốt Nhất

Khắc Phục Sự Cố

Kích Hoạt Apple Pay

Hỗ Trợ Trình Duyệt

Thanh Toán Overlay vs Inline

Tài Nguyên Liên Quan

Thanh Toán Inline

API Phiên Thanh Toán

Webhooks

Hướng Dẫn Tích Hợp

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Tổng quan

​Demo

Demo Tương tác

​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 Thanh Toán

​Kiểm Tra Trạng Thái

​Sự Kiện

​Dữ Liệu Sự Kiện Trạng Thái Thanh Toán

​Dữ Liệu Sự Kiện Yêu Cầu Chuyển Hướng Thanh Toán

​Tùy Chọn Triển Khai

​Cài Đặt Qua Trình Quản Lý Gói

​Triển Khai CDN

​Hỗ Trợ TypeScript

​Xử Lý Lỗi

​Thực Hành Tốt Nhất

​Khắc Phục Sự Cố

​Kích Hoạt Apple Pay

​Hỗ Trợ Trình Duyệt

​Thanh Toán Overlay vs Inline

​Tài Nguyên Liên Quan

Thanh Toán Inline

API Phiên Thanh Toán

Webhooks

Hướng Dẫn Tích Hợp

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 Thanh Toán

Kiểm Tra Trạng Thái

Sự Kiện

Dữ Liệu Sự Kiện Trạng Thái Thanh Toán

Dữ Liệu Sự Kiện Yêu Cầu Chuyển Hướng Thanh Toán

Tùy Chọn Triển Khai

Cài Đặt Qua Trình Quản Lý Gói

Triển Khai CDN

Hỗ Trợ TypeScript

Xử Lý Lỗi

Thực Hành Tốt Nhất

Khắc Phục Sự Cố

Kích Hoạt Apple Pay

Hỗ Trợ Trình Duyệt

Thanh Toán Overlay vs Inline

Tài Nguyên Liên Quan