手动许可证密钥履行集成指南

使用手动许可证密钥履行时，每次购买都会创建一个 Pending grant，等待您提供密钥值，而不是由 Dodo Payments 在付款时生成密钥。密钥可以来自您自己的系统、第三方供应商或有限的代码池。完成本指南后，您将拥有：

一个产品的许可证密钥授权设置为manual履行。
一个 webhooks 监听器，用于检测客户何时等待密钥。
一个交付调用，用于传递密钥并自动通知客户。

License Keys Overview

完整的许可证密钥生命周期以及 fulfillment_mode 设置。

Fulfill License Key Grant API

用于交付密钥的 endpoint 的 API reference。

工作原理

下面的流程展示了一次购买从 checkout 到密钥交付的过程：手动履行只会改变签发步骤。交付后，该密钥在激活、验证、停用、过期和撤销方面的行为与自动生成的密钥相同。购买多个单位时，每个单位会创建一个 Pending grant，并且每个 grant 都需要自己的密钥。

前提条件

要按照本指南操作，您需要：

一个 Dodo Payments merchant account。
一个在 Developer → API Keys 下创建并存储在 DODO_PAYMENTS_API_KEY 中的 API key，以及从 Developer → Webhooks 获取并存储在 DODO_PAYMENTS_WEBHOOK_KEY 中的 webhook signing secret。请参阅 API key generation guide。
一个可以接收 webhooks 的 backend endpoint。

构建期间请使用 https://test.dodopayments.com 和 test mode credentials。上线 production 时，切换到 https://live.dodopayments.com 和 live mode keys。

步骤 1 — 在手动模式下创建 License Key Entitlement

entitlement 是对您所交付内容的可复用定义。创建一个 License Key entitlement，并将其 fulfillment_mode 设置为 manual。

Dashboard
API

Open Entitlements

前往 dashboard 中的 Entitlements，点击 + 创建 entitlement。

Choose License Key

选择 License Keys 并输入 Name。表单包含以下字段：

Fulfillment Mode：默认为 Automatic。此设置用于启用手动履行，您将在下一步中进行更改。
License Length：每个已签发密钥保持有效的时长，或 No expiration。
Activations Limit：每个密钥允许的最大激活次数，或 Unlimited。
Activation Message：可选的面向客户的消息，在客户激活密钥时显示，并包含在 license key email 中。

New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message

Set Fulfillment Mode to Manual

打开 Fulfillment Mode 下拉菜单，将其从 Automatic 更改为 Manual。本指南的其余部分都依赖此设置：如果不启用该设置，Dodo Payments 会自动生成并通过 email 发送密钥，也不会创建 pending grant。选择 Manual 后，每次购买都会创建一个 Pending grant，供您履行。点击 Create Entitlement 保存。

将 integration_config.fulfillment_mode 设置为 manual，创建该 entitlement。

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

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

console.log(entitlement.id); // ent_...

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

entitlement = 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",
    },
)

print(entitlement.id)

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"
    }
  }'

fulfillment_mode 默认值为 auto。如果省略该字段，或不修改现有 entitlement，该 entitlement 会继续使用自动履行。只有明确设置为 manual 的 entitlements 才会创建 pending grants。

步骤 2 — 将 Entitlement 附加到 Product

打开您要销售的 product，进入其 Entitlements 部分，然后选择步骤 1 中设置为 Manual 的 License Key entitlement。一次购买中，一个 product 可以将此 license key 与其他 entitlements 一起交付。如果您还没有 product，请先创建一次性 product 或 subscription product。要通过 checkout 销售，请参阅 Integration Guide。

Product entitlements panel with License Key selected — Selecting the License Key entitlement in the product entitlements panel.

履行模式是 entitlement 的属性，而不是 product 的属性。由于您在步骤 1 中将其设置为 Manual，每个附加了此 entitlement 的 product 在购买时都会创建 Pending license-key grants。您无需在 product 上配置其他内容。

步骤 3 — 检测 Pending Grants

客户购买 product 后，Dodo Payments 会创建一个状态为 Pending 且未附加密钥的 grant，并发送 entitlement_grant.created webhook。此事件表示有客户正在等待密钥。

监听 Webhook

在 dashboard 的 Developer → Webhooks 下添加 webhook endpoint，然后处理 pending license-key grants。webhooks 遵循 Standard Webhooks 规范，因此您可以使用 standardwebhooks library 对其进行验证：

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();
  const headers = {
    'webhook-id': request.headers.get('webhook-id') || '',
    'webhook-signature': request.headers.get('webhook-signature') || '',
    'webhook-timestamp': request.headers.get('webhook-timestamp') || '',
  };

  await webhook.verify(rawBody, headers);
  const event = JSON.parse(rawBody);

  // A customer bought a manual-mode license key and is waiting for it.
  if (
    event.type === 'entitlement_grant.created' &&
    event.data.integration_type === 'license_key' &&
    event.data.status === 'Pending'
  ) {
    // queueLicenseKeyFulfillment is your own job queue, not part of the SDK.
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

grant payload 包含 integration_type: "license_key"，因此无需额外 lookup 即可识别 license-key grant。Webhook deliveries 可能会重复，因此请跳过您已经处理过其 webhook-id header 的事件。完整 payload 请参阅 Entitlement Grant webhook reference。

或轮询 List Grants API

如果您不想依赖 webhooks，可以列出 License Key entitlement 的 grants，并按 status 进行筛选。License Key entitlement 上的每个 grant 都是 license-key grant，因此无需使用 integration_type 筛选条件：

// Uses the client from Step 1.
const pending = await client.entitlements.grants.list('ent_license_key_id', {
  status: 'Pending',
});

for (const grant of pending.items) {
  console.log(`Grant ${grant.id} for customer ${grant.customer_id} needs a key`);
}

curl -G https://test.dodopayments.com/entitlements/ent_license_key_id/grants \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  --data-urlencode "status=Pending"

步骤 4 — 交付密钥

从您自己的系统获取密钥值，然后将其提交到 Fulfill License Key Grant endpoint。该调用需要具有 Editor permission 的 secret API key。它不是 public license endpoints 之一。SDKs 也提供了此功能，例如在 TypeScript 中为 client.entitlements.grants.fulfillLicenseKey()，在 Python 中为 client.entitlements.grants.fulfill_license_key()。

async function fulfill(grantId: string, key: string) {
  const res = await fetch(
    `https://test.dodopayments.com/grants/${grantId}/license-key`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      },
      body: JSON.stringify({
        key,
        // Optional — fall back to the entitlement config when omitted
        activations_limit: 5,
        expires_at: '2027-05-01T00:00:00Z',
      }),
    },
  );

  if (!res.ok) {
    // See the status code table below for handling
    throw new Error(`Fulfillment failed: ${res.status}`);
  }

  return res.json(); // updated grant, now status: "Delivered"
}

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"
  }'

