Skip to main content

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

  1. Navigate to the Dodo Payments Dashboard
  2. 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.
  3. Generate your API key:
    • Go to Developer > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  4. Configure webhooks:
    • Go to Developer > Webhooks
    • Create a webhook URL for payment notifications
    • Copy the webhook secret key in env

Integration

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_url to 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 returned checkout_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.
2

Redirect customer to checkout

After session creation, redirect to the checkout_url to start the hosted flow.
Prefer Checkout Sessions for the fastest, most reliable way to start taking payments. For advanced customization, see the full Checkout Sessions guide and the API Reference.

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. 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:
  • integer
    mặc định:"1"
    Number of items to purchase.
  • string
    bắt buộc
    URL to redirect after payment completion.
The redirect URL will include payment details as query parameters, for example:
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com

If 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.com
3

Pre-fill customer information (optional)

Add customer or billing fields as query parameters to streamline checkout.
  • string
    Customer’s full name (ignored if firstName or lastName is provided).
  • string
    Customer’s first name.
  • string
    Customer’s last name.
  • string
    Customer’s email address.
  • string
    Customer’s country.
  • string
    Street address.
  • string
    City.
  • string
    State or province.
  • string
    Postal/ZIP code.
  • boolean
    true 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).
To disable a field, provide its value and set the corresponding disable… flag to true:
Disabling fields helps prevent accidental changes and ensures data consistency.
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)

  • 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ệ.
  • number
    Cố định số tiền được tính, theo đơn vị tiền tệ chính (ví dụ: 12.5 tươ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.
  • string
    Các trường metadata tùy chỉnh (ví dụ: metadata_orderId=123).
paymentAmount trên payment link không sử dụng cùng đơn vị với trường amount trong Checkout Sessions API. Tham số của link sử dụng đơn vị tiền tệ chính (12.5 = 12.50),trongkhiproductcart[].amountcaAPIsdngmnhgiaˊnhnha^ˊt(1250=12.50), trong khi `product_cart[].amount` của API sử dụng mệnh giá nhỏ nhất (`1250` = 12.50). Xem Dynamic Pricing để biết trường API.
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.
Ưu tiên sử dụng Checkout Sessions cho hầu hết trường hợp sử dụng vì chúng cung cấp nhiều tính linh hoạt và khả năng kiểm soát hơn.
Đượ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:
Cả hai endpoint tạo link đều đã deprecated. POST /paymentsPOST /subscriptions vẫn tiếp tục hoạt động đối với các integration hiện có, nhưng integration mới nên sử dụng Checkout Sessions (POST /checkouts) thay thế.
Hướng dẫn dưới đây dành cho việc tạo one-time payment link. Để biết hướng dẫn chi tiết về việc tích hợp subscription, hãy tham khảo Subscription Integration Guide này.
Đảm bảo bạn truyền payment_link = true để nhận payment link
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:
Triển khai webhook của chúng tôi tuân theo đặc tả Standard Webhooks. Để biết các định nghĩa về loại webhook, hãy tham khảo Webhook Event Guide của chúng tôi.

Các Events cần lắng nghe

Bật payload.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:
Luôn fulfill trên payment.succeeded từ webhook, không phải trên browser redirect — redirect có thể bị bỏ lỡ nếu khách hàng đóng tab, trong khi webhook sẽ được retry cho đến khi được acknowledge.
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

Các amount động (Pay-What-You-Want) sử dụng base currency của product — không phải một local currency tùy ý — và base currency bị giới hạn ở USD, INR, GBP và EUR. Để thu một amount cố định bằng currency khác (ví dụ: PHP), bạn không thể truyền trực tiếp: hãy sử dụng Adaptive Pricing (chuyển đổi amount cơ sở theo FX trực tiếp) hoặc Localized Pricing (giá cố định theo từng currency, nhưng không tương thích với Pay-What-You-Want).
Cố định currency một cách rõ ràng. Truyền billing_currencybilling_address.country trên checkout session. Nếu bỏ qua, currency và country sẽ được phát hiện từ IP của khách hàng (Adaptive Currency) và có thể không khớp với thông tin bạn dự định tính phí.
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
Lần sửa đổi cuối 17 tháng 8, 2026