Skip to main content

Checkout Sessions

Tạo checkout bảo mật, được lưu trữ để xử lý các khoản thanh toán một lần và gói đăng ký.

Payment Links

Chia sẻ URL để thu tiền mà không cần viết code.

Webhooks

Lắng nghe các sự kiện thanh toán và hoàn tất đơn hàng.

API Reference

Tài liệu endpoint đầy đủ và kiểm thử trực tiếp.

Điều kiện tiên quyết

Trước khi bắt đầu, bạn cần:
  • Một tài khoản Dodo Payments.
  • Ít nhất một sản phẩm. Tạo sản phẩm trong Products trên dashboard. Sản phẩm đăng ký có mức giá khác 0 phải có giá từ $1 trở lên hoặc mức tương đương theo đơn vị tiền tệ của sản phẩm. Sản phẩm đăng ký $0 cũng được hỗ trợ.
  • Một API key. Tạo key trong Developer → API Keys và lưu key vào biến môi trường DODO_PAYMENTS_API_KEY. Hãy tạo key ở test mode trong quá trình xây dựng: các ví dụ trên trang này sử dụng test mode và key ở test mode chỉ hoạt động với test mode. Xem Authentication.

Chọn đường dẫn tích hợp

Overlay và inline checkout chỉ chạy trên trang web. Trong ứng dụng di động native, hãy tạo phiên checkout trên server rồi mở checkout_url bằng mobile checkout SDK. Để một coding agent xây dựng tích hợp này cho bạn, hãy cài đặt Agent Plugin.

Checkout Sessions

Tạo trải nghiệm checkout bảo mật, được lưu trữ. Bạn tạo một phiên trên server, sau đó chuyển hướng khách hàng đến checkout_url được trả về.
Mỗi checkout_url chỉ hoạt động một lần và hết hạn sau 24 giờ hoặc sau 15 phút khi bạn truyền confirm: true. Với confirm: true, bạn cũng phải cung cấp mọi trường bắt buộc. Tạo một phiên mới cho mỗi khách hàng và mỗi lần thử thanh toán.

Tạo Checkout Session

Chuyển hướng đến Checkout

Sau khi tạo phiên, hãy chuyển hướng khách hàng đến checkout_url:
Để tùy chỉnh nâng cao, hãy xem hướng dẫn đầy đủ về Checkout Sessions và API Reference.
Payment link là URL mở checkout cho một sản phẩm, giúp bạn thu tiền mà không cần viết code. Các tham số truy vấn điền sẵn thông tin khách hàng và kiểm soát biểu mẫu checkout. Khi khách hàng mở liên kết, checkout lưu các tham số vào một phiên và rút ngắn URL thành tham số session, nhờ đó các tham số vẫn được giữ lại khi tải lại trang. Static payment link là URL bạn tạo một lần và chia sẻ nhiều lần. URL cơ sở là:
Thêm các tham số truy vấn để tùy chỉnh checkout:
integer
mặc định:"1"
Số lượng sản phẩm muốn mua.
string
bắt buộc
Payment links sử dụng redirect_url. API Checkout Sessions sử dụng return_url cho cùng mục đích.URL để chuyển hướng sau khi thanh toán. Dodo Payments thêm thông tin thanh toán dưới dạng tham số truy vấn, ví dụ https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Nếu sản phẩm cấp license key, tham số license_key cũng được thêm vào, với nhiều key được phân tách bằng dấu phẩy.
string
Chỉ định đơn vị tiền tệ thanh toán. Mặc định là đơn vị tiền tệ của quốc gia thanh toán.
boolean
mặc định:"true"
Hiển thị hoặc ẩn bộ chọn đơn vị tiền tệ.
boolean
mặc định:"true"
Hiển thị hoặc ẩn phần giảm giá. Đặt thành false để ngăn khách hàng nhập mã coupon.
number
Cố định số tiền được tính, theo đơn vị tiền tệ chính; ví dụ 12.5 cho $12.50. Chỉ hoạt động với sản phẩm Pay What You Want và bị bỏ qua nếu thấp hơn giá tối thiểu của sản phẩm.
paymentAmount sử dụng đơn vị tiền tệ chính (12.5 là $12.50). Trường product_cart[].amount của API Checkout Sessions sử dụng đơn vị nhỏ nhất của tiền tệ (1250 là $12.50). Xem Dynamic Pricing.
string
Các trường metadata tùy chỉnh, ví dụ metadata_orderId=123.

Điền sẵn thông tin khách hàng

