Giới Thiệu

Tự động cung cấp khóa giấy phép, tệp tải về, cờ tính năng, và truy cập vào các nền tảng như Discord, GitHub, Telegram, Framer, và Notion khi khách hàng thanh toán.

Entitlements biến một lần thanh toán thành công hoặc đăng ký hoạt động thành quyền truy cập thực tế: một khóa giấy phép trong hộp thư của khách hàng, một cờ tính năng ứng dụng của bạn kiểm tra, 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 Telegram, hoặc một gói tệp tải về. Dodo Payments tự động phát hành, theo dõi và thu hồi quyền truy cập đó khi vòng đời thanh toán thay đổi.

The Entitlements dashboard. Each entitlement is a reusable template; the right pane shows individual customer grants.

​

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.

Feature Flags

Chặn các tính năng trong ứng dụng của bạn sau khi mua. Được cung cấp ngay lập tức, kiểm tra thông qua API, thu hồi khi hủy bỏ.

Discord

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

GitHub

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

Telegram

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

Framer

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

Notion

Nhân bản 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ác sự kiện thanh toán và đăng ký mà bạn đã nhận được dưới dạng webhooks. Bạn không cần phải tự gọi API grant cho các lần mua. Dodo Payments tự động tạo và thu hồi grants 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 một khoản thanh toán hoàn thành hoặc một đăng ký trở nên hoạt động. Khóa giấy phép và cờ tính năng nhảy trực tiếp đế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 truy cập để hoàn thành ủy quyền. Các tích hợp trực tiếp từ nền tảng (Telegram, Framer, Tệp Kỹ Thuật Số) chỉ nằm trong pending ngắn gọn trong khi việc cung cấp được chuẩn bị, sau đó chuyển sang delivered.

2. Delivered

   Khi việc cung cấp hoàn thành (khóa giấy phép được tạo, vai trò được gán, truy cập kho lưu trữ được cấp, liên kết tệp được giải quyết, OAuth hoàn thành), grant 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 (token OAuth bị thu hồi, quyền bị từ chối, tệp không còn tồn tại), grant di chuyển đến failed. Các trường error_code và error_message ghi nhận lý do.

4. Revoked

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

​

Hành vi của Grant theo sự kiện

Sự kiện	Hành vi
payment.succeeded (thanh toán một lần)	Phát hành một grant cho mỗi quyền lợi được đính kèm.
payment.succeeded (thanh toán liên kết đăng ký)	Không hoạt động. Grants được điều khiển bởi sự kiện đăng ký dưới đây.
subscription.active	Phát hành grants cho bất kỳ quyền lợi đính kèm nào chưa có grant. Cấp lại bất kỳ grants nào trước đó đã bị thu hồi cho cùng đăng ký.
subscription.renewed	Không hoạt động. Các grants hiện tại tồn tại qua các lần gia hạn.
subscription.on_hold	Thu hồi tất cả grants đã cung cấp và đang chờ xử lý. revocation_reason: subscription_on_hold.
subscription.cancelled	Thu hồi tất cả. revocation_reason: subscription_cancelled.
subscription.expired	Thu hồi tất cả. revocation_reason: subscription_expired.
subscription.plan_changed	Thu hồi tất cả grants hiện tại, sau đó phát hành grants cho quyền lợi 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 khoản thanh toán đó. revocation_reason: refund.
Thu hồi API thủ công	Thu hồi bằng revocation_reason: manual. Thu hồi thủ công không được cấp lại tự động khi gia hạn đăng ký.
Khóa giấy phép bị vô hiệu hóa	Đối với grants khóa giấy phép, việc vô hiệu hóa khóa cơ bản sẽ thu hồi grant bằng revocation_reason: license_key_disabled. Grant được tự động kích hoạt lại nếu khóa được kích hoạt lại.
Phát hiện drift nền tảng	Nếu phần nền tảng của một tích hợp chệch hướng so với đồng bộ (một vai trò Discord bị loại bỏ thủ công, ứng dụng GitHub mất quyền truy cập để kho lưu trữ, hoặc một cuộc đối chiếu phát hiện mục tiêu thiếu), grant bị thu hồi với revocation_reason: platform_external. Không được cấp lại tự động khi gia hạn đăng ký cho đến khi vấn đề nền tảng được giải quyết.

Grants dựa trên đăng ký là idempotent cho mỗi (entitlement, customer, subscription); 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 cho mỗi (entitlement, customer, payment).

---

​

Tạo quyền lợi đầu tiên của bạn

1. Open Entitlements

   Đi tới Entitlements trong bảng điều khiển Dodo Payments của bạn và nhấp vào + để tạo một quyền lợi mới.

2. Pick an integration

   Chọn loại tích hợp: Key giấy phép, Tệp kỹ thuật số, Cờ tính năng, 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 đầu tiên nếu bạn chưa làm.

3. Configure delivery

   Điền vào các trường cụ thể cho tích hợp. Ví dụ, GitHub yêu cầu kho lưu trữ và mức quyền; Discord yêu cầu máy chủ và vai trò tùy chọn; Khóa giấy phép yêu cầu hạn mức kích hoạt và ngày hết hạn.

   

   Creating a GitHub entitlement. Each integration shows the fields it needs.

4. Save

   Lưu quyền lợi. Bây giờ bạn có thể đính kèm nó vào bất kỳ sản phẩm nào.

​

Đính kèm quyền lợi vào sản phẩm

