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

Ce guide explique de bout en bout comment créer un système de distribution manuelle de clés de licence. Au lieu que Dodo Payments génère automatiquement une clé lors du paiement, chaque achat crée un grant Pending et attend que vous fournissiez la valeur de la clé depuis votre propre système, un fournisseur tiers ou un stock limité de codes. À la fin, vous aurez :

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.

License Keys overview

Le cycle de vie complet des clés de licence et le paramètre fulfillment_mode.

Fulfill License Key Grant API

Référence API pour l’endpoint que vous appelez pour délivrer une clé.

Fonctionnement

Le traitement manuel ne modifie que l’étape d’émission. L’activation, la validation, la désactivation, l’expiration et la révocation fonctionnent exactement comme une clé générée automatiquement une fois délivrée.

Prérequis

Pour suivre ce guide, vous aurez besoin de :

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.

Utilisez https://test.dodopayments.com et des identifiants de mode test pendant la création. Passez à https://live.dodopayments.com et des clés actives lorsque vous passez en production.

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

Un droit est une définition réutilisable de ce que vous livrez. Créez un droit de clé de licence et définissez son fulfillment_mode à manual.

Dashboard
API

Open Entitlements

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

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

New License Key entitlement form with name, fulfillment mode, license length, activations limit, and activation message

Set Fulfillment Mode to Manual

Ouvrez la liste déroulante Fulfillment Mode et remplacez Automatic par Manual. C’est le paramètre qui régit l’ensemble de ce guide : sans lui, les clés sont générées et envoyées automatiquement par e-mail, et aucun grant en attente n’est créé. Avec Manual sélectionné, chaque achat crée un grant Pending que vous devez traiter. Cliquez sur Create Entitlement pour enregistrer.

Créez le droit avec integration_config.fulfillment_mode défini à 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 a pour valeur par défaut auto. L’omettre, ou laisser un droit existant inchangé, maintient le comportement automatique. Seuls les droits explicitement définis à manual créent des droits en attente.

Étape 2 — Attacher le droit à un produit

Ouvrez le produit que vous souhaitez vendre, développez Paramètres avancés → Droits & Crédits, et sélectionnez le droit de clé de licence que vous avez défini en Manuel à l’étape 1. Un seul produit peut délivrer cette clé de licence en plus d’autres droits sur le même achat.

Panneau des droits du produit avec la clé de licence sélectionnée — Selecting the License Key entitlement in the product entitlements panel.

Le mode de traitement est une propriété du droit, pas du produit. Parce que vous l’avez défini en Manuel à l’étape 1, chaque produit auquel ce droit est attaché crée des droits de clé de licence pending à l’achat — il n’y a rien d’autre à configurer ici.

Le mode de distribution est une propriété de l’entitlement, et non du produit. Comme vous l’avez défini sur Manual à l’étape 1, chaque produit auquel cet entitlement est associé crée des grants de clés de licence Pending lors de l’achat — aucune configuration supplémentaire n’est nécessaire ici.

Étape 3 — Détecter les droits en attente

Lorsqu’un client achète le produit, Dodo Payments crée un droit au statut pending sans clé attachée et déclenche un webhook entitlement_grant.created. C’est votre signal qu’un client attend une clé. Lorsqu’un client achète le produit, Dodo Payments crée un grant avec le statut Pending, sans clé associée, et déclenche un webhook entitlement_grant.created. C’est le signal indiquant qu’un client attend une clé. Configurez un endpoint de webhook (Développeur → Webhooks dans le tableau de bord) et agissez sur les droits de clé de licence en attente. La mise en œuvre suit la spécification des Webhooks standard.

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

Ou interroger l’API Liste des droits

Si vous préférez ne pas vous fier aux webhooks, listez les droits pour le droit et filtrez par integration_type et status : Si vous préférez ne pas vous fier aux webhooks, listez les autorisations pour votre droit de Clé de Licence et filtrez par status. Chaque autorisation sur un droit de Clé de Licence est déjà une autorisation de clé de licence, donc aucun filtre integration_type n’est nécessaire :

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"

Étape 4 — Délivrer la clé

Obtenez la valeur de la clé depuis votre propre système, puis soumettez-la avec l’endpoint Traitement du droit de clé de licence. Cela nécessite votre clé API secrète (Permission Éditeur) ; ce n’est pas l’un des endpoints de licence publique.

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

Champs de demande

string

requis

La chaîne de clé de licence à délivrer au client. Les espaces sont coupés ; une valeur vide ou composée uniquement d’espaces est rejetée.

integer

Limite d’activation par clé. Retombe sur la configuration du droit lorsque omise.

string

Expiration par clé (ISO 8601). Retombe sur la durée de configuration du droit lorsque omise. Pour les droits délivrés par abonnement, la validité reste liée à l’abonnement indépendamment.

