
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.Đặ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:
Example inline checkout layout showing required elements
- 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ử.
- Mô tả mặt hàng: Mô tả nội dung khách hàng đang mua.
- Tổng giao dịch: Subtotal, tổng tax và grand total, bao gồm currency.
- 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.
- 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.
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.Customer opens checkout
checkout.breakdown, để hiển thị và cập nhật thông tin trên trang.
Customer enters their details
Customer selects payment method

Checkout completed

Dodo Payments creates the payment or subscription

Bắt đầu nhanh
Cài đặt SDK, khởi tạo SDK ở inline mode và mở checkout trong một container element:Tích hợp từng bước
Install the SDK
Initialize the SDK for Inline Display
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:Create a Container Element
Open the Checkout
DodoPayments.Checkout.open() với checkoutUrl và elementId của container:Test Your Integration
- Khởi động development server:
- 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
checkout.breakdown được ghi trong browser console nếu đã thêm console log vào callback onEvent.Go Live
- Chuyển mode thành
'live':
- Cập nhật checkout URL để sử dụng live checkout session từ backend
- 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 eventcheckout.breakdown:
Tham chiếu API
Khởi tạo
GọiInitialize 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 callbackonEvent. Đối với inline checkout, checkout.breakdown đặc biệt hữu ích để đồng bộ UI:
Dữ liệu phân tích Checkout
Eventcheckout.breakdown cung cấp thông tin về price và tax:
- Đị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. - Xử lý trạng thái ban đầu: Khi checkout vừa tải,
taxvàdiscountcó thể là0hoặcnullcho đế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. - “Final Total” và “Total”: Mặc dù
totalcung cấp phép tính price tiêu chuẩn,finalTotalmới là nguồn dữ liệu chính xác cho giao dịch. NếufinalTotaltồ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. - 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
- Gọi Update Payment Method API để lấy một
payment_link:
- Truyền
payment_linknhận được làmcheckoutUrlđể mở inline checkout:
Đối với Subscription đang On-Hold
Khi cập nhật payment method cho subscription ở trạng tháion_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.
Xử lý lỗi
Luôn triển khai xử lý lỗi trong callbackonEvent:
Best Practices
- 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.
- Đồ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. - Skeleton State: Hiển thị loading indicator trong container cho đến khi event
checkout.openedđược phát. - Dọn dẹp: Gọi
DodoPayments.Checkout.close()khi component unmount để dọn dẹp iframe và event listener.
#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
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:- Lắng nghe webhook event - Dodo Payments gửi webhook khi trạng thái payment thay đổi
- Triển khai cơ chế polling - Frontend nên polling server để lấy thông tin cập nhật trạng thái
- 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: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ố
Checkout frame is not appearing
Checkout frame is not appearing
- Xác minh
elementIdkhớp vớiidcủa mộtdivthực sự tồn tại trong DOM - Đảm bảo
displayType: 'inline'đã được truyền vàoInitialize - Kiểm tra
checkoutUrlcó hợp lệ hay không
Taxes are not updating in my UI
Taxes are not updating in my UI
- Đả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
Open Wallet domains

Open Wallet domains from the Apple Pay row
Download the domain association file

Download the Apple Pay domain association file
Register your domain
shop.example.com, rồi nhấp Continue.
Register the domain where you embed inline checkout
Host the file on your domain
Content-Type: application/octet-stream hoặc text/plain.Verify the domain

Verify the hosted association file
Confirm it's active

Verified domains show an Active status
Test the integration
- Mở checkout trên thiết bị Apple
- Xác minh nút Apple Pay hiển thị
- 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+