License Keys

​

Mã Giấy Phép là gì?

• Software licensing: Desktop apps, plugins, and CLIs
• Per-seat controls: Limit activations per user or device
• Digital goods: Gate downloads, updates, or premium features

​

Tạo một Quyền cấp phép License Key

1

Open Entitlements

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

2

Choose License Key

Chọn License Key làm tích hợp. Cấu hình cách mà mỗi mã được cấp phát hành xử lý:

• Giới hạn Kích hoạt: Số lượng kích hoạt đồng thời tối đa cho mỗi mã (ví dụ, 1 cho ứng dụng một người dùng, 5 cho giấy phép nhóm, để trống cho không giới hạn).
• Thời Gian: Thời gian mã duy trì hiệu lực sau khi phát hành (ví dụ, 30 ngày, 1 năm). Đối với mã được cấp phát hành thông qua đăng ký, để trống; mã vẫn có hiệu lực miễn là đăng ký còn hoạt động.
• Hướng Dẫn Kích Hoạt: Các hướng dẫn dành cho khách hàng được gửi kèm với mã qua email. Ví dụ: Paste the key in Settings → License hoặc Run: mycli activate <key>.

3

Save the entitlement

Lưu. Quyền cấp phát hành giờ có sẵn để gắn vào bất kỳ sản phẩm nào.

​

Gắn vào Sản Phẩm

​

Cách Mã Được Phát Hành

​

Hành vi với Số lượng

• Sản phẩm đăng ký cấp một mã cho mỗi chỗ (subscriptions.quantity).
• Sản phẩm một lần cấp một mã cho mỗi dòng sản phẩm trong giỏ hàng (product_cart.quantity).
• Cấp phát thủ công qua API chỉ cấp đúng một mã.

​

Chế độ thực hiện

• auto (mặc định): Dodo Payments tự động tạo và gửi khóa qua email khi thanh toán hoặc đăng ký gói. Đây là hành vi được mô tả ở trên và áp dụng khi fulfillment_mode bị bỏ qua.
• manual: Giao dịch mua tạo một grant Pending không có khóa, và bạn tự cung cấp từng giá trị khóa. Xem Manual Fulfillment bên dưới.

​

Thực hiện thủ công

​

Khi nào sử dụng

• Mang theo mã của bạn: Mã được tạo bởi ứng dụng của bạn, một sản phẩm desktop, hoặc máy chủ cấp phép của bạn.
• Nhà cung cấp bên thứ ba: Bạn bán lại các mã được cấp bởi nhà cung cấp thượng nguồn (một mã game, thông tin xác thực API, nền tảng đối tác).
• Tồn kho hữu hạn: Bạn cung cấp mã từ một nhóm đã phân bổ trước và muốn chỉ định chúng từng cái một.
• Đánh giá con người: Bạn muốn xem xét một giao dịch mua trước khi phát hành quyền truy cập.

​

Kích hoạt thực hiện thủ công

const entitlement = await client.entitlements.create({
  name: 'Pro License (Manual)',
  integration_type: 'license_key',
  integration_config: {
    fulfillment_mode: 'manual',
    activations_limit: 5,
    duration_count: 1,
    duration_interval: 'Year',
  },
});

curl -X POST https://test.dodopayments.com/entitlements \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro License (Manual)",
    "integration_type": "license_key",
    "integration_config": {
      "fulfillment_mode": "manual",
      "activations_limit": 5,
      "duration_count": 1,
      "duration_interval": "Year"
    }
  }'

​

Tìm quyền cấp chờ thực hiện

const pending = await client.customers.listEntitlementGrants('customer_id', {
  integration_type: 'license_key',
  status: 'Pending',
});

​

Cung cấp mã

curl -X POST https://test.dodopayments.com/grants/grant_8VbC6JDZ/license-key \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "activations_limit": 5,
    "expires_at": "2027-05-01T00:00:00Z"
  }'

​

Kích hoạt, Xác nhận, Hủy kích hoạt

​

Kích hoạt một license

import DodoPayments from 'dodopayments';

// No API key needed for public license endpoints
const client = new DodoPayments();

const response = await client.licenses.activate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  name: 'Device Name',
});

console.log(response.id);

client.licenses.activate(
    license_key="PRO-AAAA-BBBB-CCCC-DDDD",
    name="Device Name",
)

curl -X POST https://test.dodopayments.com/licenses/activate \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "PRO-AAAA-BBBB-CCCC-DDDD",
    "name": "Device Name"
  }'

​

Xác nhận một license

const response = await client.licenses.validate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
});

console.log(response.valid);

curl -X POST https://test.dodopayments.com/licenses/validate \
  -H "Content-Type: application/json" \
  -d '{ "license_key": "PRO-AAAA-BBBB-CCCC-DDDD" }'

​

Hủy kích hoạt một phiên bản kích hoạt

await client.licenses.deactivate({
  license_key: 'PRO-AAAA-BBBB-CCCC-DDDD',
  license_key_instance_id: 'instance_abc123',
});

​

Quản lý Mã

const grants = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Delivered',
});

for (const grant of grants.items) {
  console.log(grant.license_key.key, grant.license_key.activations_used);
}

​

Nhập Mã License Hiện Tại qua API

const licenseKey = await client.licenseKeys.create({
  customer_id: 'cus_abc123',
  product_id: 'pdt_456',
  key: 'YOUR-EXISTING-LICENSE-KEY',
  activations_limit: 5,
  expires_at: '2026-12-31T23:59:59Z',
});

​

Sự Khác Biệt của Mã theo Nguồn

​

Mã License trong URL Trả về

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com

https://yoursite.com/return?payment_id=pay_xxx&status=succeeded&license_key=LK-001,LK-002&email=customer%40example.com

https://yoursite.com/return?subscription_id=sub_xxx&status=active&license_key=LK-001&email=customer%40example.com

​

Quản lý API

​

Webhooks

​

License Keys cũ

​

Best Practices

• Giữ giới hạn kích hoạt rõ ràng: Chọn các giá trị mặc định hợp lý (1 cho ứng dụng một người dùng, 3–5 cho license dành cho nhóm) và ghi lại chúng.
• Cung cấp hướng dẫn kích hoạt chính xác: Customer sẽ dán các hướng dẫn này từ email của họ, vì vậy path và command chính xác sẽ giúp giảm số lượng ticket hỗ trợ.
• Validate key ở phía server: Đối với các product được kết nối mạng, hãy validate qua /licenses/validate thay vì cache activation cục bộ.
• Sử dụng webhook để thu hồi: Lắng nghe entitlement_grant.revoked để vô hiệu hóa ngay các tính năng trong app khi customer hủy hoặc được refund.
• Test với subscription và giao dịch một lần: Hành vi của license key có khác biệt nhỏ giữa hai loại này, vì vậy hãy test cả hai trước khi go live.