Thêm các trường khách hàng dưới dạng tham số truy vấn để đơn giản hóa checkout:
string
Họ tên đầy đủ của khách hàng (bị bỏ qua nếu cung cấp firstName hoặc lastName).
string
Tên của khách hàng.
string
Họ của khách hàng.
string
Địa chỉ email của khách hàng.
string
Quốc gia của khách hàng (mã ISO 3166-1 alpha-2).
string
Địa chỉ đường phố.
string
Thành phố.
string
Bang hoặc tỉnh.
string
Mã bưu chính hoặc ZIP.

Vô hiệu hóa các trường biểu mẫu

Để ngăn khách hàng thay đổi thông tin đã điền sẵn, hãy vô hiệu hóa một trường bằng cách cung cấp giá trị của trường đó và đặt cờ disable... tương ứng thành true:
Việc vô hiệu hóa các trường ngăn thay đổi ngoài ý muốn và đảm bảo tính nhất quán của dữ liệu.
Các endpoint POST /payments và POST /subscriptions đã không còn được hỗ trợ. Thay vào đó, hãy sử dụng Checkout Sessions cho các tích hợp mới.
Đối với các tích hợp hiện có sử dụng dynamic payment links, hãy truyền payment_link: true vào Create One-Time Payment hoặc Create Subscription để tạo liên kết. Các ví dụ dưới đây tạo một liên kết thanh toán một lần. Đối với gói đăng ký, hãy xem Subscription Integration Guide.

Webhooks

Webhooks thông báo cho server của bạn khi một khoản thanh toán thành công hoặc thất bại, để bạn có thể hoàn tất đơn hàng.

Tạo Webhook Endpoint

Truy cập Developer → Webhooks trong dashboard và thêm URL endpoint của bạn. Sao chép signing secret của endpoint vào biến môi trường DODO_PAYMENTS_WEBHOOK_KEY. Đây là ví dụ sử dụng Next.js:
app/api/webhooks/dodo/route.ts
Triển khai webhook của chúng tôi tuân theo đặc tả Standard Webhooks.

Các sự kiện cần lắng nghe

Tối thiểu, hãy lắng nghe các sự kiện sau trong quy trình thanh toán một lần:
Luôn hoàn tất đơn hàng khi nhận payment.succeeded từ webhook, không phải từ chuyển hướng trình duyệt. Chuyển hướng có thể bị bỏ qua nếu khách hàng đóng tab, trong khi webhook sẽ được thử lại cho đến khi nhận xác nhận.
Nếu bán sản phẩm có license key, hãy xử lý thêm license_key.created. Để xem danh sách đầy đủ các sự kiện, bao gồm sự kiện đăng ký, entitlement, credit, recovery và dunning, hãy xem Webhook Event Guide. Để xem ví dụ đầy đủ sử dụng Next.js và TypeScript, hãy xem demo repository và live deployment của repository này.

Đơn vị tiền tệ và địa chỉ thanh toán

Để tính phí bằng một đơn vị tiền tệ cụ thể, hãy truyền billing_currency và billing_address.country khi tạo phiên checkout. Nếu bỏ qua các tham số này, Adaptive Currency sẽ chọn đơn vị tiền tệ và quốc gia dựa trên địa chỉ IP của khách hàng, nên có thể không phải đơn vị tiền tệ bạn dự định sử dụng để tính phí. Số tiền Pay What You Want được tính theo đơn vị tiền tệ cơ sở của sản phẩm, phải là USD, GBP hoặc EUR. Để thu một số tiền cố định bằng đơn vị tiền tệ khác, hãy sử dụng Adaptive Currency, tính giá cơ sở theo tỷ giá trực tiếp, hoặc Localized Pricing, thiết lập giá cố định cho từng đơn vị tiền tệ. Localized Pricing không hoạt động với Pay What You Want.

Mua lại bằng một cú nhấp

Để tính phí khách hàng quay lại bằng phương thức thanh toán đã lưu, hãy truyền payment_method_id cùng với confirm: true. payment_method_id chỉ được chấp nhận khi confirm là true, và bạn cũng phải truyền customer_id của khách hàng hiện tại. Vì confirm là true, bạn cũng phải truyền billing_address đầy đủ. Phiên sẽ tính phí trực tiếp vào phương thức thanh toán đã lưu nên không trả về checkout_url. Sử dụng webhooks để biết thanh toán có thành công hay không.

Các trang liên quan

Checkout Sessions

Hướng dẫn đầy đủ với các tùy chọn tùy chỉnh nâng cao.

Overlay Checkout

Nhúng checkout dưới dạng overlay modal trên trang của bạn.

Inline Checkout

Nhúng checkout trực tiếp vào bố cục trang của bạn.

Subscription Integration

Thiết lập thanh toán định kỳ.

Webhook Event Guide

Danh sách đầy đủ tất cả sự kiện webhook.

API Reference

Tài liệu API Checkout Sessions.
Lần sửa đổi cuối 26 tháng 9, 2026