Panduan Integrasi Pemenuhan Kunci Lisensi Manual

Panduan ini membahas cara membangun sistem pemenuhan kunci lisensi manual secara menyeluruh. Alih-alih Dodo Payments membuat kunci secara otomatis saat pembayaran, setiap pembelian membuat grant Pending dan menunggu Anda memasukkan nilai kunci dari sistem Anda sendiri, vendor pihak ketiga, atau kumpulan kode yang terbatas. Pada akhirnya Anda akan memiliki:

Produk dengan hak Kunci Lisensi yang diatur ke pemenuhan manual.
Sebuah webhook listener yang mendeteksi ketika pelanggan menunggu kunci.
Panggilan pemenuhan yang mengirim kunci dan memberi tahu pelanggan secara otomatis.

License Keys overview

Siklus hidup kunci lisensi lengkap dan pengaturan fulfillment_mode.

Fulfill License Key Grant API

Referensi API untuk endpoint yang Anda panggil untuk mengirim kunci.

Cara Kerjanya

Pemenuhan manual hanya mengubah langkah penerbitan. Aktivasi, validasi, deaktivasi, kadaluarsa, dan pencabutan berperilaku persis seperti kunci yang dihasilkan secara otomatis setelah dikirimkan.

Prasyarat

Untuk mengikuti panduan ini Anda memerlukan:

Akun pedagang Dodo Payments.
Kunci API Anda (DODO_PAYMENTS_API_KEY) dan kunci rahasia webhook dari dashboard. Lihat panduan pembuatan kunci API.
Sebuah endpoint backend yang dapat menerima webhooks.

Gunakan https://test.dodopayments.com dan kredensial test-mode saat membangun. Beralih ke https://live.dodopayments.com dan kunci live saat Anda masuk ke produksi.

Langkah 1 — Buat Hak Kunci Lisensi dalam Mode Manual

Sebuah hak adalah definisi yang dapat digunakan kembali dari apa yang Anda kirim. Buat hak Kunci Lisensi dan atur fulfillment_mode ke manual.

Dashboard
API

Open Entitlements

Pergi ke Hak di dashboard Anda dan klik + untuk membuat hak baru.

Choose License Key

Pilih License Key sebagai integrasi dan berikan Nama. Formulirnya menampilkan bidang berikut:

Fulfillment Mode — Automatic secara default. Ini adalah pengaturan yang memungkinkan pemenuhan manual; Anda mengubahnya di langkah berikutnya.
Panjang Lisensi — berapa lama setiap kunci yang diterbitkan tetap valid, atau Tanpa kadaluarsa.
Batas Aktivasi — maksimum aktivasi per kunci, atau Tak terbatas.
Pesan Aktivasi — pesan opsional yang ditampilkan kepada pelanggan ketika mereka mengaktifkan kunci.

Form entitlement New License Key dengan nama, mode fulfillment, durasi lisensi, batas aktivasi, dan pesan aktivasi

Set Fulfillment Mode to Manual

Buka dropdown Fulfillment Mode dan ubah dari Automatic menjadi Manual. Ini adalah pengaturan yang menggerakkan seluruh panduan ini — tanpanya, kunci dibuat dan dikirim melalui email secara otomatis dan tidak ada grant tertunda yang dibuat. Setelah Manual dipilih, setiap pembelian membuat grant Pending untuk Anda penuhi. Klik Create Entitlement untuk menyimpan.

Buat hak dengan integration_config.fulfillment_mode diatur ke manual.

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 default ke auto. Mengabaikannya, atau membiarkan hak yang ada tidak berubah, mempertahankan perilaku otomatis. Hanya hak yang secara eksplisit diatur ke manual yang membuat grant yang tertunda.

Langkah 2 — Pasang Hak ke Produk

Buka produk yang ingin Anda jual, perluas Pengaturan Lanjutan → Hak & Kredit, dan pilih Hak Kunci Lisensi yang Anda atur ke Manual di Langkah 1. Satu produk dapat menyediakan kunci lisensi ini bersama hak lain pada pembelian yang sama.

Panel hak produk dengan Kunci Lisensi yang dipilih — Selecting the License Key entitlement in the product entitlements panel.

Fulfillment mode adalah properti dari hak, bukan produk. Karena Anda mengaturnya ke Manual di Langkah 1, setiap produk yang terpasang pada hak ini menciptakan grant lisensi-kunci pending saat pembelian — tidak ada yang perlu dikonfigurasi di sini.

