License Keys

​

License Key là gì?

• Cấp phép phần mềm: ứng dụng desktop, plugin và CLI.
• Kiểm soát theo seat: giới hạn số lần kích hoạt cho mỗi user hoặc device.
• Digital goods: kiểm soát quyền tải xuống, cập nhật hoặc tính năng premium.

​

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

1

Open Entitlements

Đi đến Entitlements trong dashboard và nhấp + để tạo entitlement.

2

Choose License Key

Chọn License Keys, nhập Name và cấu hình cách mỗi key được phát hành hoạt động:

• Fulfillment Mode: Automatic (mặc định) sẽ tạo và gửi email cho từng key. Manual cho phép bạn tự cung cấp từng key. Xem Manual Fulfillment.
• Activations Limit: số lượng activation đang hoạt động tối đa cho mỗi key, ví dụ 1 cho một user hoặc 5 cho license dành cho team. Chọn Unlimited nếu không muốn giới hạn.
• License Length: khoảng thời gian key còn hợp lệ sau khi được phát hành, ví dụ 30 ngày hoặc 1 năm, hoặc No expiration. Đối với product dạng subscription, hãy chọn No expiration: các key được phát hành cho subscription không hết hạn và tính hợp lệ của chúng sẽ tuân theo trạng thái subscription.
• Activation Message: hướng dẫn tùy chọn dành cho customer, tối đa 2.500 ký tự, được đưa vào email gửi key. Ví dụ: Paste the key in Settings → License hoặc Run: mycli activate <key>.

3

Save the Entitlement

Nhấp Create Entitlement. Bây giờ bạn có thể gắn entitlement này vào bất kỳ product nào.

​

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

​

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

​

Hành vi theo số lượng

• Product dạng subscription phát hành một key cho mỗi seat (subscriptions.quantity).
• Product one-time phát hành một key cho mỗi unit của line item trong cart (product_cart.quantity).
• Grant thủ công qua API phát hành chính xác một key.

​

Fulfillment Mode

• auto (mặc định, Automatic trong dashboard): Dodo Payments tạo và gửi email key khi có payment hoặc subscription. Đây là hành vi trong bảng trên và được áp dụng khi fulfillment_mode bị bỏ qua.
• manual (Manual trong dashboard): mỗi unit được mua sẽ tạo một grant Pending không có key và bạn cung cấp giá trị của từng key. Xem Manual Fulfillment.

​

Manual Fulfillment

​

Khi nào nên sử dụng

• Sử dụng key của riêng bạn: ứng dụng, product desktop hoặc license server của bạn tạo key.
• Nhà cung cấp bên thứ ba: bạn bán lại key do nhà cung cấp upstream phát hành, chẳng hạn như game key, API credential hoặc license cho platform đối tác.
• Kho có số lượng giới hạn: bạn phân phối code từ một kho được cấp phát trước và gán từng code một.
• Kiểm tra thủ công: bạn muốn kiểm tra giao dịch mua trước khi cấp quyền truy cập.

​

Bật Manual Fulfillment

// `client` is a DodoPayments instance created with your API key.
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 các grant đang chờ fulfillment

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

​

Phân phối key

curl -X POST https://test.dodopayments.com/grants/entg_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 thực, hủy kích hoạt

​

Kích hoạt license

import DodoPayments from 'dodopayments';

// The license endpoints don't check the token, but the SDK requires a value.
// Never ship your secret API key in client software.
const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' });

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

console.log(response.id);

from dodopayments import DodoPayments

# The license endpoints don't check the token, but the SDK requires a value.
client = DodoPayments(bearer_token="public", environment="test_mode")

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

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 thực license

// Uses the client from the activation example.
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 activation instance

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

​

Quản lý key

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);
}

​

Import license key hiện có 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',
});

​

Key khác nhau theo nguồn như thế nào

​

License key trong Return URL

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%2CLK-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 key cũ

​

Best Practices

• Chọn giới hạn activation rõ ràng: chọn các giá trị mặc định như 1 cho ứng dụng một user hoặc 3–5 cho license team, đồng thời ghi rõ các giá trị này cho customer.
• Viết activation message chính xác: customer sao chép nội dung này từ email license key, vì vậy path và command chính xác sẽ giúp tránh các ticket hỗ trợ.
• Xác thực key với API: đối với product có kết nối mạng, hãy gọi /licenses/validate thay vì dựa vào activation được cache cục bộ.
• Sử dụng webhook để thu hồi: xử lý entitlement_grant.revoked để tắt các tính năng trong ứng dụng khi customer hủy hoặc nhận refund.
• Kiểm thử subscription và giao dịch one-time: hành vi của license key khác nhau giữa hai loại này; ví dụ key subscription không hết hạn, vì vậy hãy kiểm thử cả hai trước khi đưa vào vận hành.