Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Entitlements biến một thanh toán thành công hoặc một đăng ký đang hoạt động thành quyền truy cập thực sự: một mã giấy phép trong hộp thư đến của khách hàng, một vai trò Discord, một kho lưu trữ GitHub, một mẫu Notion, một liên kết remix Framer, một lời mời trò chuyện trên Telegram, hoặc một gói tập tin tải xuống. Dodo Payments phát hành, theo dõi, và thu hồi quyền truy cập đó tự động khi vòng đời thanh toán thay đổi.
Bảng điều khiển Entitlements với danh sách entitlement ở bên trái và hoạt động grant ở bên phải

​
Entitlements là gì?

Một entitlement là một định nghĩa tái sử dụng của thứ bạn cung cấp cho khách hàng: một mã giấy phép Pro, một vai trò “Patrons” trên Discord, quyền truy cập vào kho lưu trữ GitHub riêng của bạn, một gói e-book có thể tải xuống. Bạn gắn entitlements vào sản phẩm, và Dodo Payments xử lý phần còn lại. Khi một khách hàng mua sản phẩm, Dodo Payments tạo một grant, tức là việc phát hành entitlement đó cho khách hàng cụ thể. Grants di chuyển qua một tập hợp trạng thái nhỏ: pending trong khi việc giao hàng đang tiến hành, delivered khi khách hàng có quyền truy cập, failed nếu không thể hoàn thành việc giao hàng, và revoked khi quyền truy cập bị thu hồi.
Entitlements kiểm soát fulfillment (khách hàng có quyền truy cập không?). Credits kiểm soát consumption (họ có thể sử dụng bao nhiêu?). Cả hai có thể được gắn vào cùng một sản phẩm. Xem Thanh toán Dựa trên Tín dụng cho thông tin về credits.

​
Các Tích Hợp Có Sẵn

Dodo Payments cung cấp mỗi entitlement thông qua một tích hợp chuyên dụng. Chọn tích hợp phù hợp với những gì bạn bán.

License Keys

Tạo mã giấy phép duy nhất với giới hạn kích hoạt và thời hạn. Phù hợp nhất cho phần mềm, plugin, và CLI.

Digital Files

Cung cấp các tập tin có thể tải xuống (e-books, mẫu, phương tiện) với URL tải xuống được ký trước và hướng dẫn tùy chọn.

Discord

Cấp một vai trò trong máy chủ Discord của bạn cho khách hàng khi họ mua hàng. Tự động thu hồi khi hủy bỏ.

GitHub

Thêm khách hàng làm cộng tác viên vào một kho lưu trữ riêng ở mức độ quyền hạn bạn chọn.

Telegram

Thêm khách hàng vào một cuộc trò chuyện hoặc kênh riêng trên Telegram sau khi mua.

Framer

Mở khóa một liên kết remix mẫu Framer cho khách hàng thanh toán.

Notion

Sao chép một mẫu Notion vào không gian làm việc của khách hàng khi mua.

​
Cách Thức Hoạt Động Của Grants

Grants được điều khiển bởi cùng các sự kiện thanh toán và đăng ký bạn đã nhận qua webhooks. Bạn không cần phải gọi API grant cho từng lần mua. Dodo Payments tạo và thu hồi grants tự động dựa trên vòng đời thanh toán cơ bản.

​
Vòng Đời Của Grant

1

Created

Một grant được tạo khi thanh toán hoàn thành hoặc đăng ký được kích hoạt. Các mã giấy phép nhảy thẳng đến delivered. Mọi tích hợp khác bắt đầu ở pending. Các tích hợp dựa trên OAuth (Discord, GitHub, Notion) bao gồm một oauth_url mà khách hàng phải ghé thăm để hoàn tất ủy quyền. Các tích hợp trực tiếp nền tảng (Telegram, Framer, Digital Files) nằm ở pending chỉ trong một thời gian ngắn trong khi việc giao hàng được chuẩn bị, sau đó chuyển sang delivered.
2

Delivered

Khi việc giao hàng hoàn thành (mã giấy phép được tạo, vai trò được gán, quyền truy cập vào kho lưu trữ được cấp, các liên kết tập tin được giải quyết, OAuth được hoàn tất), grant sẽ di chuyển đến delivered và delivered_at được thiết lập.
3

Failed

Nếu cuộc gọi tích hợp trả về một lỗi không thể thử lại (mã thông báo OAuth bị thu hồi, quyền bị từ chối, tệp không còn tồn tại), grant sẽ di chuyển đến failed. Các trường error_code và error_message lưu lại lý do.
4

Revoked

Khi quyền truy cập bị thu hồi (hủy đăng ký, hoàn tiền, hoặc thu hồi do thương nhân khởi xướng), grant sẽ di chuyển đến revoked. Trường revocation_reason ghi lại tác nhân kích hoạt.

