Integrationsguide för manuell leverans av licensnycklar

Den här guiden går igenom hur du bygger ett system för manuell leverans av licensnycklar från början till slut. I stället för att Dodo Payments automatiskt genererar en nyckel vid betalning skapar varje köp en Pending grant och väntar på att du ska ange nyckelvärdet från ditt eget system, en tredjepartsleverantör eller en begränsad pool av koder. När du är klar kommer du att ha:

En produkt med rättigheter för licensnyckel inställd till manual leverans.
En webhook-lyssnare som detekterar när en kund väntar på en nyckel.
Ett leveranssamtal som levererar nyckeln och automatiskt meddelar kunden.

License Keys overview

Den fullständiga livscykeln för licensnyckeln och fulfillment_mode-inställningen.

Fulfill License Key Grant API

API-referens för slutpunkten du anropar för att leverera en nyckel.

Hur det fungerar

Manuell leverans ändrar endast utgivningssteget. Aktivering, validering, avaktivering, utgång och återkallande fungerar precis som en auto-genererad nyckel när den väl är levererad.

Förutsättningar

För att följa denna guide behöver du:

Ett Dodo Payments handlarkonto.
Din API-nyckel (DODO_PAYMENTS_API_KEY) och hemlig webhook-nyckel från instrumentpanelen. Se Guiden för API-nyckelgenerering.
En backend-slutpunkt som kan ta emot webhooks.

Använd https://test.dodopayments.com och testläges-uppgifter under byggandet. Byt till https://live.dodopayments.com och live-nycklar när du går till produktion.

Steg 1 — Skapa en rättighet för licensnycklar i manuellt läge

En rättighet är en återanvändbar definition av vad du levererar. Skapa en rättighet för licensnyckel och ställ in dess fulfillment_mode till manual.

Dashboard
API

Open Entitlements

Gå till Rättigheter i din instrumentpanel och klicka på + för att skapa en ny rättighet.

Choose License Key

Välj Licensnyckel som integration och ge den ett Namn. Formuläret exponerar dessa fält:

Leveransläge — Automatic som standard. Detta är inställningen som möjliggör manuell leverans; du ändrar det i nästa steg.
Licensens längd — hur länge varje utfärdad nyckel är giltig, eller Ingen utgång.
Aktiveringsgräns — maximalt antal aktiveringar per nyckel, eller Obegränsat.
Aktiveringsmeddelande — valfritt kundriktat meddelande som visas när de aktiverar nyckeln.

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

Set Fulfillment Mode to Manual

Öppna rullgardinsmenyn Fulfillment Mode och ändra den från Automatic till Manual. Detta är inställningen som styr hela guiden — utan den genereras och skickas nycklar automatiskt via e-post och inget väntande grant skapas. När Manual är valt skapar varje köp ett Pending grant som du ska leverera. Klicka på Create Entitlement för att spara.

Skapa rättigheten med integration_config.fulfillment_mode inställd till 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 standard är auto. Att utelämna det eller lämna en befintlig rättighet oförändrad behåller det automatiska beteendet. Endast rättigheter som explicit är inställda på manual skapar väntande beviljanden.

Steg 2 — Fäst rättigheten till en produkt

Öppna produkten du vill sälja, expandera Avancerade inställningar → Rättigheter & Krediter, och välj Licensnyckelrättigheten du satte till Manuell i Steg 1. En enda produkt kan leverera denna licensnyckel tillsammans med andra rättigheter vid samma köp.

Produktens rättighetspanel med Licensnyckel vald — Selecting the License Key entitlement in the product entitlements panel.

Leveransläge är en egenskap hos rättigheten, inte produkten. Eftersom du satte den till Manuell i Steg 1 skapar varje produkt denna rättighet är fäst vid pending licensnyckel-beviljanden vid köp — det finns inget extra att konfigurera här.

Leveransläget är en egenskap hos entitlement, inte produkten. Eftersom du angav Manual i steg 1 skapar varje produkt som detta entitlement är kopplat till Pending license-key grants vid köp — inget ytterligare behöver konfigureras här.

Steg 3 — Detektera väntande beviljanden

När en kund köper produkten skapar Dodo Payments ett beviljande i pending-status utan nyckel bifogad och skickar en entitlement_grant.created-webhook. Detta är din signal att en kund väntar på en nyckel. När en kund köper produkten skapar Dodo Payments ett grant med statusen Pending, utan någon kopplad nyckel, och skickar en entitlement_grant.created webhook. Detta är din signal om att en kund väntar på en nyckel. Ställ in en webhook-slutpunkt (Utvecklare → Webhooks i instrumentpanelen) och agera på väntande licensnyckel-beviljanden. Implementationen följer specifikationen Standard Webhooks.

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

Eller fråga List Grants API

Om du hellre vill undvika webhooks, lista beviljanden för rättigheten och filtrera efter integration_type och status: Om du hellre inte vill förlita dig på webhooks, lista beviljanden för din License Key-rättighet och filtrera efter status. Varje beviljande på en License Key-rättighet är redan ett licensnyckel-beviljande, så inget integration_type-filter behövs.

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"

Steg 4 — Leverera nyckeln

Hämta nyckelvärdet från ditt eget system och skicka det med Fullgör Licensnyckel-beviljande slutpunkten. Detta kräver din hemliga API-nyckel (Redaktörsbehörighet); det är inte en av de offentliga licens-slutpunkterna.

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

Begär fält

string

obligatorisk

Licensnyckelsträngen som ska levereras till kunden. Mellanslag trimmas; ett tomt eller endast mellanslag-värde avvisas.

integer

Aktiveringsbegränsning per nyckel. Återgår till rättighetskonfigurationen när den utelämnas.

string

