> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Express Adaptor

> Erfahren Sie, wie Sie Dodo Payments mit Ihrem Express App Router-Projekt über unseren Express Adaptor integrieren. Behandelt Checkout, Kundenportal, Webhooks und die Einrichtung einer sicheren Umgebung.

<CardGroup cols={2}>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Integrieren Sie den Dodo Payments Checkout in Ihre Express-App.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Ermöglichen Sie Kunden, Abonnements und Details zu verwalten.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Empfangen und verarbeiten Sie Dodo Payments Webhook-Ereignisse.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus:

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    Erstellen Sie eine <code>.env</code>-Datei im Stammverzeichnis Ihres Projekts:

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
    DODO_PAYMENTS_RETURN_URL=your-return-url
    ```

    <Warning>
      Committen Sie Ihre <code>.env</code>-Datei oder Geheimnisse niemals in die Versionskontrolle.
    </Warning>
  </Step>
</Steps>

## Routenhandler-Beispiele

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Verwenden Sie diesen Handler, um den Dodo Payments Checkout in Ihre Express-App zu integrieren. Unterstützt statische (GET), dynamische (POST) und Session- (POST) Zahlungsabläufe.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { checkoutHandler } from '@dodopayments/express';

      app.get('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "static"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "dynamic"
      }))

      app.post('/api/checkout', checkoutHandler({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
          type: "session"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "billing": {
        "city": "Texas",
        "country": "US",
        "state": "Texas",
        "street": "56, hhh",
        "zipcode": "560000"
      },
      "customer": {
        "email": "test@example.com",
        	"name": "test"
      },
      "metadata": {},
      "payment_link": true,
        "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
        "quantity": 1,
        "billing_currency": "USD",
        "discount_codes": ["IKHZ23M9GQ"],
        "return_url": "https://example.com",
        "trial_period_days": 10
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      curl --request POST \
      --url https://example.com/api/checkout \
      --header 'Content-Type: application/json' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test \
      --data '{
      "product_cart": [
        {
          "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
          "quantity": 1
        }
      ],
      "customer": {
        "email": "test@example.com",
        "name": "test"
      },
      "return_url": "https://example.com/success"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Verwenden Sie diesen Handler, damit Kunden ihre Abonnements und Details über das Dodo Payments Kundenportal verwalten können.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

      app.get('/api/customer-portal', CustomerPortal({
          bearerToken: process.env.DODO_PAYMENTS_API_KEY,
          environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Verwenden Sie diesen Handler, um Dodo Payments Webhook-Ereignisse sicher in Ihrer Express-App zu empfangen und zu verarbeiten.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { Webhooks } from "@dodopayments/express";

      app.post('/api/webhook',Webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
              // handle the payload
          },
          // ... other event handlers for granular control
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Checkout-Routen-Handler

<Info>
  Dodo Payments unterstützt drei Arten von Zahlungsabläufen zur Integration von Zahlungen auf Ihrer Website. Dieser Adapter unterstützt alle Arten von Zahlungsabläufen.
</Info>

* **Statische Zahlungslinks:** Sofort teilbare URLs zur schnellen, codefreien Zahlungsabwicklung.
* **Dynamische Zahlungslinks:** Programmgesteuertes Erstellen von Zahlungslinks mit benutzerdefinierten Details über die API oder SDKs.
* **Checkout-Sitzungen:** Erstellen Sie sichere, anpassbare Checkout-Erlebnisse mit vorkonfigurierten Produktkörben und Kundendetails.

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Unterstützte Abfrageparameter

    <ParamField query="productId" type="string" required>
      Produktkennzeichen (z. B. <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField query="quantity" type="integer">
      Menge des Produkts.
    </ParamField>

    <ParamField query="fullName" type="string">
      Vollständiger Name des Kunden.
    </ParamField>

    <ParamField query="firstName" type="string">
      Vorname des Kunden.
    </ParamField>

    <ParamField query="lastName" type="string">
      Nachname des Kunden.
    </ParamField>

    <ParamField query="email" type="string">
      E-Mail-Adresse des Kunden.
    </ParamField>

    <ParamField query="country" type="string">
      Land des Kunden.
    </ParamField>

    <ParamField query="addressLine" type="string">
      Adresszeile des Kunden.
    </ParamField>

    <ParamField query="city" type="string">
      Stadt des Kunden.
    </ParamField>

    <ParamField query="state" type="string">
      Bundesland/Provinz des Kunden.
    </ParamField>

    <ParamField query="zipCode" type="string">
      Postleitzahl des Kunden.
    </ParamField>

    <ParamField query="disableFullName" type="boolean">
      Vollnamenfeld deaktivieren.
    </ParamField>

    <ParamField query="disableFirstName" type="boolean">
      Vornamenfeld deaktivieren.
    </ParamField>

    <ParamField query="disableLastName" type="boolean">
      Nachnamenfeld deaktivieren.
    </ParamField>

    <ParamField query="disableEmail" type="boolean">
      E-Mail-Feld deaktivieren.
    </ParamField>

    <ParamField query="disableCountry" type="boolean">
      Länderauswahlfeld deaktivieren.
    </ParamField>

    <ParamField query="disableAddressLine" type="boolean">
      Adresszeilenfeld deaktivieren.
    </ParamField>

    <ParamField query="disableCity" type="boolean">
      Stadtfeld deaktivieren.
    </ParamField>

    <ParamField query="disableState" type="boolean">
      Bundeslandfeld deaktivieren.
    </ParamField>

    <ParamField query="disableZipCode" type="boolean">
      Postleitzahlenfeld deaktivieren.
    </ParamField>

    <ParamField query="paymentCurrency" type="string">
      Geben Sie die Zahlungswährung an (z. B. <code>USD</code>).
    </ParamField>

    <ParamField query="showCurrencySelector" type="boolean">
      Währungsselektor anzeigen.
    </ParamField>

    <ParamField query="paymentAmount" type="integer">
      Geben Sie den Zahlungsbetrag an (z. B. <code>1000</code> für 10,00 \$).
    </ParamField>

    <ParamField query="showDiscounts" type="boolean">
      Rabattfelder anzeigen.
    </ParamField>

    <ParamField query="metadata_*" type="string">
      Jeder Abfrageparameter, der mit <code>metadata\_</code> beginnt, wird als Metadaten weitergegeben.
    </ParamField>

    <Warning>
      Fehlt <code>productId</code>, liefert der Handler eine 400-Antwort. Ungültige Abfrageparameter führen ebenfalls zu einer 400-Antwort.
    </Warning>

    ### Antwortformat

    Der statische Checkout gibt eine JSON-Antwort mit der Checkout-URL zurück:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Dynamic Checkout (POST)">
    * Senden Sie Parameter als JSON-Body in einer POST-Anfrage.
    * Unterstützt einmalige und wiederkehrende Zahlungen.
    * Für eine vollständige Liste der unterstützten POST-Body-Felder siehe:
      * [Request body for a One Time Payment Product](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Antwortformat

    Der dynamische Checkout gibt eine JSON-Antwort mit der Checkout-URL zurück:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="Checkout Sessions (POST)">
    Checkout-Sitzungen bieten eine sicherere, gehostete Checkout-Erfahrung, die den vollständigen Zahlungsablauf für einmalige Käufe und Abonnements abwickelt und dabei vollständige Anpassungskontrolle bietet.

    Siehe [Integrationsleitfaden für Checkout-Sitzungen](https://docs.dodopayments.com/developer-resources/checkout-session) für weitere Details und eine vollständige Liste der unterstützten Felder.

    ### Antwortformat

    Checkout-Sitzungen geben eine JSON-Antwort mit der Checkout-URL zurück:

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## Kundenportal-Routen-Handler

Der Kundenportal-Routen-Handler ermöglicht es Ihnen, das Dodo Payments Kundenportal nahtlos in Ihre Express-Anwendung zu integrieren.

### Abfrageparameter

<ParamField query="customer_id" type="string" required>
  Die Kunden-ID für die Portalsitzung (z. B. <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField query="send_email" type="boolean">
  Wenn auf <code>true</code> gesetzt, sendet es eine E-Mail mit dem Portal-Link an den Kunden.
</ParamField>

<Warning>
  Gibt 400 zurück, wenn <code>customer\_id</code> fehlt.
</Warning>

## Webhook-Routen-Handler

* **Methode:** Nur POST-Anfragen werden unterstützt. Andere Methoden geben 405 zurück.
* **Signaturverifizierung:** Überprüft die Webhook-Signatur mit <code>webhookKey</code>. Gibt 401 zurück, wenn die Verifizierung fehlschlägt.
* **Payload-Validierung:** Wird mit Zod validiert. Gibt 400 für ungültige Payloads zurück.
* **Fehlerbehandlung:**
  * 401: Ungültige Signatur
  * 400: Ungültige Payload
  * 500: Interner Fehler während der Verifizierung
* **Ereignisweiterleitung:** Ruft den entsprechenden Ereignishandler basierend auf dem Payload-Typ auf.

### Unterstützte Webhook-Ereignishandler

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  onPayload?: (payload: WebhookPayload) => Promise<void>;
  onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
  onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
  onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
  onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
  onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
  onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
  onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
  onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
  onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
  onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
  onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
  onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
  onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Eingabeaufforderung für LLM

```
Sie sind ein Experte für Express.js-Entwicklung. Ihre Aufgabe ist es, einen Benutzer durch die Integration des @dodopayments/express-Adapters in sein bestehendes Express.js-Projekt zu führen.

