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.
• Une clé API, créée sous Developer → API Keys et stockée dans DODO_PAYMENTS_API_KEY, ainsi que le secret de signature des webhooks disponible sous Developer → Webhooks, stocké dans DODO_PAYMENTS_WEBHOOK_KEY. Consultez le guide de génération de clé API.
• Un endpoint backend capable de recevoir des webhooks.

​

Étape 1 — Créer un entitlement License Key en mode manuel

• Dashboard
• API

1

Open Entitlements

Accédez à Entitlements dans le dashboard et cliquez sur + pour créer un entitlement.

2

Choose License Key

Sélectionnez License Keys et saisissez un Name. Le formulaire contient les champs suivants :

• Fulfillment Mode : Automatic par défaut. C’est le paramètre qui active le fulfillment manuel ; vous le modifierez à l’étape suivante.
• License Length : durée de validité de chaque clé émise, ou No expiration.
• Activations Limit : nombre maximal d’activations par clé, ou Unlimited.
• Activation Message : message facultatif destiné au client, affiché lorsque celui-ci active la clé et inclus dans l’e-mail contenant la clé de licence.

3

Set Fulfillment Mode to Manual

Ouvrez la liste déroulante Fulfillment Mode et remplacez Automatic par Manual. Le reste de ce guide dépend de ce paramètre : sans lui, Dodo Payments génère et envoie automatiquement les clés par e-mail et ne crée aucun grant en attente. Lorsque Manual est sélectionné, chaque achat crée un grant Pending que vous devez traiter. Cliquez sur Create Entitlement pour enregistrer.

Créez l’entitlement avec integration_config.fulfillment_mode défini sur 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

​

Étape 2 — Associer l’entitlement à un produit

​

Étape 3 — Détecter les grants en attente

​

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

​

Ou interroger la List Grants API

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

​

Étape 4 — Transmettre 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"
}

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

​

Champs de la requête

​

Étape 5 — Gérer les erreurs et les nouvelles tentatives

​

Vérifier le flux

1. Achetez le produit en mode test. Consultez les guides de checkout.
2. 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 List Grants filtrée par status=Pending.
3. Appelez l’endpoint de fulfillment avec une clé de test.
4. 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