En cas de succès, le droit passe à delivered, le client reçoit automatiquement la clé (le même email qu’il recevrait en traitement automatique), et entitlement_grant.delivered est déclenché. En cas de succès, le grant passe à l’état Delivered, la clé est automatiquement envoyée au client (dans le même e-mail que celui qu’il aurait reçu avec la distribution automatique), et les événements webhook license_key.created et entitlement_grant.delivered sont déclenchés.

Email clé de licence client montrant la clé, produit, limite d'activation, expiration et instructions d'activation — The license key email the customer receives once you fulfill the grant.

Vous n’avez pas besoin d’envoyer vous-même la clé par email — la livraison se fait automatiquement lorsque le droit est rempli.

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

L’endpoint valide le droit avant de délivrer quoi que ce soit. Gérez ces réponses :

Statut	Signification	Que faire
`200`	Clé délivrée, le droit est désormais `delivered`.	Terminé.
`400`	Pas un droit de clé de licence, ou la clé est vide/espace.	Corrigez la demande ; ne réessayez pas telle quelle.
`404`	Aucun droit avec cet ID pour votre entreprise.	Vérifiez le `grant_id`.
`409`	Droit non en attente de traitement (déjà délivré ou ayant déjà une clé), ou la valeur de la clé existe déjà.	Si déjà délivré, traiter comme succès. Si une clé en double, fournir une clé différente.
`422`	Le corps de la demande n’a pas passé la validation (e.g. `activations_limit < 1`).	Corrigez le champ et réessayez.

Status	Meaning	What to do
`200`	Clé envoyée, le grant est maintenant `Delivered`.	Terminé.
`400`	Ce n’est pas un grant de clé de licence, ou la clé est vide/ne contient que des espaces.	Corrigez la requête ; ne la réessayez pas telle quelle.
`404`	Aucun grant avec cet ID pour votre entreprise.	Vérifiez le `grant_id`.
`409`	Le grant n’attend pas de traitement (il a déjà été livré ou possède déjà une clé), ou la valeur de la clé existe déjà.	S’il a déjà été livré, considérez l’opération comme réussie. S’il s’agit d’une clé en double, fournissez une autre clé.
`422`	Le corps de la requête n’a pas passé la validation (par exemple, `activations_limit < 1`).	Corrigez le champ et réessayez.

Vérifier le flux

Achetez le produit en mode test (voir les guides de check-out).
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.
Appelez l’endpoint de traitement avec une clé de test.
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é.
Achetez le produit en mode test (consultez les guides de checkout).
Vérifiez que votre webhook a reçu entitlement_grant.created avec status: "Pending" et integration_type: "license_key", ou que le grant apparaît dans la réponse de List Grants avec ces filtres.
Appelez l’endpoint de fulfillment avec une clé de test.
Vérifiez que la réponse affiche status: "Delivered" avec un license_key renseigné, que le client reçoit l’e-mail contenant la clé et que entitlement_grant.delivered est déclenché.

Référence API associée

Create Entitlement

Créez le droit de clé de licence avec fulfillment_mode: manual.

List Grants

Filtrez par integration_type et status pour trouver les droits en attente.

Fulfill License Key Grant

Délivrez la valeur de la clé et passez le droit à livré.

Entitlement Grant Webhooks

Les événements entitlement_grant.* qui signalent les droits en attente et délivrés.

Create Entitlement

Créez l’entitlement License Key avec fulfillment_mode: manual.

List Grants

Filtrez par status et customer_id pour trouver les grants en attente.

Fulfill License Key Grant

Fournissez la valeur de la clé et faites passer le grant à l’état livré.

Entitlement Grant Webhooks

Les événements entitlement_grant.* qui signalent les grants en attente et livrés.

Integration Guides

Billing Deconstructions

Cookbooks

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

License Keys overview

Fulfill License Key Grant API

Fonctionnement

Prérequis

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

Étape 2 — Attacher le droit à un produit

Étape 3 — Détecter les droits en attente

Ou interroger l’API Liste des droits

Étape 4 — Délivrer la clé

Champs de demande

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

Vérifier le flux

Référence API associée

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

​Fonctionnement

​Prérequis

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

​Étape 2 — Attacher le droit à un produit

​Étape 3 — Détecter les droits en attente

​Ou interroger l’API Liste des droits

​Étape 4 — Délivrer la clé

​Champs de demande

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

​Vérifier le flux

​Référence API associée

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Fonctionnement

Prérequis

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

Étape 2 — Attacher le droit à un produit

Étape 3 — Détecter les droits en attente

Ou interroger l’API Liste des droits

Étape 4 — Délivrer la clé

Champs de demande

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

Vérifier le flux

Référence API associée