Skip to main content
Inline checkout nhúng biểu mẫu thanh toán bảo mật trực tiếp vào bố cục trang của bạn. Khác với overlay checkout, mở dưới dạng modal, inline checkout trở thành một phần trong trang của bạn. Bạn kiểm soát bố cục và có thể hiển thị phần tóm tắt đơn hàng riêng bên cạnh biểu mẫu checkout.
Biểu mẫu inline checkout được nhúng trong trang sản phẩm cùng phần tóm tắt đơn hàng

Cách hoạt động

Inline checkout hiển thị một frame bảo mật của Dodo Payments trong một container trên trang của bạn. Frame này xử lý việc thu thập thông tin khách hàng và thông tin thanh toán. Trang của bạn hiển thị các mặt hàng, tổng tiền và những thông tin khác. SDK cho phép trang của bạn và checkout frame giao tiếp với nhau. Khi checkout hoàn tất, Dodo Payments tạo payment hoặc subscription đối với sản phẩm subscription, rồi gửi webhook để bạn cấp quyền truy cập.
Inline checkout frame xử lý an toàn toàn bộ thông tin thanh toán nhạy cảm, đảm bảo tuân thủ PCI mà không yêu cầu bạn phải có thêm chứng nhận.

Đặc điểm của Inline Checkout tốt

Khách hàng cần biết họ đang mua từ ai, mua gì và sẽ thanh toán bao nhiêu. Phần triển khai của bạn phải bao gồm:
Ví dụ inline checkout với các thành phần bắt buộc được chú thích

Example inline checkout layout showing required elements

  1. Thông tin định kỳ: Nếu là khoản thanh toán định kỳ, hãy hiển thị tần suất lặp lại và tổng số tiền cần thanh toán khi gia hạn. Nếu có thời gian dùng thử, hãy hiển thị thời lượng dùng thử.
  2. Mô tả mặt hàng: Mô tả nội dung khách hàng đang mua.
  3. Tổng giao dịch: Subtotal, tổng tax và grand total, bao gồm currency.
  4. Dodo Payments footer: Toàn bộ inline checkout frame, bao gồm footer có thông tin Dodo Payments, điều khoản bán hàng và privacy policy.
  5. Refund policy: Liên kết đến refund policy của bạn nếu chính sách này khác với refund policy tiêu chuẩn của Dodo Payments.
Luôn hiển thị toàn bộ inline checkout frame, bao gồm footer. Việc xóa hoặc ẩn thông tin pháp lý sẽ vi phạm các yêu cầu tuân thủ.

Hành trình khách hàng

Luồng checkout phụ thuộc vào cấu hình checkout session của bạn. Tùy theo cách bạn cấu hình session, khách hàng có thể xem toàn bộ thông tin trên một trang hoặc qua nhiều bước.
1

Customer opens checkout

Bạn mở inline checkout bằng cách truyền checkout URL. Sử dụng các SDK event, chẳng hạn như checkout.breakdown, để hiển thị và cập nhật thông tin trên trang.Trang checkout ban đầu với danh sách mặt hàng và biểu mẫu thanh toán
2

Customer enters their details

Trước tiên, inline checkout yêu cầu khách hàng nhập địa chỉ email, chọn quốc gia và, khi cần, nhập ZIP hoặc postal code. Bước này thu thập toàn bộ thông tin cần thiết để xác định tax và các payment option khả dụng.Bạn có thể điền trước thông tin khách hàng và hiển thị các địa chỉ đã lưu để rút gọn quy trình.
3

Customer selects payment method

Sau khi nhập thông tin, khách hàng sẽ thấy các payment method khả dụng và biểu mẫu thanh toán. Các lựa chọn có thể bao gồm credit card hoặc debit card, PayPal, Apple Pay, Google Pay và những payment method địa phương khác tùy theo vị trí của khách hàng.Hiển thị các payment method đã lưu nếu có để tăng tốc checkout.Các payment method khả dụng và biểu mẫu nhập thông tin thẻ
4

Checkout completed

Dodo Payments định tuyến mọi payment đến acquirer phù hợp nhất cho giao dịch đó nhằm tăng khả năng thành công. Khách hàng sẽ chuyển đến success workflow mà bạn có thể xây dựng.Màn hình thành công với dấu kiểm xác nhận
5

Dodo Payments creates the payment or subscription

Dodo Payments tạo payment hoặc subscription đối với sản phẩm subscription, rồi gửi webhook để bạn cấp quyền truy cập. Payment method mà khách hàng đã sử dụng được lưu lại để dùng cho các lần gia hạn hoặc thay đổi subscription.Subscription đã được tạo cùng thông báo webhook

Bắt đầu nhanh

Cài đặt SDK, khởi tạo SDK ở inline mode và mở checkout trong một container element:
Đảm bảo trang của bạn có container element với id tương ứng: <div id="dodo-inline-checkout"></div>.

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

1

Install the SDK

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

Initialize the SDK for Inline Display

Khởi tạo SDK và chỉ định displayType: 'inline'. Lắng nghe event checkout.breakdown để cập nhật UI với các phép tính tax và total theo thời gian thực:
3

