Tổng Quan
Thanh toán inline cho phép bạn tạo ra những trải nghiệm thanh toán hoàn toàn tích hợp, hòa quyện một cách liền mạch với trang web hoặc ứng dụng của bạn. Khác với thanh toán overlay, mở dưới dạng modal trên trang của bạn, thanh toán inline nhúng biểu mẫu thanh toán trực tiếp vào bố cục trang của bạn. Sử dụng thanh toán inline, bạn có thể:- Tạo ra những trải nghiệm thanh toán hoàn toàn tích hợp với ứng dụng hoặc trang web của bạn
- Để Dodo Payments an toàn thu thập thông tin khách hàng và thông tin thanh toán trong một khung thanh toán tối ưu
- Hiển thị các mặt hàng, tổng số và thông tin khác từ Dodo Payments trên trang của bạn
- Sử dụng các phương thức và sự kiện SDK để xây dựng những trải nghiệm thanh toán nâng cao

Cách Hoạt Động
Thanh toán inline hoạt động bằng cách nhúng một khung Dodo Payments an toàn vào trang web hoặc ứng dụng của bạn. Khung thanh toán xử lý việc thu thập thông tin khách hàng và ghi lại chi tiết thanh toán. Trang của bạn hiển thị danh sách mặt hàng, tổng số và tùy chọn để thay đổi những gì có trên thanh toán. SDK cho phép trang của bạn và khung thanh toán tương tác với nhau. Dodo Payments tự động tạo một đăng ký khi một thanh toán hoàn tất, sẵn sàng để bạn cung cấp.Khung thanh toán inline xử lý an toàn tất cả thông tin thanh toán nhạy cảm, đảm bảo tuân thủ PCI mà không cần chứng nhận bổ sung từ phía bạn.
Điều Gì Tạo Nên Một Thanh Toán Inline Tốt?
Điều quan trọng là khách hàng biết họ đang mua từ ai, họ đang mua gì và họ phải trả bao nhiêu. Để xây dựng một thanh toán inline tuân thủ và tối ưu hóa cho chuyển đổi, việc triển khai của bạn phải bao gồm:
- Thông tin định kỳ: Nếu là định kỳ, tần suất và tổng số phải trả khi gia hạn. Nếu là dùng thử, thời gian dùng thử kéo dài bao lâu.
- Mô tả mặt hàng: Một mô tả về những gì đang được mua.
- Tổng giao dịch: Tổng giao dịch, bao gồm tổng phụ, thuế tổng và tổng cộng. Đảm bảo bao gồm cả loại tiền tệ.
- Chân trang Dodo Payments: Toàn bộ khung thanh toán inline, bao gồm chân trang thanh toán có thông tin về Dodo Payments, điều khoản bán hàng của chúng tôi và chính sách bảo mật của chúng tôi.
- Chính sách hoàn tiền: Một liên kết đến chính sách hoàn tiền của bạn, nếu nó khác với chính sách hoàn tiền tiêu chuẩn của Dodo Payments.
Hành Trình Khách Hàng
Luồng thanh toán được xác định bởi cấu hình phiên thanh toán của bạn. Tùy thuộc vào cách bạn cấu hình phiên thanh toán, khách hàng sẽ trải nghiệm một thanh toán có thể trình bày tất cả thông tin trên một trang duy nhất hoặc qua nhiều bước.Khách hàng mở thanh toán
Bạn có thể mở thanh toán inline bằng cách truyền các mặt hàng hoặc một giao dịch hiện có. Sử dụng SDK để hiển thị và cập nhật thông tin trên trang, và các phương thức SDK để cập nhật các mặt hàng dựa trên tương tác của khách hàng.

Khách hàng nhập thông tin của họ
Thanh toán inline trước tiên yêu cầu khách hàng nhập địa chỉ email của họ, chọn quốc gia của họ và (nếu cần) nhập mã ZIP hoặc mã bưu chính của họ. Bước này thu thập tất cả thông tin cần thiết để xác định thuế và các tùy chọn thanh toán có sẵn.Bạn có thể tự động điền thông tin khách hàng và trình bày các địa chỉ đã lưu để đơn giản hóa trải nghiệm.
Khách hàng chọn phương thức thanh toán
Sau khi nhập thông tin của họ, khách hàng sẽ được trình bày các phương thức thanh toán có sẵn và biểu mẫu thanh toán. Các tùy chọn có thể bao gồm thẻ tín dụng hoặc thẻ ghi nợ, PayPal, Apple Pay, Google Pay và các phương thức thanh toán địa phương khác dựa trên vị trí của họ.Hiển thị các phương thức thanh toán đã lưu nếu có để tăng tốc độ thanh toán.