Fulfillment mode adalah properti entitlement, bukan produk. Karena Anda menetapkannya ke Manual pada Langkah 1, setiap produk yang dikaitkan dengan entitlement ini akan membuat grant kunci lisensi Pending saat pembelian — tidak ada konfigurasi tambahan yang diperlukan di sini.

Langkah 3 — Deteksi Grant yang Tertunda

Ketika pelanggan membeli produk, Dodo Payments membuat grant dalam status pending dengan tidak ada kunci terlampir dan menembakkan webhook entitlement_grant.created. Ini adalah sinyal Anda bahwa pelanggan menunggu kunci. Saat pelanggan membeli produk, Dodo Payments membuat grant berstatus Pending tanpa kunci terlampir dan memicu webhook entitlement_grant.created. Ini adalah sinyal bahwa pelanggan sedang menunggu kunci. Siapkan endpoint webhook (Pengembang → Webhook di dashboard) dan bertindaklah pada grant lisensi-kunci yang tertunda. Implementasinya mengikuti spesifikasi Standard Webhooks.

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_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'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.DODO_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'
  ) {
    await queueLicenseKeyFulfillment({
      grantId: event.data.id,
      customerId: event.data.customer_id,
    });
  }

  return new Response('ok');
}

Atau polling API List Grants

Jika Anda lebih memilih untuk tidak bergantung pada webhooks, daftar grant untuk hak dan filter berdasarkan integration_type dan status: Jika Anda lebih suka tidak mengandalkan webhook, daftarkan hibah untuk hak License Key Anda dan saring berdasarkan status. Setiap hibah pada hak License Key sudah merupakan hibah license-key, jadi tidak diperlukan saringan integration_type:

Node.js

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

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

Node.js

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

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

Langkah 4 — Kirim Kunci

Dapatkan nilai kunci dari sistem Anda sendiri, lalu kirimkan dengan endpoint Fulfill License Key Grant. Ini memerlukan kunci API rahasia Anda (Izin Editor); ini bukan salah satu dari endpoint lisensi publik.

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

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

Bidang Permintaan

string

wajib

String kunci lisensi untuk dikirim ke pelanggan. Spasi dikurangi; nilai kosong atau hanya spasi ditolak.

integer

Batas aktivasi per kunci. Kembali ke konfigurasi hak jika tidak diisi.

string

Kadaluarsa per kunci (ISO 8601). Kembali ke durasi konfigurasi hak jika tidak diisi. Untuk grant yang diterbitkan langganan, validitas tetap terkait dengan langganan terlepas apapun.

Pada keberhasilan, grant berpindah ke delivered, pelanggan dikirim kunci secara otomatis (email yang sama yang akan mereka terima di bawah pemenuhan otomatis), dan entitlement_grant.delivered menembak. Setelah berhasil, grant berpindah ke Delivered, pelanggan dikirimi kunci secara otomatis (email yang sama seperti yang akan mereka terima dalam pemenuhan otomatis), dan event webhook license_key.created serta entitlement_grant.delivered dipicu.

Email kunci lisensi pelanggan yang menunjukkan kunci, produk, batas aktivasi, kadaluarsa, dan instruksi aktivasi — The license key email the customer receives once you fulfill the grant.

Anda tidak perlu mengirim email kunci sendiri — pengiriman terjadi secara otomatis ketika grant dipenuhi.

Langkah 5 — Tangani Kesalahan dan Pengulangan

Endpoint memvalidasi grant sebelum mengirimkan apapun. Tangani tanggapan berikut:

Status	Arti	Apa yang harus dilakukan
`200`	Kunci terkirim, grant sekarang `delivered`.	Selesai.
`400`	Bukan grant kunci-lisensi, atau kuncinya kosong/hanya spasi.	Perbaiki permintaan; jangan coba lagi sebagaimana adanya.
`404`	Tidak ada grant dengan ID tersebut untuk bisnis Anda.	Verifikasi `grant_id`.
`409`	Grant tidak menunggu pemenuhan (sudah terkirim atau sudah memiliki kunci), atau nilai kunci sudah ada.	Jika sudah dikirim, perlakukan sebagai keberhasilan. Jika duplikat kunci, berikan kunci yang berbeda.
`422`	Body permintaan gagal validasi (mis. `activations_limit < 1`).	Koreksi bidang dan coba lagi.

