Guide d'intégration pour le traitement manuel des clés de licence

• Un produit avec un droit de clé de licence défini pour le traitement manual.
• Un écouteur de webhook qui détecte quand un client attend une clé.
• Un appel de traitement qui délivre la clé et notifie automatiquement le client.

​

Fonctionnement

​

Prérequis

• Un compte marchand Dodo Payments.
• Votre clé API (DODO_PAYMENTS_API_KEY) et la clé secrète de votre webhook depuis le tableau de bord. Consultez le guide de génération de clé API.
• Un endpoint backend pouvant recevoir des webhooks.

​

Étape 1 — Créer un droit de clé de licence en mode manuel

• Dashboard
• API

1

Open Entitlements

Allez dans Droits sur votre tableau de bord et cliquez sur + pour créer un nouveau droit.

2

Choose License Key

Sélectionnez Clé de licence comme intégration et donnez-lui un Nom. Le formulaire expose ces champs :

• Mode de traitement — Automatic par défaut. C’est le paramètre qui permet le traitement manuel ; vous le changez à l’étape suivante.
• Durée de la licence — combien de temps chaque clé délivrée reste valable, ou Pas d’expiration.
• Limite d’activations — nombre maximum d’activations par clé, ou Illimité.
• Message d’activation — message optionnel destiné au client qui s’affiche lors de l’activation de la clé.

3

Set Fulfillment Mode to Manual

Ouvrez le menu déroulant Mode de traitement et changez-le de Automatique à Manuel. C’est le paramètre qui pilote tout ce guide — sans cela, les clés sont générées et envoyées automatiquement par email et aucun droit en attente n’est créé. Avec Manuel sélectionné, chaque achat crée un droit pending que vous devez traiter. Cliquez sur Créer le droit pour enregistrer.

Créez le droit avec integration_config.fulfillment_mode défini à 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_...

​

Étape 2 — Attacher le droit à un produit

​

Étape 3 — Détecter les droits en attente

​

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

​

Ou interroger l’API Liste des droits

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

​

Étape 4 — Délivrer la clé

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

​

Champs de demande

​

Étape 5 — Gérer les erreurs et les réessais

​

Vérifier le flux

1. Achetez le produit en mode test (voir les guides de check-out).
2. Confirmez que votre webhook a reçu entitlement_grant.created avec status: "pending" et integration_type: "license_key", ou que le droit apparaît dans la réponse de Liste des droits avec ces filtres.
3. Appelez l’endpoint de traitement avec une clé de test.
4. Confirmez que la réponse montre status: "delivered" avec un license_key rempli, que le client reçoit l’email de la clé, et entitlement_grant.delivered est déclenché.

​

Référence API associée