Create a Container Element

Thêm một element vào HTML nơi checkout frame sẽ được chèn vào:
4

Open the Checkout

Gọi DodoPayments.Checkout.open() với checkoutUrl và elementId của container:
5

Test Your Integration

  1. Khởi động development server:
  1. Kiểm thử luồng checkout:
    • Nhập email và thông tin địa chỉ trong inline frame
    • Xác minh rằng phần tóm tắt đơn hàng tùy chỉnh được cập nhật theo thời gian thực
    • Kiểm thử luồng thanh toán bằng test credentials
    • Xác nhận redirect hoạt động chính xác
Bạn sẽ thấy các event checkout.breakdown được ghi trong browser console nếu đã thêm console log vào callback onEvent.
6

Go Live

Khi sẵn sàng cho production:
  1. Chuyển mode thành 'live':
  1. Cập nhật checkout URL để sử dụng live checkout session từ backend
  2. Kiểm thử toàn bộ luồng trong production

Ví dụ React hoàn chỉnh

Ví dụ này minh họa cách triển khai phần tóm tắt đơn hàng tùy chỉnh bên cạnh inline checkout và giữ cho hai phần đồng bộ bằng event checkout.breakdown:

Tham chiếu API

Khởi tạo

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

Mở Checkout

Mở checkout frame trong một container:

Đóng Checkout

Xóa checkout frame theo program và dọn dẹp event listener:

Kiểm tra trạng thái

Kiểm tra xem checkout frame hiện đã được inject hay chưa:

Event

SDK cung cấp event theo thời gian thực thông qua callback onEvent. Đối với inline checkout, checkout.breakdown đặc biệt hữu ích để đồng bộ UI:

Dữ liệu phân tích Checkout

Event checkout.breakdown cung cấp thông tin về price và tax:
Event được phát khi checkout frame tải xong và một lần nữa mỗi khi price được tính lại, chẳng hạn khi khách hàng chọn quốc gia hoặc nhập postal code làm thay đổi tax. Chi tiết field: Mẹo tích hợp:
  1. Định dạng currency: Price là số nguyên theo đơn vị nhỏ nhất của currency, chẳng hạn cent đối với USD. Với currency có hai chữ số thập phân, hãy chia cho 100 trước khi định dạng bằng Intl.NumberFormat. Currency không có chữ số thập phân như JPY không có đơn vị nhỏ hơn, vì vậy không chia các giá trị này.
  2. Xử lý trạng thái ban đầu: Khi checkout vừa tải, tax và discount có thể là 0 hoặc null cho đến khi người dùng cung cấp thông tin billing hoặc áp dụng code. Hãy xử lý các trạng thái này phù hợp, chẳng hạn hiển thị dấu gạch ngang — hoặc ẩn row.
  3. “Final Total” và “Total”: Mặc dù total cung cấp phép tính price tiêu chuẩn, finalTotal mới là nguồn dữ liệu chính xác cho giao dịch. Nếu finalTotal tồn tại, giá trị này phản ánh chính xác số tiền sẽ được charge vào card của khách hàng.
  4. Phản hồi theo thời gian thực: Sử dụng field tax để cho người dùng biết tax đang được tính theo thời gian thực. Điều này giúp trang checkout có cảm giác “live” và giảm trở ngại trong bước nhập địa chỉ.

Triển khai qua CDN

Để tích hợp nhanh mà không cần build step, hãy load SDK từ CDN:

Cập nhật Payment Method

Inline checkout hỗ trợ cập nhật payment method cho subscription. Khi khách hàng cần cập nhật payment method cho subscription đang hoạt động hoặc kích hoạt lại subscription đang on-hold, bạn có thể hiển thị flow cập nhật trực tiếp trong bố cục trang.

Cách hoạt động

  1. Gọi Update Payment Method API để lấy một payment_link:
  1. Truyền payment_link nhận được làm checkoutUrl để mở inline checkout:
Inline frame chỉ hiển thị form thu thập payment method. Khách hàng có thể nhập thông tin card mới hoặc chọn payment method đã lưu mà không cần rời khỏi trang.

Đối với Subscription đang On-Hold

Khi cập nhật payment method cho subscription ở trạng thái on_hold, Dodo Payments tự động tạo charge cho mọi khoản còn nợ. Theo dõi webhook payment.succeeded và subscription.active để xác nhận việc kích hoạt lại.
Bạn cũng có thể sử dụng payment method đã lưu thay vì thu thập thông tin mới bằng cách truyền type: 'existing' cùng với payment_method_id đến Update Payment Method API.

Xử lý lỗi

Luôn triển khai xử lý lỗi trong callback onEvent:
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.

Best Practices

  1. Responsive Design: Đảm bảo container element có đủ chiều rộng và chiều cao. iframe thường sẽ mở rộng để lấp đầy container.
  2. Đồng bộ hóa: Sử dụng event checkout.breakdown để giữ phần tóm tắt đơn hàng hoặc bảng price tùy chỉnh đồng bộ với nội dung người dùng thấy trong checkout frame.
  3. Skeleton State: Hiển thị loading indicator trong container cho đến khi event checkout.opened được phát.
  4. Dọn dẹp: Gọi DodoPayments.Checkout.close() khi component unmount để dọn dẹp iframe và event listener.