​
Hành Vi Grant Theo Sự Kiện

Sự KiệnHành Vi
payment.succeeded (thanh toán một lần)Cấp một grant cho mỗi entitlement được gắn.
payment.succeeded (thanh toán liên kết đăng ký)Không thao tác. Grants được điều khiển bởi sự kiện đăng ký bên dưới.
subscription.activeCấp grants cho bất kỳ entitlements nào không đã có. Cấp lại bất kỳ grants nào đã bị thu hồi trước đó cho cùng một đăng ký.
subscription.renewedKhông thao tác. Grants hiện có tồn tại liên tục qua các lần gia hạn.
subscription.on_holdThu hồi tất cả grants đã cấp và đang chờ xử lý. revocation_reason: subscription_on_hold.
subscription.cancelledThu hồi tất cả. revocation_reason: subscription_cancelled.
subscription.expiredThu hồi tất cả. revocation_reason: subscription_expired.
subscription.plan_changedThu hồi tất cả grants hiện có, sau đó cấp grants cho các entitlements của kế hoạch mới. revocation_reason: plan_changed.
refund.succeeded (thanh toán một lần)Thu hồi grants cho thanh toán đó. revocation_reason: refund.
Thu hồi API thủ côngThu hồi với revocation_reason: manual. Các lần thu hồi thủ công không được cấp lại tự động khi gia hạn đăng ký.
Mã giấy phép bị vô hiệu hóaĐối với grants mã giấy phép, vô hiệu hóa mã cơ bản thu hồi grant với revocation_reason: license_key_disabled. Grant sẽ được kích hoạt lại tự động nếu mã được kích hoạt lại.
Phát hiện trôi dạt nền tảngNếu phía nền tảng của một tích hợp bị lệch ra khỏi đồng bộ (một vai trò Discord bị xóa thủ công, Ứng dụng GitHub mất quyền truy cập kho lưu trữ, hoặc qua kiểm tra phát hiện một mục tiêu bị thiếu), grant sẽ bị thu hồi với revocation_reason: platform_external. Không tự cấp lại khi gia hạn đăng ký cho đến khi sự cố nền tảng cơ bản được giải quyết.
Grants điều khiển bởi đăng ký là idempotent theo (entitlement, customer, subscription); các lần gia hạn và kích hoạt lại không tạo ra grants trùng lặp. Grants một lần là idempotent theo (entitlement, customer, payment).

​
Tạo Entitlement Đầu Tiên Của Bạn

1

Open Entitlements

Đi đến Entitlements trong bảng điều khiển Dodo Payments của bạn và bấm + để tạo một entitlement mới.
2

Pick an integration

Chọn loại tích hợp: License Key, Digital Files, Discord, GitHub, Telegram, Framer, hoặc Notion. Đối với các tích hợp nền tảng, kết nối tài khoản của bạn trước nếu bạn chưa thực hiện.
3

Configure delivery

Điền vào các trường cụ thể tích hợp. Ví dụ, GitHub yêu cầu một kho lưu trữ và một mức độ quyền hạn; Discord yêu cầu một máy chủ và một vai trò tùy chọn; License Key yêu cầu giới hạn kích hoạt và thời hạn.
Biểu mẫu Entitlement Mới với bộ chọn tích hợp và các trường cấu hình
4

Save

Lưu entitlement. Bạn có thể gắn nó vào bất kỳ sản phẩm nào.

​
Gắn Entitlements Vào Sản Phẩm

Mở một sản phẩm, mở rộng Advanced Settings → Entitlements & Credits, và chọn các entitlements sẽ được cung cấp khi sản phẩm được mua. Một sản phẩm đơn lẻ có thể cung cấp nhiều entitlements cùng một lúc. Ví dụ, gói Pro có thể bao gồm một mã giấy phép, quyền truy cập GitHub, và một vai trò Discord.
Bảng điều khiển lựa chọn entitlement sản phẩm hiển thị các ô kiểm cho từng entitlement có sẵn

​
Trải Nghiệm Khách Hàng

​
Email và cổng thông tin khách hàng

Khách hàng nhận được email giao hàng sau khi mua chứa mã giấy phép, liên kết tải xuống, liên kết mời OAuth, hoặc lời mời nền tảng, tùy thuộc vào các entitlements của sản phẩm. Cùng thông tin vẫn có sẵn vĩnh viễn từ Cổng Thông Tin Khách Hàng dưới lịch sử đơn hàng của họ.

​
Giao hàng dựa trên OAuth

Quyền truy cập của người đăng ký Discord, GitHub, và Notion yêu cầu khách hàng cấp quyền cho Dodo Payments để cấp quyền truy cập cho họ. Các grants này giữ ở trạng thái pending cho đến khi khách hàng hoàn tất luồng OAuth bằng liên kết từ email hoặc cổng thông tin khách hàng của họ. Một khi họ ủy quyền, grant di chuyển đến delivered và quyền truy cập nền tảng được cấp ngay lập tức.