Der @dodopayments/express-Adapter bietet Routenhandler für die Checkout-, Kundenportal- und Webhook-Funktionalitäten von Dodo Payments, die direkt in eine Express-App integriert werden können.

Zuerst installieren Sie das erforderliche Paket. Verwenden Sie den für das Projekt des Benutzers geeigneten Paketmanager (npm, yarn oder bun):

npm install @dodopayments/express

---

So sollten Sie Ihre Antwort strukturieren:

1. Fragen Sie den Benutzer, welche Funktionalitäten er integrieren möchte.

"Welche Teile des @dodopayments/express-Adapters möchten Sie in Ihr Projekt integrieren? Sie können eine oder mehrere der folgenden Optionen wählen:

- Checkout-Routen-Handler (zum Verarbeiten von Produkt-Checkouts)
- Kundenportal-Routen-Handler (zum Verwalten von Kundenabonnements/Details)
- Webhook-Routen-Handler (zum Empfangen von Dodo Payments Webhook-Ereignissen)
- Alle (alle drei integrieren)"

---

2. Basierend auf der Auswahl des Benutzers geben Sie detaillierte Integrationsschritte für jede gewählte Funktionalität an.

---

**Wenn der Checkout-Routen-Handler ausgewählt ist:**

**Zweck**: Dieser Handler verwaltet verschiedene Arten von Checkout-Flüssen. Alle Checkout-Typen (statisch, dynamisch und Sitzungen) geben JSON-Antworten mit Checkout-URLs für die programmgesteuerte Verarbeitung zurück.

