Chuyển đến nội dung chính

​
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.
Hình ảnh bìa Overlay Checkout

​
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'
  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

1

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
2

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

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

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

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

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

  1. Bắt đầu máy chủ phát triển của bạn:
npm run dev
  1. 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.
7

Đi vào sản xuất

Khi bạn đã sẵn sàng cho sản xuất:
  1. Thay đổi chế độ thành 'live':
DodoPayments.Initialize({
  mode: "live",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});
  1. 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
  2. Kiểm tra quy trình hoàn chỉnh trong sản xuất
  3. 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";
  onEvent: (event: CheckoutEvent) => void;
}
Tùy chọnLoạiBắt buộcMô tả
mode"test" | "live"CóChế độ môi trường: 'test' cho phát triển, 'live' cho sản xuất
onEventfunctionCóHàm callback để xử lý các sự kiện thanh toán

​
Tùy chọn thanh toán

interface CheckoutOptions {
  checkoutUrl: string;
}
Tùy chọnLoạiBắt buộcMô tả
checkoutUrlstringCóURL phiên thanh toán từ API tạo phiên thanh toán

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

​
Đó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ề liệu overlay thanh toán hiện đang mở hay không. 
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

​
Sự kiện

SDK cung cấp các sự kiện theo thời gian thực mà bạn có thể lắng nghe thông qua hàm callback onEvent: 
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;
    }
  }
});
Loại sự kiệnMô tả
checkout.openedOverlay thanh toán đã được mở
checkout.payment_page_openedTrang thanh toán đã được hiển thị
checkout.customer_details_submittedThông tin khách hàng và thanh toán đã được gửi
checkout.closedOverlay thanh toán đã được đóng
checkout.redirectThanh toán sẽ thực hiện một chuyển hướng
checkout.errorĐã xảy ra lỗi trong quá trình thanh toán

​
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 hiển thị 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
            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",
  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: 
DodoPayments.Initialize({
  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
    }
  }
});
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 tiễn tốt nhất

  1. 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 cố gắng thanh toán
  2. 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
  3. 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
  4. 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
  5. URL hợp lệ: Luôn sử dụng các URL thanh toán hợp lệ từ API tạo phiên thanh toán
  6. 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
  7. 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

​
Khắc phục sự cố

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 việc khởi tạo SDK diễn ra 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
Nguyên nhân có thể:
  • Trình xử lý sự kiện không được thiết lập đúng cách
  • Lỗi JavaScript ngăn chặn sự kiện phát tán
  • SDK không đượ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 việc khởi tạo SDK đã hoàn tất thành công
  • Thử nghiệm với một trình xử lý sự kiện đơn giản trước
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

​
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+
Apple Pay hiện không được hỗ trợ trong trải nghiệm thanh toán overlay. Chúng tôi dự định thêm hỗ trợ cho Apple Pay trong một bản phát hành trong tương lai.
Để 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.