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

​

사전 요구 사항

• 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를 참고하세요.
• webhook을 수신할 수 있는 backend endpoint.

​

1단계 — Manual Mode로 License Key Entitlement 만들기

• Dashboard
• API

1

Open Entitlements

Dashboard에서 Entitlements로 이동하고 **+**를 클릭하여 entitlement를 만드세요.

2

Choose License Key

License Keys를 선택하고 Name을 입력하세요. 양식에는 다음 필드가 있습니다.

• Fulfillment Mode: 기본값은 Automatic입니다. 이 설정으로 수동 fulfillment를 활성화하며, 다음 단계에서 변경합니다.
• License Length: 발급된 각 키가 유효한 기간 또는 No expiration.
• Activations Limit: 키당 허용되는 최대 activation 수 또는 Unlimited.
• Activation Message: 고객이 키를 activation할 때 표시되고 license key email에 포함되는 선택적 고객용 메시지.

3

Set Fulfillment Mode to Manual

Fulfillment Mode dropdown을 열고 Automatic에서 Manual로 변경하세요. 이 가이드의 나머지 과정은 이 설정에 따라 달라집니다. 이 설정이 없으면 Dodo Payments가 키를 자동으로 생성하고 이메일로 보내며, 처리 대기 중인 grant를 생성하지 않습니다. Manual을 선택하면 구매할 때마다 사용자가 fulfillment해야 하는 Pending grant가 생성됩니다. Create Entitlement을 클릭하여 저장하세요.

integration_config.fulfillment_mode를 manual로 설정하여 entitlement를 만드세요.

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

​

2단계 — Entitlement를 Product에 연결하기

​

3단계 — 처리 대기 중인 Grant 감지하기

​

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

​

또는 List Grants API Polling

// 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단계 — 키 전달하기

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

​

5단계 — 오류 및 재시도 처리

​

Flow 확인하기

1. test mode에서 product를 구매하세요. checkout guides를 참고하세요.
2. webhook이 status: "Pending" 및 integration_type: "license_key"와 함께 entitlement_grant.created를 수신했는지 확인하거나, status=Pending로 필터링한 List Grants response에 grant가 표시되는지 확인하세요.
3. test key를 사용하여 fulfill endpoint를 호출하세요.
4. response에 채워진 license_key와 함께 status: "Delivered"가 표시되는지, 고객이 key email을 수신하는지, entitlement_grant.delivered가 발생하는지 확인하세요.

​

관련 API Reference