Thanh toán hoàn tất
Dodo Payments định tuyến mọi thanh toán đến nhà cung cấp tốt nhất cho giao dịch đó để có cơ hội thành công tốt nhất. Khách hàng sẽ vào một quy trình thành công mà bạn có thể xây dựng.

Bắt đầu nhanh
Bắt đầu với Dodo Payments Inline Checkout chỉ với vài dòng mã:Hướng dẫn tích hợp từng bước
Khởi tạo SDK cho Hiển thị Inline
Khởi tạo SDK và chỉ định
displayType: 'inline'. Bạn cũng nên lắng nghe sự kiện checkout.breakdown để cập nhật UI của bạn với các tính toán thuế và tổng thời gian thực.Kiểm tra tích hợp của bạn
- Khởi động máy chủ phát triển của bạn:
- Kiểm tra quy trình thanh toán:
- Nhập email và địa chỉ của bạn trong khung inline.
- Xác minh rằng tóm tắt đơn hàng tùy chỉnh của bạn cập nhật theo thời gian thực.
- 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 rằng các chuyển hướng hoạt động chính xác.
Bạn nên thấy các sự kiện
checkout.breakdown được ghi lại trong bảng điều khiển trình duyệt của bạn nếu bạn đã thêm một bản ghi console trong callback onEvent.Ví dụ hoàn chỉnh về React
Ví dụ này minh họa cách thực hiện một tóm tắt đơn hàng tùy chỉnh bên cạnh thanh toán inline, giữ cho chúng đồng bộ bằng cách sử dụng sự kiệncheckout.breakdown.
Tài liệu API
Cấu hình
Tùy chọn khởi tạo
| Tùy chọn | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
mode | "test" | "live" | Có | Chế độ môi trường. |
displayType | "inline" | "overlay" | Có | Phải được đặt thành "inline" để nhúng thanh toán. |
onEvent | function | Có | Hàm callback để xử lý các sự kiện thanh toán. |
Tùy chọn thanh toán
| Tùy chọn | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
checkoutUrl | string | Có | URL phiên thanh toán. |
elementId | string | Có | id của phần tử DOM nơi thanh toán nên được hiển thị. |
options.showTimer | boolean | Không | Hiện 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 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. |
options.themeConfig | ThemeConfig | Không | Cấu hình chủ đề tùy chỉnh. |
options.payButtonText | string | Không | Văn bản tùy chỉnh để hiển thị trên nút thanh toán. |
options.fontSize | FontSize | Không | Kích thước phông chữ toàn cầu cho thanh toán. |
options.fontWeight | FontWeight | Không | Độ dày phông chữ toàn cầu cho thanh toán. |
Phương thức
Mở thanh toán
Mở khung thanh toán trong phần tử được chỉ định.manualRedirect, xử lý việc hoàn tất thanh toán trong callback onEvent:
Đóng Thanh Toán
Loại bỏ khung thanh toán theo cách lập trình và dọn dẹp các trình lắng nghe sự kiện.Kiểm Tra Trạng Thái
Trả về liệu khung thanh toán hiện đang được chèn hay không.Sự Kiện
SDK cung cấp các sự kiện thời gian thực thông qua callbackonEvent. Đối với thanh toán inline, checkout.breakdown đặc biệt hữu ích để đồng bộ hóa UI của bạn.
| Loại sự kiện | Mô tả |
|---|---|
checkout.opened | Khung thanh toán đã được tải. |
checkout.breakdown | Bị kích hoạt khi giá, thuế hoặc giảm giá được cập nhật. |
checkout.customer_details_submitted | Chi tiết khách hàng đã được gửi. |
checkout.pay_button_clicked | Bị kích hoạt khi khách hàng nhấp vào nút thanh toán. Hữu ích cho phân tích và theo dõi các kênh chuyển đổi. |
checkout.redirect | Thanh toán sẽ thực hiện một chuyển hướng (ví dụ: đến trang ngân hàng). |
checkout.error | Đã xảy ra lỗi trong quá trình thanh toán. |
checkout.link_expired | Bị 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 | Bị 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 | Bị kích hoạt khi manualRedirect được kích hoạt. Chứa URL để chuyển hướng khách hàng đến. |
Dữ Liệu Phân Tích Thanh Toán
Sự kiệncheckout.breakdown cung cấp các dữ liệu sau:
Dữ Liệu Sự Kiện Trạng Thái Thanh Toán
KhimanualRedirect được kích hoạt, bạn nhận được sự kiện checkout.status với các dữ liệu sau:
Dữ Liệu Sự Kiện Yêu Cầu Chuyển Hướng Thanh Toán
KhimanualRedirect được kích hoạt, bạn nhận được sự kiện checkout.redirect_requested với các dữ liệu sau:
Hiểu Sự Kiện Phân Tích
Sự kiệncheckout.breakdown là cách chính để giữ cho UI của ứng dụng của bạn đồng bộ với trạng thái thanh toán của Dodo Payments.
Khi nó xảy ra:
- Khi khởi tạo: Ngay sau khi khung thanh toán được tải và sẵn sàng.
- Khi thay đổi địa chỉ: Bất cứ khi nào khách hàng chọn một quốc gia hoặc nhập mã bưu chính dẫn đến việc tính toán thuế lại.
| Trường | Mô tả |
|---|---|
subTotal | Tổng số tất cả các mục trong phiên trước khi bất kỳ giảm giá hoặc thuế nào được áp dụng. |
discount | Tổng giá trị của tất cả các giảm giá đã áp dụng. |
tax | Số tiền thuế đã được tính toán. Trong chế độ inline, điều này được cập nhật động khi người dùng tương tác với các trường địa chỉ. |
total | Kết quả toán học của subTotal - discount + tax trong đơn vị tiền tệ cơ bản của phiên. |
currency | Mã tiền tệ ISO (ví dụ: "USD") cho các giá trị tổng phụ, giảm giá và thuế tiêu chuẩn. |
finalTotal | Số tiền thực tế mà khách hàng bị tính phí. Điều này có thể bao gồm các điều chỉnh ngoại hối bổ sung hoặc phí phương thức thanh toán địa phương không nằm trong bảng giá cơ bản. |
finalTotalCurrency | Tiền tệ mà khách hàng thực sự thanh toán. Điều này có thể khác với currency nếu sức mua tương đương hoặc chuyển đổi tiền tệ địa phương đang hoạt động. |
- Định dạng tiền tệ: Giá luôn được trả về dưới dạng số nguyên trong đơn vị tiền tệ nhỏ nhất (ví dụ: xu cho USD, yên cho JPY). Để hiển thị chúng, chia cho 100 (hoặc lũy thừa thích hợp của 10) hoặc sử dụng thư viện định dạng như
Intl.NumberFormat. - Xử lý trạng thái ban đầu: Khi thanh toán lần đầu được tải,
taxvàdiscountcó thể là0hoặcnullcho đến khi người dùng cung cấp thông tin thanh toán hoặc áp dụng mã. UI của bạn nên xử lý các trạng thái này một cách duyên dáng (ví dụ: hiển thị một dấu gạch ngang—hoặc ẩn hàng). - “Tổng cuối cùng” so với “Tổng”: Trong khi
totalcung cấp cho bạn phép tính giá tiêu chuẩn,finalTotallà nguồn sự thật cho giao dịch. NếufinalTotalcó mặt, nó phản ánh chính xác những gì sẽ được tính phí vào thẻ của khách hàng, bao gồm bất kỳ điều chỉnh động nào. - Phản hồi thời gian thực: Sử dụng trường
taxđể cho người dùng thấy rằng thuế đang được tính toán trong thời gian thực. Điều này cung cấp cảm giác “trực tiếp” cho trang thanh toán của bạn và giảm ma sát trong bước nhập địa chỉ.
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: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 một đối tượngthemeConfig trong tham số options khi mở thanh toán. Cấu hình chủ đề 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.
Cấu hình Giao diện Cơ bản
Cấu hình Giao diện Hoàn chỉnh
Tất cả các thuộc tính giao diện có sẵn:Chỉ Chế độ Sáng
Nếu bạn chỉ muốn tùy chỉnh giao diện sáng:Chỉ Chế độ Tối
Nếu bạn chỉ muốn tùy chỉnh giao diện tối:Ghi đè một phần Giao diện
Bạn có thể ghi đè chỉ các thuộc tính cụ thể. Thanh toán sẽ sử dụng các giá trị mặc định cho các thuộc tính bạn không chỉ định:Cấu hình Giao diện với Các Tùy chọn Khác
Bạn có thể kết hợp cấu hình giao diện với các tùy chọn thanh toán khác:Các Kiểu TypeScript
Đối với người dùng TypeScript, tất cả các kiểu cấu hình giao diện đều được xuất khẩu: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 callbackonEvent:
Thực hành Tốt Nhất
- Thiết kế đáp ứng: Đảm bảo phần tử container của bạn có đủ chiều rộng và chiều cao. iframe sẽ thường mở rộng để lấp đầy container của nó.
- Đồng bộ hóa: Sử dụng sự kiện
checkout.breakdownđể giữ cho tóm tắt đơn hàng tùy chỉnh hoặc bảng giá của bạn đồng bộ với những gì người dùng thấy trong khung thanh toán. - Trạng thái khung: Hiển thị một chỉ báo tải trong container của bạn cho đến khi sự kiện
checkout.openedđược kích hoạt. - Dọn dẹp: Gọi
DodoPayments.Checkout.close()khi thành phần của bạn bị gỡ bỏ để dọn dẹp iframe và các trình lắng nghe sự kiện.
Đối với các triển khai chế độ tối, nên sử dụng
#0d0d0d làm màu nền để tích hợp hình ảnh tốt nhất với khung thanh toán inline.Xác thực trạng thái thanh toán
Tại sao xác thực phía máy chủ là cần thiết
Trong khi các sự kiện thanh toán inline nhưcheckout.status cung cấp phản hồi thời gian thực, chúng không nên là nguồn sự thật duy nhất của bạn cho trạng thái thanh toán. Các vấn đề mạng, sự cố trình duyệt hoặc người dùng đóng trang có thể khiến các sự kiện bị bỏ lỡ. Để đảm bảo xác thực thanh toán đáng tin cậy:
- Máy chủ của bạn nên lắng nghe các sự kiện webhook - Dodo Payments gửi webhooks cho các thay đổi trạng thái thanh toán
- Triển khai cơ chế polling - Giao diện của bạn nên polling máy chủ của bạn để cập nhật trạng thái
- Kết hợp cả hai phương pháp - Sử dụng webhooks làm nguồn chính và polling làm phương pháp dự phòng
Kiến trúc được khuyến nghị
Các bước triển khai
1. Lắng nghe các sự kiện thanh toán - Khi người dùng nhấp vào thanh toán, 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 của chúng tôi để biết chi tiết.
Xử lý chuyển hướng (3DS, Google Pay, UPI)
Khi sử dụngmanualRedirect: true, một số phương thức thanh toán yêu cầu chuyển hướng người dùng ra khỏi trang của bạn để xác thực:
- 3D Secure (3DS) - Xác thực thẻ
- Google Pay - Xác thực ví trong một số quy trình
- UPI - Chuyển hướng phương thức thanh toán Ấn Độ
checkout.redirect_requested. Chuyển hướng người dùng đến URL được cung cấp:
- Kiểm tra xem người dùng có đang trở lại từ một chuyển hướng hay không (ví dụ: thông qua
sessionStorage) - Bắt đầu polling máy chủ của bạn để xác nhận trạng thái thanh toán
- Hiển thị trạng thái “Đang xác minh thanh toán…” trong khi polling
- Hiển thị UI thành công/thất bại dựa trên trạng thái đã xác nhận từ máy chủ
Khắc phục sự cố
Khung thanh toán không xuất hiện
Khung thanh toán không xuất hiện
- Xác minh rằng
elementIdkhớp vớiidcủa mộtdivthực sự tồn tại trong DOM. - Đảm bảo
displayType: 'inline'đã được truyền choInitialize. - Kiểm tra rằng
checkoutUrllà hợp lệ.
Thuế không được cập nhật trong UI của tôi
Thuế không được cập nhật trong UI của tôi
- Đảm bảo bạn đang lắng nghe sự kiện
checkout.breakdown. - Thuế chỉ được tính toán sau khi người dùng nhập một quốc gia và mã bưu chính hợp lệ trong khung thanh toán.
Bật Ví Điện Tử
Để biết thêm thông tin chi tiết về cách thiết lập Apple Pay, Google Pay và các ví điện tử khác, hãy xem trang Ví Điện Tử.Thiết lập nhanh cho Apple Pay
Tải xuống tệp liên kết miền
Tải xuống tệp liên kết miền Apple Pay.
Yêu cầu kích hoạt
Gửi email tới support@dodopayments.com với URL miền sản xuất của bạn và yêu cầu kích hoạt Apple Pay.
Hỗ Trợ Trình Duyệt
SDK Thanh Toán Dodo hỗ trợ các trình duyệt sau:- Chrome (phiên bản mới nhất)
- Firefox (phiên bản mới nhất)
- Safari (phiên bản mới nhất)
- Edge (phiên bản mới nhất)
- IE11+
Thanh Toán Inline so với Overlay
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 Inline | Thanh toán Overlay |
|---|---|---|
| Độ sâu tích hợp | Hoàn toàn nhúng trong trang | Modal trên cùng trang |
| Kiểm soát bố cục | Toàn quyền kiểm soát | Hạn chế |
| Thương hiệu | Liền mạch | Tách biệt với trang |
| Nỗ lực triển khai | Cao hơn | Thấp hơn |
| Tốt nhất cho | Trang thanh toán tùy chỉnh, quy trình chuyển đổi cao | Tích hợp nhanh, trang hiện có |
Tài Nguyên Liên Quan
Thanh Toán Overlay
Sử dụng thanh toán overlay cho tích hợp modal nhanh chóng.
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.
Webhook
Xử lý sự kiện thanh toán ở phía máy chủ với webhook.
Hướng Dẫn Tích Hợp
Hướng dẫn đầy đủ về việc tích hợp Dodo Payments.