Đối với phần triển khai dark mode, hãy sử dụng #0d0d0d làm màu nền để inline checkout frame tích hợp trực quan tối ưu.

Xác thực trạng thái Payment

Không chỉ dựa vào event của inline checkout để xác định payment thành công hay thất bại. Luôn triển khai xác thực phía server bằng webhook và/hoặc polling.

Vì sao xác thực phía Server là cần thiết

Mặc dù event của inline checkout cung cấp phản hồi theo thời gian thực, bạn không nên coi chúng là nguồn dữ liệu duy nhất về trạng thái payment. Sự cố mạng, trình duyệt bị crash hoặc người dùng đóng trang có thể khiến event bị bỏ lỡ. Để đảm bảo xác thực payment đáng tin cậy:
  1. Lắng nghe webhook event - Dodo Payments gửi webhook khi trạng thái payment thay đổi
  2. Triển khai cơ chế polling - Frontend nên polling server để lấy thông tin cập nhật trạng thái
  3. Kết hợp cả hai phương pháp - Sử dụng webhook làm nguồn chính và polling làm phương án dự phòng

Kiến trúc đề xuất

Các bước triển khai

1. Lắng nghe checkout event - Khi người dùng nhấp pay, bắt đầu chuẩn bị xác minh trạng thái:
2. Polling server - Tạo một endpoint kiểm tra database để lấy trạng thái payment, được cập nhật bởi webhook:
3. Xử lý webhook phía server - Cập nhật database khi Dodo gửi webhook payment.succeeded hoặc payment.failed. Xem tài liệu Webhooks để biết thêm chi tiết.

Khắc phục sự cố

  • Xác minh elementId khớp với id của một div thực sự tồn tại trong DOM
  • Đảm bảo displayType: 'inline' đã được truyền vào Initialize
  • Kiểm tra checkoutUrl có hợp lệ hay không
  • Đảm bảo bạn đang lắng nghe event checkout.breakdown
  • Tax chỉ được tính sau khi người dùng nhập country và postal code hợp lệ trong checkout frame

Digital Wallet

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

Thiết lập nhanh Apple Pay

Chỉ inline checkout (embedded checkout) mới yêu cầu xác minh domain. Hosted checkout không yêu cầu bước này.
Apple Pay không khả dụng cho overlay checkout.
Apple Pay được xác minh theo từng domain từ dashboard.
1

Open Wallet domains

Đi đến Settings → Payment Methods và nhấp Manage domains trên dòng Apple Pay.
Nút Manage domains trên dòng Apple Pay trong cài đặt Payment Methods

Open Wallet domains from the Apple Pay row

2

Download the domain association file

Trong panel Wallet domains, hãy tải xuống association file.
Panel Wallet domains với nút Download file

Download the Apple Pay domain association file

3

Register your domain

Nhấp Register domain và nhập domain nơi bạn nhúng inline checkout, chẳng hạn shop.example.com, rồi nhấp Continue.
Biểu mẫu đăng ký domain với một domain đã được nhập

Register the domain where you embed inline checkout

4

Host the file on your domain

Host tại:
File phải được phân phối qua HTTPS, có thể truy cập mà không redirect và được phân phối với Content-Type: application/octet-stream hoặc text/plain.
5

Verify the domain

Nhấp Verify domain. Dodo Payments xác nhận file đang hoạt động và gửi domain của bạn đến Apple.
Màn hình Verify your domain với đường dẫn host association file và nút Verify domain

Verify the hosted association file

6

Confirm it's active

Khi trạng thái hiển thị Active, Apple Pay đã được bật cho domain đó. Sử dụng toggle Enabled để bật hoặc tắt theo từng domain.
Danh sách Wallet domains hiển thị các domain có trạng thái Apple Pay Active và toggle Enabled

Verified domains show an Active status

7

Test the integration

  1. Mở checkout trên thiết bị Apple
  2. Xác minh nút Apple Pay hiển thị
  3. Hoàn tất một giao dịch thử nghiệm

Hỗ trợ trình duyệt

Dodo Payments Checkout SDK hỗ trợ:
  • Chrome (mới nhất)
  • Firefox (mới nhất)
  • Safari (mới nhất)
  • Edge (mới nhất)
  • IE11+

Inline và Overlay Checkout

Chọn loại checkout phù hợp với trường hợp sử dụng của bạn:
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. Sử dụng overlay checkout để tích hợp nhanh hơn với ít thay đổi đối với các trang hiện có.

Tài nguyên liên quan

Overlay Checkout

Sử dụng overlay checkout để tích hợp nhanh dựa trên modal.

Checkout Sessions API

Tạo checkout session để cung cấp nền tảng cho trải nghiệm checkout.

Webhooks

Xử lý payment event phía server bằng webhook.

Integration Guide

Hướng dẫn hoàn chỉnh 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ệ đội ngũ hỗ trợ developer của chúng tôi.
Lần sửa đổi cuối 26 tháng 9, 2026