Tài liệu tham khảo API - Dodo Payments Documentation

SDKs & Libraries

SDK backend chính thức cho TypeScript, Python, Go, PHP, Java, Kotlin, C#, Ruby và Rust. Các thư viện này xử lý việc xác thực, tuần tự hóa và xử lý lỗi để bạn có thể tập trung vào việc tích hợp.

Mobile Checkout SDKs

Mở trang thanh toán được lưu trữ của Dodo từ các ứng dụng Android, iOS, React Native và Flutter, đồng thời nhận kết quả có kiểu trong một lần gọi. Các SDK này không lưu API key.

URL môi trường

Chế độ kiểm thử: https://test.dodopayments.com
Chế độ trực tiếp: https://live.dodopayments.com

Tìm hiểu thêm về Test Mode vs Live Mode.

Xác thực

Các request API yêu cầu API key, ngoại trừ một số endpoint công khai như Activate License, Validate License và Deactivate License. Hãy tạo một API key trong dashboard của bạn và đưa key đó vào header Authorization của mọi request.

Generate an API Key

Đi đến Developer → API Keys trong dashboard và chọn Add API Key. Tạo key ở chế độ bạn muốn gọi: test mode key chỉ hoạt động với https://test.dodopayments.com, còn live mode key chỉ hoạt động với https://live.dodopayments.com. Đặt tên mô tả cho key và chọn cấp quyền truy cập:

Enable write access được chọn (mặc định): Toàn quyền đọc và ghi cho mọi thao tác API.
Enable write access không được chọn: Quyền chỉ đọc. Bạn có thể truy xuất dữ liệu (thanh toán, gói đăng ký, khách hàng, sản phẩm) nhưng không thể tạo hoặc chỉnh sửa tài nguyên.

Bỏ chọn Enable write access cho các tích hợp chỉ cần xem dữ liệu, chẳng hạn như công cụ phân tích hoặc tích hợp dashboard.

Store Your Key Securely

Sao chép key ngay lập tức. Bạn sẽ không thể xem lại key này. Lưu key trong một environment variable chẳng hạn như DODO_PAYMENTS_API_KEY.

Authenticate Requests

Đưa API key vào header Authorization của mọi yêu cầu:

Authorization: Bearer YOUR_API_KEY

Không bao giờ để lộ API key trong mã phía client, kho lưu trữ công khai hoặc hệ thống quản lý phiên bản.

Định dạng response

Các yêu cầu thành công trả về 200 hoặc 201 cùng với phần thân JSON, hoặc 204 không có phần thân. Lỗi trả về trạng thái 4xx hoặc 5xx cùng với phần thân JSON chứa code và message.

{
  "payment_id": "pay_gr4RizvMOXFJ6xca3y2tU",
  "status": "succeeded",
  "total_amount": 2999,
  "currency": "USD",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "code": "INVALID_REQUEST_BODY",
  "message": "Your request body is invalid. Please check your request headers and object."
}

Giới hạn tốc độ

API áp dụng đồng thời hai giới hạn: giới hạn burst mỗi giây và giới hạn duy trì mỗi phút. Các giới hạn áp dụng cho toàn bộ business của bạn, trên tất cả API key của business đó, và phụ thuộc vào tier giới hạn tốc độ của business.

Tier mặc định

Cửa sổ	Giới hạn
Mỗi giây (Burst)	40 yêu cầu
Mỗi phút (Duy trì)	240 yêu cầu

Các tier cao hơn

Các business có nhu cầu API cao hơn có thể nâng cấp lên giới hạn tốc độ cao hơn:

Tier	Burst (mỗi giây)	Duy trì (mỗi phút)
Mặc định	40	240
Tier 1	100	1.000
Tier 2	500	5.000

Để nâng cấp tier giới hạn tốc độ, hãy gửi email đến support@dodopayments.com.

Yêu cầu không xác thực

Các yêu cầu không có API key hợp lệ sẽ bị giới hạn tốc độ theo địa chỉ IP:

Cửa sổ	Giới hạn
Mỗi giây (Burst)	20 yêu cầu
Mỗi phút (Duy trì)	100 yêu cầu

Header giới hạn tốc độ

Các response bao gồm các header hiển thị mức sử dụng hiện tại của bạn:

X-RateLimit-Limit — Số yêu cầu tối đa được phép trong cửa sổ hiện tại.
X-RateLimit-Remaining — Số yêu cầu còn lại trước khi bạn đạt giới hạn.
X-RateLimit-Reset — Số giây cho đến khi cửa sổ hiện tại được reset.

Khi vượt quá giới hạn, API trả về 429 Too Many Requests. Hãy triển khai exponential backoff trong logic retry.

Xử lý lỗi

Để biết ý nghĩa của một lỗi và cách khắc phục, hãy xem các trang mã lỗi và lỗi giao dịch.

Error Codes

Danh sách đầy đủ các mã lỗi và ý nghĩa của chúng.

Transaction Failures

Các vấn đề giao dịch thường gặp và cách xử lý.

Webhooks

Nhận thông báo theo thời gian thực khi thanh toán, gói đăng ký và các sự kiện khác xảy ra. Thiết lập webhooks trong dashboard và xử lý các sự kiện mà tích hợp của bạn cần.

Webhook Guide

Thiết lập webhooks, xử lý sự kiện và xác minh chữ ký.

Hướng dẫn tích hợp

Bắt đầu với một trong các hướng dẫn sau để xây dựng tích hợp đầu tiên của bạn:

One-time Payments

Tạo checkout session, payment link và xử lý thanh toán.

Subscriptions

Thiết lập thanh toán định kỳ, quản lý plan và xử lý các sự kiện trong vòng đời.

Usage-Based Billing

Đo lường mức sử dụng và tính phí khách hàng dựa trên mức tiêu thụ.

Checkout Sessions

Tạo trải nghiệm thanh toán được lưu trữ an toàn.

SDKs & Libraries

Mobile Checkout SDKs

​URL môi trường

​Xác thực

​Định dạng response

​Giới hạn tốc độ

​Tier mặc định

​Các tier cao hơn

​Yêu cầu không xác thực

​Header giới hạn tốc độ

​Xử lý lỗi

Error Codes

Transaction Failures

​Webhooks

Webhook Guide

​Hướng dẫn tích hợp

One-time Payments

Subscriptions

Usage-Based Billing

Checkout Sessions

URL môi trường

Xác thực

Định dạng response

Giới hạn tốc độ

Tier mặc định

Các tier cao hơn

Yêu cầu không xác thực

Header giới hạn tốc độ

Xử lý lỗi

Webhooks

Hướng dẫn tích hợp