Status	Arti	Tindakan yang harus dilakukan
`200`	Kunci telah dikirim, grant sekarang berstatus `Delivered`.	Selesai.
`400`	Bukan grant kunci lisensi, atau kuncinya kosong/berisi spasi.	Perbaiki request; jangan retry apa adanya.
`404`	Tidak ada grant dengan ID tersebut untuk bisnis Anda.	Verifikasi `grant_id`.
`409`	Grant tidak sedang menunggu fulfillment (sudah dikirim atau sudah memiliki kunci), atau nilai kunci tersebut sudah ada.	Jika sudah dikirim, anggap sebagai berhasil. Jika kunci duplikat, berikan kunci yang berbeda.
`422`	Body request gagal divalidasi (misalnya `activations_limit < 1`).	Perbaiki field tersebut dan lakukan retry.

Verifikasi Alur

Beli produk dalam mode pengujian (lihat panduan checkout).
Konfirmasi webhook Anda menerima entitlement_grant.created dengan status: "pending" dan integration_type: "license_key", atau bahwa grant muncul dalam respons List Grants dengan filter tersebut.
Panggil endpoint pemenuhan dengan kunci pengujian.
Konfirmasi tanggapan menunjukkan status: "delivered" dengan license_key yang terisi, pelanggan menerima email kunci, dan entitlement_grant.delivered menembak.
Beli produk dalam test mode (lihat panduan checkout).
Pastikan webhook Anda menerima entitlement_grant.created dengan status: "Pending" dan integration_type: "license_key", atau pastikan grant muncul dalam respons List Grants dengan filter tersebut.
Panggil endpoint fulfill dengan kunci pengujian.
Pastikan respons menampilkan status: "Delivered" dengan license_key yang terisi, pelanggan menerima email berisi kunci, dan entitlement_grant.delivered dipicu.

Referensi API Terkait

Create Entitlement

Buat hak Kunci Lisensi dengan fulfillment_mode: manual.

List Grants

Filter berdasarkan integration_type dan status untuk menemukan grant yang pending.

Fulfill License Key Grant

Kirim nilai kunci dan transisikan grant ke terkirim.

Entitlement Grant Webhooks

Acara entitlement_grant.* yang menandakan grant yang tertunda dan terkirim.

Create Entitlement

Buat entitlement License Key dengan fulfillment_mode: manual.

List Grants

Filter berdasarkan status dan customer_id untuk menemukan grant yang tertunda.

Fulfill License Key Grant

Kirimkan nilai kunci dan ubah status grant menjadi delivered.

Entitlement Grant Webhooks

Event entitlement_grant.* yang menandakan grant tertunda dan terkirim.

Integration Guides

Billing Deconstructions

Cookbooks

Panduan Integrasi Pemenuhan Kunci Lisensi Manual

License Keys overview

Fulfill License Key Grant API

Cara Kerjanya

Prasyarat

Langkah 1 — Buat Hak Kunci Lisensi dalam Mode Manual

Langkah 2 — Pasang Hak ke Produk

Langkah 3 — Deteksi Grant yang Tertunda

Atau polling API List Grants

Langkah 4 — Kirim Kunci

Bidang Permintaan

Langkah 5 — Tangani Kesalahan dan Pengulangan

Verifikasi Alur

Referensi API Terkait

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

License Keys overview

Fulfill License Key Grant API

​Cara Kerjanya

​Prasyarat

​Langkah 1 — Buat Hak Kunci Lisensi dalam Mode Manual

​Langkah 2 — Pasang Hak ke Produk

​Langkah 3 — Deteksi Grant yang Tertunda

​Atau polling API List Grants

​Langkah 4 — Kirim Kunci

​Bidang Permintaan

​Langkah 5 — Tangani Kesalahan dan Pengulangan

​Verifikasi Alur

​Referensi API Terkait

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Cara Kerjanya

Prasyarat

Langkah 1 — Buat Hak Kunci Lisensi dalam Mode Manual

Langkah 2 — Pasang Hak ke Produk

Langkah 3 — Deteksi Grant yang Tertunda

Atau polling API List Grants

Langkah 4 — Kirim Kunci

Bidang Permintaan

Langkah 5 — Tangani Kesalahan dan Pengulangan

Verifikasi Alur

Referensi API Terkait