Panduan Integrasi Pemenuhan Kunci Lisensi Manual

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

​

Cara Kerjanya

​

Prasyarat

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

​

Langkah 1 — Buat Hak Kunci Lisensi dalam Mode Manual

• Dashboard
• API

1

Open Entitlements

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

2

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.

3

Set Fulfillment Mode to Manual

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

Buat hak dengan integration_config.fulfillment_mode diatur ke 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_...

​

Langkah 2 — Pasang Hak ke Produk

​

Langkah 3 — Deteksi Grant yang Tertunda

​

Dengarkan untuk webhook

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

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

​

Langkah 4 — Kirim Kunci

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

​

Langkah 5 — Tangani Kesalahan dan Pengulangan

​

Verifikasi Alur

1. Beli produk dalam mode pengujian (lihat panduan checkout).
2. 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.
3. Panggil endpoint pemenuhan dengan kunci pengujian.
4. Konfirmasi tanggapan menunjukkan status: "delivered" dengan license_key yang terisi, pelanggan menerima email kunci, dan entitlement_grant.delivered menembak.

​

Referensi API Terkait