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 đếncheckout_url được trả về.
Tạo Checkout Session
- Node.js SDK
- Python SDK
- cURL
Chuyển hướng đến Checkout
Sau khi tạo phiên, hãy chuyển hướng khách hàng đếncheckout_url:
Payment Links
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 Links
Static payment link là URL bạn tạo một lần và chia sẻ nhiều lần. URL cơ sở là: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.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:
Ví dụ về Static Payment Link
Dynamic Payment Links (Đã ngừng hỗ trợ)
Đối với các tích hợp hiện có sử dụng dynamic payment links, hãy truyềnpayment_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.
- Node.js SDK
- Python SDK
- Go SDK
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ườngDODO_PAYMENTS_WEBHOOK_KEY.
Đây là ví dụ sử dụng Next.js:
app/api/webhooks/dodo/route.ts
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:
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ềnbilling_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ềnpayment_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.