​
Thu hồi

Các grants bị thu hồi sẽ bị xóa ở cấp nền tảng: vai trò Discord bị xóa, cộng tác viên GitHub bị xóa, mã giấy phép bị vô hiệu hóa. Khách hàng sẽ thấy thay đổi đó phản ánh trong cổng thông tin khách hàng.
Đối với Tập Tin Số, việc thu hồi sẽ xóa quyền truy cập vào các URL được ký trước trong tương lai nhưng không vô hiệu hóa các bản sao mà khách hàng đã tải xuống. Lập kế hoạch nội dung gói theo cách đó.

​
Quản Lý Grants

Mở bất kỳ entitlement nào từ bảng điều khiển để xem các grants của nó. Bảng chi tiết grant hiển thị tổng số grants, bộ lọc trạng thái, thông tin khách hàng, ngày giao hàng, và hành động thu hồi. Bạn cũng có thể quản lý grants qua lập trình: 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
});

// List grants for an entitlement
const grants = await client.entitlements.grants.list('ent_abc123', {
  status: 'delivered',
});

// Revoke a single grant
await client.entitlements.grants.revoke('grant_xyz789', {
  path_id: 'ent_abc123',
});

​
Quản Lý API

Create Entitlement

Tạo một entitlement mới thuộc bất kỳ loại tích hợp nào.

List Entitlements

Liệt kê entitlements với bộ lọc theo loại tích hợp.

Get Entitlement

Lấy một entitlement và cấu hình giải quyết của nó.

Update Entitlement

Cập nhật tên, mô tả, hoặc cấu hình tích hợp.

Delete Entitlement

Xóa mềm một entitlement; grants hiện có không bị ảnh hưởng.

Upload File

Tải lên một tập tin cho một entitlement Digital Files (tối đa 100 MB).

List Grants

Liệt kê tất cả grants cho một entitlement với trạng thái và bộ lọc khách hàng.

Revoke Grant

Thu hồi một grant đơn lẻ bằng tay.

​
Webhooks

Dodo Payments kích hoạt bốn sự kiện webhook cho vòng đời của grant. Đăng ký những sự kiện này để giữ ứng dụng của bạn đồng bộ với những gì mỗi khách hàng có thể truy cập.
Sự KiệnKích hoạt khi
entitlement_grant.createdMột grant mới được tạo. Grants mã giấy phép xuất hiện delivered; mọi tích hợp khác xuất hiện pending và chuyển đổi sang delivered khi cuộc gọi nền tảng thành công (hoặc với các tích hợp dựa trên OAuth, khi khách hàng được ủy quyền).
entitlement_grant.deliveredGrant chuyển sang trạng thái đã giao. Khách hàng hiện có quyền truy cập.
entitlement_grant.failedGrant không thể được giao. Kiểm tra error_code và error_message.
entitlement_grant.revokedQuyền truy cập đã bị thu hồi. Kiểm tra revocation_reason.

Entitlement Grant Webhook Payloads

Xem đầy đủ cấu trúc tải, các sự kiện mẫu, và tham chiếu revocation_reason.

​
Thực Hành Tốt Nhất

  • Sử dụng một entitlement cho mỗi kênh giao hàng. Không chia sẻ một entitlement Discord duy nhất cho các sản phẩm với ý định vai trò khác nhau; tạo một cái cho mỗi vai trò để dễ thu hồi.
  • Kiểm tra trong chế độ kiểm tra trước tiên. Tạo entitlement, gắn vào một sản phẩm thử nghiệm, chạy thử nghiệm thanh toán, và xem grant chuyển qua pending → delivered. Xác nhận việc hủy đăng ký thử nghiệm thu hồi grant.
  • Lắng nghe entitlement_grant.delivered, không payment.succeeded. Một thanh toán có thể thành công trước khi hoàn thành fulfilment (đặc biệt là đối với các luồng OAuth). Chờ sự kiện giao hàng trước khi mở khóa các tính năng phụ thuộc trong hệ thống của bạn.
  • Xử lý entitlement_grant.failed như có thể hành động. Một grant thất bại có nghĩa là một khách hàng đã thanh toán nhưng không nhận được quyền truy cập. Nâng cao điều này cho đội hỗ trợ của bạn hoặc kích hoạt một grant mới.
  • Đối sánh revocation_reason với lưu lượng giữ chân của bạn. Một quyền thu hồi subscription_on_hold có thể phục hồi được (khách hàng có thể cập nhật thẻ của họ). Một quyền thu hồi manual là có chủ đích. Xử lý chúng khác nhau trong thông tin liên lạc khách hàng.
Last modified on May 14, 2026