Request Fields

string

必填

要交付给客户的 license key 字符串，最多 255 个字符。首尾空白会被去除，空值或仅包含空白的值会被拒绝。

integer

每个密钥的 activation limit，至少为 1。省略时使用 entitlement 的 Activations Limit。

string

每个密钥的 expiry（ISO 8601）。省略时，一次性 grant 的密钥根据 entitlement 的 License Length 过期；subscription grant 的密钥没有 expiry，其有效性遵循 subscription。

成功后，grant 会变为 Delivered，Dodo Payments 会将密钥通过 email 发送给客户（客户收到的 email 与自动履行时相同），并触发 license_key.created 和 entitlement_grant.delivered webhook events。 email 包含 license key、product、activation limit、expiry 以及您的激活说明：

Customer license key email showing the key, product, activation limit, expiry, and activation instructions — The license key email the customer receives once you fulfill the grant.

您无需自行通过 email 发送密钥。grant 履行后会自动完成交付。

步骤 5 — 处理错误和重试

endpoint 会在交付任何内容前验证 grant。请处理以下响应：

Status	Meaning	What to do
`200`	密钥已交付。grant 现在为 `Delivered`。	完成。
`400`	不是 license-key grant，或密钥为空或仅包含空白。	修正 request。不要在不做修改的情况下重试。
`404`	您的 business 中不存在该 ID 对应的 grant。	检查 `grant_id`。
`409`	grant 未等待履行（已交付、已撤销或已有密钥），或者该密钥值已存在。	如果 grant 已交付，则将该调用视为成功。如果密钥重复，请提供其他密钥。
`422`	request body 未通过验证，例如下面的 `activations_limit` 小于 1，或密钥长度超过 255 个字符。	修正字段并重试。

对于 timeout 和 5xx responses 等 transient errors，履行操作可以安全重试。每个 grant 只能履行一次，因此在调用成功但未收到确认后重试，会返回 409，而不会签发第二个密钥或发送重复 email。使用 grant 的 id 作为 idempotency key。

验证流程

要端到端测试此流程：

在 test mode 中购买 product。请参阅 checkout guides。
确认 webhook 收到了包含 status: "Pending" 和 integration_type: "license_key" 的 entitlement_grant.created，或者 grant 出现在按 status=Pending 筛选的 List Grants response 中。
使用 test key 调用 fulfill endpoint。
确认 response 显示 status: "Delivered"，且 license_key 已填充；同时确认客户收到 key email，并且 entitlement_grant.delivered 被触发。

密钥交付后，客户可以像使用自动生成的密钥一样，通过 public license endpoints 对其进行激活和验证。

Create Entitlement

使用 fulfillment_mode: manual 创建 License Key entitlement。

List Grants

按 status 和 customer_id 筛选，以查找 pending grants。

Fulfill License Key Grant

交付密钥值，并将 grant 移至 Delivered。

Entitlement Grant Webhooks

用于表示 pending 和 delivered grants 的 entitlement_grant.* events。

Integration Guides

Billing Deconstructions

Cookbooks

License Keys Overview

Fulfill License Key Grant API

工作原理

前提条件

步骤 1 — 在手动模式下创建 License Key Entitlement

步骤 2 — 将 Entitlement 附加到 Product

步骤 3 — 检测 Pending Grants

监听 Webhook

或轮询 List Grants API

步骤 4 — 交付密钥

Request Fields

步骤 5 — 处理错误和重试

验证流程

相关 API Reference

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys Overview

Fulfill License Key Grant API

​工作原理

​前提条件

​步骤 1 — 在手动模式下创建 License Key Entitlement

​步骤 2 — 将 Entitlement 附加到 Product

​步骤 3 — 检测 Pending Grants

​监听 Webhook

​或轮询 List Grants API

​步骤 4 — 交付密钥

​Request Fields

​步骤 5 — 处理错误和重试

​验证流程

​相关 API Reference

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

工作原理

前提条件

步骤 1 — 在手动模式下创建 License Key Entitlement

步骤 2 — 将 Entitlement 附加到 Product

步骤 3 — 检测 Pending Grants

监听 Webhook

或轮询 List Grants API

步骤 4 — 交付密钥

Request Fields

步骤 5 — 处理错误和重试

验证流程

相关 API Reference