Prerequisites
To integrate the Dodo Payments API, you’ll need:- A Dodo Payments merchant account
- API Credentials (API key and webhook secret key) from dashboard
Dashboard Setup
- Navigate to the Dodo Payments Dashboard
- Create a product (one-time payment or subscription). Subscription products must be priced at least $1 (or the equivalent in your chosen currency); amounts below this minimum are not supported.
-
Generate your API key:
- Go to Developer > API
- Detailed Guide
- Copy the API key the in env named DODO_PAYMENTS_API_KEY
-
Configure webhooks:
- Go to Developer > Webhooks
- Create a webhook URL for payment notifications
- Copy the webhook secret key in env
Integration
Payment Links
Choose the integration path that fits your use case:- Checkout Sessions (recommended): Best for most integrations. Create a session on your server and redirect customers to a secure, hosted checkout.
- Overlay Checkout: Use when you need an in-page experience that opens checkout as a modal overlay on your site.
- Inline Checkout: Embed checkout directly into your page layout for fully integrated, branded checkout experiences.
- Static Payment Links: No-code, instantly shareable URLs for quick payment collection.
- Dynamic Payment Links: Programmatically created links. However, Checkout Sessions are recommended and provide more flexibility.
- Mobile Checkout SDKs: For native Android, iOS, React Native, and Flutter apps. Create the session on your server as above, then hand the
checkout_urlto the SDK.
Overlay and Inline Checkout are browser-only — they embed checkout into a web
page. If you’re building a native mobile app, create the checkout session on
your server and open it with the
Mobile Checkout SDKs instead.
1. Checkout Sessions
Use Checkout Sessions to create a secure, hosted checkout experience for one-time payments or subscriptions. You create a session on your server, then redirect the customer to the returnedcheckout_url.
Checkout sessions are valid for 24 hours by default. If you pass
confirm=true, sessions are valid for 15 minutes and all required fields must be provided.1
Create a checkout session
Choose your preferred SDK or call the REST API.
- Node.js SDK
- Python SDK
- REST API
2
Redirect customer to checkout
After session creation, redirect to the
checkout_url to start the hosted flow.2. Overlay Checkout
For a seamless in-page checkout experience, explore our Overlay Checkout integration that allows customers to complete payments without leaving your website.3. Inline Checkout
For fully integrated checkout experiences embedded directly in your page, use our Inline Checkout integration. This allows you to build custom order summaries and have complete control over the checkout layout while Dodo Payments securely handles payment collection.4. Static Payment Links
Static payment links let you quickly accept payments by sharing a simple URL. You can customize the checkout experience by passing query parameters to pre-fill customer details, control form fields, and add custom metadata.1
Construct your payment link
Start with the base URL and append your product ID:
2
Add core parameters
Include essential query parameters:
-
integermặc định:"1"Number of items to purchase.
-
stringbắt buộcURL to redirect after payment completion.
The redirect URL will include payment details as query parameters, for example:
If the product has license keys enabled, a
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.comIf the product has license keys enabled, a
license_key parameter is also appended (comma-separated for multiple keys):https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com3
Pre-fill customer information (optional)
Add customer or billing fields as query parameters to streamline checkout.
Supported Customer Fields
Supported Customer Fields
-
stringCustomer’s full name (ignored if firstName or lastName is provided).
-
stringCustomer’s first name.
-
stringCustomer’s last name.
-
stringCustomer’s email address.
-
stringCustomer’s country.
-
stringStreet address.
-
stringCity.
-
stringState or province.
-
stringPostal/ZIP code.
-
booleantrue or false
4
Control form fields (optional)
You can disable specific fields to make them read-only for the customer. This is useful when you already have the customer’s details (e.g., logged-in users).
disable… flag to true:- Disable Flags Table
Setting
showDiscounts=false will disable and hide the discounts section in the checkout form. Use this if you want to prevent customers from entering coupon or promo codes during checkout.5
Add advanced controls (optional)
-
stringChỉ đị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.
-
booleanmặc định:"true"Hiển thị hoặc ẩn bộ chọn đơn vị tiền tệ.
-
numberCố định số tiền được tính, theo đơn vị tiền tệ chính (ví dụ:
12.5tương ứng với $12.50). Chỉ áp dụng cho các sản phẩm Pay What You Want. Giá trị sẽ bị bỏ qua nếu thấp hơn giá tối thiểu của sản phẩm. -
stringCác trường metadata tùy chỉnh (ví dụ:
metadata_orderId=123).
6
Share the link
Gửi payment link đã hoàn tất cho khách hàng. Khi họ truy cập, tất cả query parameters sẽ được thu thập và lưu cùng với session ID. URL sau đó được đơn giản hóa, chỉ bao gồm tham số session (ví dụ:
?session=sess_1a2b3c4d). Thông tin đã lưu được duy trì qua các lần làm mới trang và có thể truy cập trong suốt quy trình checkout.Trải nghiệm checkout của khách hàng giờ đây được tinh gọn và cá nhân hóa dựa trên các tham số của bạn.
4. Dynamic Payment Links
Được tạo thông qua API call hoặc SDK của chúng tôi với thông tin chi tiết của khách hàng. Sau đây là một ví dụ: Có hai API để tạo dynamic payment links:- One-time Payment Link API Tài liệu tham khảo API
- Subscription Payment Link API Tài liệu tham khảo API
Đảm bảo bạn truyền
payment_link = true để nhận payment link - Node.js SDK
- Python SDK
- Go SDK
- Api Reference
Sau khi tạo payment link, chuyển hướng khách hàng đến để hoàn tất thanh toán.
Triển khai Webhooks
Thiết lập một API endpoint để nhận thông báo thanh toán. Sau đây là một ví dụ sử dụng Next.js:Các Events cần lắng nghe
Bậtpayload.type và xử lý các events liên quan đến quy trình one-time payment. Tối thiểu, hãy lắng nghe:
Nếu bạn bán các sản phẩm kỹ thuật số có license keys, hãy xử lý thêm
license_key.created. Để xem danh sách đầy đủ các events — bao gồm các events về subscription, entitlement, credit, recovery và dunning — hãy xem Webhook Event Guide.
Bạn có thể tham khảo project có triển khai demo trên GitHub sử dụng Next.js và TypeScript.
Bạn có thể xem triển khai trực tiếp tại đây.
Những điều quan trọng cần biết về Checkout & Currency
Checkout sessions hết hạn sau 24 giờ (15 phút khi
confirm: true), và mỗi checkout_url chỉ được sử dụng một lần — hãy tạo session mới cho từng khách hàng và từng lần thử payment thay vì sử dụng lại một link.Mua lại bằng một cú nhấp. Đối với khách hàng quay lại đã lưu payment method, truyền
payment_method_id cùng với confirm: true để tính phí ngay lập tức, hoàn toàn bỏ qua bước chọn method.Tài liệu tham khảo API liên quan
Create Checkout Session
Tài liệu tham khảo API để tạo checkout sessions được lưu trữ an toàn cho one-time payments và subscriptions
Create Payment Link
Tài liệu tham khảo API để tạo dynamic payment links theo cách lập trình