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 merchant Dodo Payments.
• API key, yang dibuat di Developer → API Keys dan disimpan di DODO_PAYMENTS_API_KEY, serta webhook signing secret dari Developer → Webhooks, yang disimpan di DODO_PAYMENTS_WEBHOOK_KEY. Lihat panduan pembuatan API key.
• Endpoint backend yang dapat menerima webhook.

​

Langkah 1 — Buat Entitlement License Key dalam Mode Manual

• Dashboard
• API

1

Open Entitlements

Buka Entitlements di dashboard, lalu klik + untuk membuat entitlement.

2

Choose License Key

Pilih License Keys dan masukkan Name. Formulir ini memiliki kolom berikut:

• Fulfillment Mode: secara default Automatic. Pengaturan ini mengaktifkan pemenuhan manual, dan Anda akan mengubahnya pada langkah berikutnya.
• License Length: berapa lama setiap key yang diterbitkan tetap valid, atau No expiration.
• Activations Limit: jumlah maksimum aktivasi per key, atau Unlimited.
• Activation Message: pesan opsional untuk pelanggan yang ditampilkan saat pelanggan mengaktifkan key dan disertakan dalam email license key.

3

Set Fulfillment Mode to Manual

Buka dropdown Fulfillment Mode dan ubah dari Automatic menjadi Manual. Pengaturan ini diperlukan untuk seluruh panduan: tanpa pengaturan ini, Dodo Payments membuat dan mengirimkan key secara otomatis serta tidak membuat grant yang tertunda. Dengan Manual dipilih, setiap pembelian membuat grant Pending untuk Anda penuhi. Klik Create Entitlement untuk menyimpan.

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

See all 19 lines

​

Langkah 2 — Lampirkan Entitlement ke Produk

​

Langkah 3 — Deteksi Grant yang Tertunda

​

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

​

Atau Lakukan Polling pada 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"

​

Langkah 4 — Kirimkan 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"
  }'

​

Kolom Request

​

Langkah 5 — Tangani Error dan Percobaan Ulang

​

Verifikasi Alur

1. Beli produk dalam test mode. Lihat panduan checkout.
2. Pastikan webhook Anda menerima entitlement_grant.created dengan status: "Pending" dan integration_type: "license_key", atau pastikan grant muncul dalam respons List Grants yang difilter berdasarkan status=Pending.
3. Panggil endpoint fulfill dengan test key.
4. Pastikan respons menampilkan status: "Delivered" dengan license_key yang terisi, pelanggan menerima email key, dan entitlement_grant.delivered dipicu.

​

Referensi API Terkait