Mở một sản phẩm, mở rộng Cài đặt nâng cao → Quyền lợi & Tín dụng, và chọn các quyền lợi mà nên được cung cấp khi sản phẩm được mua. Một sản phẩm có thể cung cấp nhiều quyền lợi cùng một lúc. Ví dụ, một kế hoạch Pro có thể bao gồm một khóa giấy phép, quyền truy cập GitHub, và một vai trò Discord.

Attaching entitlements to a product. Selected entitlements are delivered on every successful purchase or active subscription.

---

​

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 một email cung cấp sau khi mua chứa khóa giấy phép, liên kết tải về, liên kết mời OAuth, hoặc lời mời nền tảng, tùy theo các quyền lợi trên sản phẩm. Các chi tiết này vẫn có sẵn vô thời hạn từ Cổng thông tin Khách hàng dưới lịch sử đơn hàng của họ.

​

Cung cấp dựa trên OAuth

Truy cập đăng ký Discord, GitHub và Notion yêu cầu khách hàng ủy quyền cho Dodo Payments để cấp quyền truy cập cho họ. Các grants này duy trì trạng thái pending cho đến khi khách hàng hoàn thành luồng OAuth bằng cách sử dụng liên kết từ email hoặc cổng thông tin khách hàng của họ. Sau khi họ ủy quyền, grant chuyển đến delivered và quyền truy cập nền tảng được cung cấp ngay lập tức.

​

Thu hồi

Các grants bị thu hồi được loại bỏ ở cấp độ nền tảng: vai trò Discord bị loại bỏ, cộng tác viên GitHub bị loại bỏ, khóa giấy phép bị vô hiệu hóa. Khách hàng nhìn thấy sự thay đổi được phản ánh trong cổng thông tin khách hàng.

Đối với Tệp Kỹ Thuật Số, việc thu hồi loại bỏ quyền truy cập vào các URL được định sẵn trong tương lai nhưng không làm vô hiệu hóa các bản sao mà khách hàng đã tải xuống. Đặt nội dung kế hoạch tương ứng.

---

​

Quản lý Grants

Mở bất kỳ quyền lợi 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 cung cấp, và hành động thu hồi.

Bạn cũng có thể quản lý grants bằng chương trình:

TypeScript

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', {
  id: 'ent_abc123',
});

client.entitlements.grants.list(
    "ent_abc123",
    status="Delivered",
)

client.entitlements.grants.revoke(
    "grant_xyz789",
    id="ent_abc123",
)

grants, _ := client.Entitlements.Grants.List(
  ctx, "ent_abc123",
  dodopayments.EntitlementGrantListParams{Status: dodopayments.F("delivered")},
)

_, _ = client.Entitlements.Grants.Revoke(ctx, "grant_xyz789", "ent_abc123")

---

​

Quản lý API

Create Entitlement

Tạo một quyền lợi mới của bất kỳ loại tích hợp nào.

List Entitlements

Danh sách các quyền lợi với bộ lọc theo loại tích hợp.

Get Entitlement

Truy xuất một quyền lợi 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 quyền lợi; các grants hiện tại không bị ảnh hưởng.

Upload File

Tải lên tệp cho một quyền lợi Tệp Kỹ Thuật Số (tối đa 500 MiB).

List Grants

Danh sách tất cả grants cho một quyền lợi với bộ lọc trạng thái và khách hàng.

Revoke Grant

Thu hồi thủ công một grant.

---

​

Webhooks

Dodo Payments phát bốn sự kiện webhook cho vòng đời grant. Đăng ký các sự kiện này để giữ cho ứ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ện	Sinh ra khi
entitlement_grant.created	Một grant mới được tạo. Grants khóa-key đến delivered; mọi tích hợp khác đến pending và chuyển đến delivered khi cuộc gọi nền tảng thành công (hoặc, đối với tích hợp dựa trên OAuth, khi khách hàng ủy quyền).
entitlement_grant.delivered	Grant chuyển sang được cung cấp. Khách hàng hiện có quyền truy cập.
entitlement_grant.failed	Grant không thể được cung cấp. Kiểm tra error_code và error_message.
entitlement_grant.revoked	Quyền truy cập đã bị rút lại. Kiểm tra revocation_reason.

Entitlement Grant Webhook Payloads

Xem toàn bộ sơ đồ 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 quyền lợi cho mỗi kênh cung cấp. Đừng chia sẻ một quyền lợi Discord duy nhất giữa các sản phẩm có ý định vai trò khác nhau; tạo một quyền lợi cho mỗi vai trò để thu hồi sạch. - Thử nghiệm ở chế độ thử nghiệm trước tiên. Tạo quyền lợi, đính kèm nó vào một sản phẩm thử nghiệm, chạy một lần thanh toán, và xem grant chuyển qua pending → delivered. Xác nhận rằng việc hủy đăng ký thử nghiệm thu hồi grant. - Lắng nghe entitlement_grant.delivered, không phải payment.succeeded. Một thanh toán có thể thành công trước khi việc hoàn thành kết thúc (đặc biệt đối với các luồng OAuth). Đợi sự kiện được cung cấp trước khi mở khóa các tính năng phụ thuộc trong các hệ thống của bạn. - Xem entitlement_grant.failed là hành động được thực hiện. 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. Hiển thị những trường hợp này cho nhóm hỗ trợ của bạn hoặc kích hoạt cấp lại. - Map revocation_reason vào các luồng giữ chân của bạn. Một thu hồi subscription_on_hold có thể phục hồi (khách hàng có thể cập nhật thẻ của họ). Một thu hồi manual là có chủ ý. Đối xử chúng khác nhau trong thông tin khách hàng.