Förfallodatum per nyckel (ISO 8601). Återgår till rättighetskonfigurationens varaktighet när den utelämnas. För beviljanden utfärdade av prenumerationer förblir giltigheten kopplad till prenumerationen oavsett.

Vid framgång flyttas beviljandet till delivered, kunden skickas automatiskt nyckeln (samma e-post som de skulle ha fått under automatisk leverans), och entitlement_grant.delivered utlöses. När operationen lyckas övergår grant till Delivered, kunden får nyckeln automatiskt (samma e-postmeddelande som kunden skulle ha fått vid automatisk leverans), och webhook-händelserna license_key.created och entitlement_grant.delivered utlöses.

Kunds licensnyckel e-post som visar nyckeln, produkten, aktiveringsgränsen, utgången och aktiveringsinstruktionerna — The license key email the customer receives once you fulfill the grant.

Du behöver inte skicka nyckeln själv — leverans sker automatiskt när beviljandet fullgörs.

Steg 5 — Hantera fel och omförsökningar

Slutpunkten validerar beviljandet innan något levereras. Hantera dessa svar:

Status	Betydelse	Vad du ska göra
`200`	Nyckel levererad, beviljandet är nu `delivered`.	Klart.
`400`	Inte ett licensnyckel-beviljande, eller nyckeln är tom/mellanslag.	Korrigera begäran; försök inte igen som det är.
`404`	Inget beviljande med det ID för ditt företag.	Verifiera `grant_id`.
`409`	Beviljande väntar inte på leverans (redan levererad eller har redan en nyckel), eller nyckelvärdet finns redan.	Om redan levererad, behandla som framgång. Om det är en duplikerad nyckel, ange en annan nyckel.
`422`	Begär kroppen misslyckades med validering (t.ex. `activations_limit < 1`).	Korrigera fältet och försök igen.

Status	Betydelse	Åtgärd
`200`	Nyckeln har levererats och grant har nu statusen `Delivered`.	Klart.
`400`	Inte ett license-key grant, eller så är nyckeln tom eller består endast av blanksteg.	Korrigera begäran; försök inte igen som den är.
`404`	Det finns inget grant med det ID:t för ditt företag.	Verifiera `grant_id`.
`409`	Grant väntar inte på leverans (har redan levererats eller har redan en nyckel), eller så finns nyckelvärdet redan.	Om den redan har levererats ska du behandla det som en lyckad operation. Om nyckeln är en dubblett anger du en annan nyckel.
`422`	Begärans body klarade inte valideringen (t.ex. `activations_limit < 1`).	Korrigera fältet och försök igen.

Verifiera flödet

Köp produkten i testläge (se checkout-guiderna).
Bekräfta att din webhook tog emot entitlement_grant.created med status: "pending" och integration_type: "license_key", eller att beviljandet dyker upp i List Grants-svaret med dessa filter.
Anropa fullgörande slutpunkt med en testnyckel.
Bekräfta att svaret visar status: "delivered" med ett ifyllt license_key, att kunden får nyckel-e-postmeddelandet, och entitlement_grant.delivered utlöses.
Köp produkten i testläge (se guiderna för checkout).
Bekräfta att din webhook tog emot entitlement_grant.created med status: "Pending" och integration_type: "license_key", eller att grant visas i svaret från List Grants med dessa filter.
Anropa fulfill-endpointen med en testnyckel.
Bekräfta att svaret visar status: "Delivered" med ett ifyllt license_key, att kunden får e-postmeddelandet med nyckeln och att entitlement_grant.delivered utlöses.

Relaterad API-referens

Create Entitlement

Skapa licensnyckelrättigheten med fulfillment_mode: manual.

List Grants

Filtrera efter integration_type och status för att hitta väntande beviljanden.

Fulfill License Key Grant

Leverera nyckelvärdet och överför beviljandet till levererat.

Entitlement Grant Webhooks

entitlement_grant.*-händelserna som signalerar väntande och levererade beviljanden.

Create Entitlement

Skapa License Key-entitlementet med fulfillment_mode: manual.

List Grants

Filtrera efter status och customer_id för att hitta väntande grants.

Fulfill License Key Grant

Leverera nyckelvärdet och ändra grantets status till levererad.

Entitlement Grant Webhooks

Händelserna entitlement_grant.* som signalerar väntande och levererade grants.

Integration Guides

Billing Deconstructions

Cookbooks

Integrationsguide för manuell leverans av licensnycklar

License Keys overview

Fulfill License Key Grant API

Hur det fungerar

Förutsättningar

Steg 1 — Skapa en rättighet för licensnycklar i manuellt läge

Steg 2 — Fäst rättigheten till en produkt

Steg 3 — Detektera väntande beviljanden

Eller fråga List Grants API

Steg 4 — Leverera nyckeln

Begär fält

Steg 5 — Hantera fel och omförsökningar

Verifiera flödet

Relaterad API-referens

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

​Hur det fungerar

​Förutsättningar

​Steg 1 — Skapa en rättighet för licensnycklar i manuellt läge

​Steg 2 — Fäst rättigheten till en produkt

​Steg 3 — Detektera väntande beviljanden

​Eller fråga List Grants API

​Steg 4 — Leverera nyckeln

​Begär fält

​Steg 5 — Hantera fel och omförsökningar

​Verifiera flödet

​Relaterad API-referens

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Create Entitlement

List Grants

Fulfill License Key Grant

Entitlement Grant Webhooks

Hur det fungerar

Förutsättningar

Steg 1 — Skapa en rättighet för licensnycklar i manuellt läge

Steg 2 — Fäst rättigheten till en produkt

Steg 3 — Detektera väntande beviljanden

Eller fråga List Grants API

Steg 4 — Leverera nyckeln

Begär fält

Steg 5 — Hantera fel och omförsökningar

Verifiera flödet

Relaterad API-referens