Manual License Key Fulfillment Integration Guide

• A product with a License Key entitlement set to manual fulfillment.
• A webhook listener that detects when a customer is waiting for a key.
• A fulfillment call that delivers the key and notifies the customer automatically.

​

How It Works

​

Điều kiện tiên quyết

• Tài khoản merchant Dodo Payments.
• API key được tạo trong Developer → API Keys và lưu trong DODO_PAYMENTS_API_KEY, cùng webhook signing secret từ Developer → Webhooks, được lưu trong DODO_PAYMENTS_WEBHOOK_KEY. Xem hướng dẫn tạo API key.
• Một backend endpoint có thể nhận webhook.

​

Bước 1 — Tạo entitlement License Key ở chế độ thủ công

• Dashboard
• API

1

Open Entitlements

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

2

Choose License Key

Chọn License Keys và nhập Name. Biểu mẫu có các trường sau:

• Fulfillment Mode: mặc định là Automatic. Đây là thiết lập bật fulfillment thủ công và bạn sẽ thay đổi thiết lập này ở bước tiếp theo.
• License Length: thời gian mỗi key được cấp còn hiệu lực, hoặc No expiration.
• Activations Limit: số lần kích hoạt tối đa cho mỗi key, hoặc Unlimited.
• Activation Message: thông báo tùy chọn hiển thị cho khách hàng khi họ kích hoạt key và được đưa vào email license key.

3

Set Fulfillment Mode to Manual

Mở menu thả xuống Fulfillment Mode và chuyển từ Automatic sang Manual. Phần còn lại của hướng dẫn này phụ thuộc vào thiết lập này: nếu không có thiết lập này, Dodo Payments sẽ tự động tạo và gửi key qua email, đồng thời không tạo grant đang chờ xử lý. Khi chọn Manual, mỗi giao dịch mua sẽ tạo một grant Pending để bạn xử lý. Nhấp Create Entitlement để lưu.

Tạo entitlement với integration_config.fulfillment_mode được đặt thành manual.

Node.js

Python

cURL

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_...

See all 19 lines

​

Bước 2 — Gắn entitlement vào sản phẩm

​

Bước 3 — Phát hiện grant đang chờ xử lý

​

Lắng nghe webhook

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

​

Hoặc Poll API List Grants

// 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"

​

Bước 4 — Cung cấp 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"
  }'

​

Các trường request

​

Bước 5 — Xử lý lỗi và retry

​

Xác minh quy trình

1. Mua sản phẩm trong test mode. Xem các hướng dẫn checkout.
2. Xác nhận webhook của bạn đã nhận entitlement_grant.created cùng với status: "Pending" và integration_type: "license_key", hoặc grant xuất hiện trong response List Grants được lọc theo status=Pending.
3. Gọi fulfill endpoint với một test key.
4. Xác nhận response hiển thị status: "Delivered" cùng license_key đã được điền, khách hàng nhận được email chứa key và entitlement_grant.delivered được phát ra.

​

Tài liệu tham khảo API liên quan