**Integration**:
Erstellen Sie Routen in Ihrer Express-App für statische (GET), dynamische (POST) und Checkout-Sitzungen (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// Für Checkout-Sitzungen
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Konfigurationsoptionen:

    bearerToken: Ihr Dodo Payments API-Schlüssel (wird empfohlen, in der Umgebungsvariablen DODO_PAYMENTS_API_KEY gespeichert zu werden).

    returnUrl (optional): URL, um den Benutzer nach einem erfolgreichen Checkout weiterzuleiten.

    environment: "test_mode" oder "live_mode"

    type: "static" (GET), "dynamic" (POST) oder "session" (POST)

GET (statischer Checkout) erwartet Abfrageparameter:

    productId (erforderlich)

    Menge, Kundenfelder (fullName, email usw.) und Metadaten (metadata_*) sind optional.

    Gibt zurück: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (dynamischer Checkout) erwartet einen JSON-Body mit Zahlungsdetails (einmalig oder Abonnement). Verweisen Sie auf die Dokumentation für das vollständige POST-Schema:

    Einmalige Zahlungen: https://docs.dodopayments.com/api-reference/payments/post-payments

    Abonnements: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Gibt zurück: {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (Checkout-Sitzungen) - (Empfohlen) Ein anpassbareres Checkout-Erlebnis. Gibt JSON mit checkout_url zurück: Parameter werden als JSON-Body gesendet. Unterstützt sowohl einmalige als auch wiederkehrende Zahlungen. Gibt zurück: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Für eine vollständige Liste der unterstützten Felder siehe:

  Integrationsleitfaden für Checkout-Sitzungen: https://docs.dodopayments.com/developer-resources/checkout-session

Wenn der Kundenportal-Routen-Handler ausgewählt ist:

Zweck: Diese Route ermöglicht es Kunden, ihre Abonnements über das Dodo Payments-Portal zu verwalten.

Integration:

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Abfrageparameter:

    customer_id (erforderlich): z. B. ?customer_id=cus_123

    send_email (optional): wenn true, wird dem Kunden der Portal-Link per E-Mail gesendet

Gibt 400 zurück, wenn customer_id fehlt.

Wenn der Webhook-Routen-Handler ausgewählt ist:

Zweck: Verarbeitet eingehende Webhook-Ereignisse von Dodo Payments, um Ereignisse in Ihrer App auszulösen.

Integration:

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Allgemeine Payload verarbeiten
  },
  // Sie können auch detaillierte Handler für jeden Ereignistyp unten bereitstellen
}));

Funktionen:

    Nur die POST-Methode ist erlaubt — andere geben 405 zurück

    Die Signaturverifizierung erfolgt mit webhookKey. Gibt 401 zurück, wenn ungültig.

    Zod-basierte Payload-Validierung. Gibt 400 zurück, wenn das Schema ungültig ist.

    Alle Handler sind asynchrone Funktionen.

Unterstützte Webhook-Ereignishandler:

Sie können einen der folgenden Handler übergeben:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired

    onLicenseKeyCreated

Einrichtung der Umgebungsvariablen:

Stellen Sie sicher, dass Sie diese Umgebungsvariablen in Ihrem Projekt definieren:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" oder "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Verwenden Sie diese in Ihrem Code wie:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Sicherheitsnotiz: Verpflichte keine Geheimnisse zur Versionskontrolle. Verwenden Sie lokal .env-Dateien und Geheimnismanager in Bereitstellungsumgebungen (z. B. AWS, Vercel, Heroku usw.).

Verwenden Sie diese in Ihrem Code wie folgt:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Sicherheitshinweis: Kompromittieren Sie keine Geheimnisse in der Versionskontrolle. Nutzen Sie .env-Dateien lokal und verwenden Sie Geheimnis-Manager in Bereitstellungsumgebungen (z. B. AWS, Vercel, Heroku, etc.).
```