Express Adaptor - Dodo Payments Documentation

Checkout Handler

Integrieren Sie den Dodo Payments Checkout in Ihre Express-App.

Customer Portal

Ermöglichen Sie Kunden, Abonnements und Details zu verwalten.

Webhooks

Empfangen und verarbeiten Sie Dodo Payments Webhook-Ereignisse.

Installation

Install the package

Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus:

npm install @dodopayments/express

Set up environment variables

Erstellen Sie eine .env-Datei im Stammverzeichnis Ihres Projekts:

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

Committen Sie Ihre .env-Datei oder Geheimnisse niemals in die Versionskontrolle.

Routenhandler-Beispiele

Checkout Handler
Customer Portal Handler
Webhook Handler

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.

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

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

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

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

Verwenden Sie diesen Handler, damit Kunden ihre Abonnements und Details über das Dodo Payments Kundenportal verwalten können.

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

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

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

Verwenden Sie diesen Handler, um Dodo Payments Webhook-Ereignisse sicher in Ihrer Express-App zu empfangen und zu verarbeiten.

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

Checkout-Routen-Handler

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.

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.

Static Checkout (GET)

Unterstützte Abfrageparameter

productId

string

erforderlich

Produktkennzeichen (z. B. ?productId=pdt_nZuwz45WAs64n3l07zpQR).

quantity

integer

Menge des Produkts.

fullName

string

Vollständiger Name des Kunden.

firstName

string

Vorname des Kunden.

lastName

string

Nachname des Kunden.

string

E-Mail-Adresse des Kunden.

country

string

Land des Kunden.

addressLine

string

Adresszeile des Kunden.

city

string

Stadt des Kunden.

state

string

Bundesland/Provinz des Kunden.

zipCode

string

Postleitzahl des Kunden.

disableFullName

boolean

Vollnamenfeld deaktivieren.

disableFirstName

boolean

Vornamenfeld deaktivieren.

disableLastName

boolean

Nachnamenfeld deaktivieren.

disableEmail

boolean

E-Mail-Feld deaktivieren.

disableCountry

boolean

Länderauswahlfeld deaktivieren.

disableAddressLine

boolean

Adresszeilenfeld deaktivieren.

disableCity

boolean

Stadtfeld deaktivieren.

disableState

boolean

Bundeslandfeld deaktivieren.

disableZipCode

boolean

Postleitzahlenfeld deaktivieren.

paymentCurrency

string

Geben Sie die Zahlungswährung an (z. B. USD).

showCurrencySelector

boolean

Währungsselektor anzeigen.

paymentAmount

integer

Geben Sie den Zahlungsbetrag an (z. B. 1000 für 10,00 $).

showDiscounts

boolean

Rabattfelder anzeigen.

metadata_*

string

Jeder Abfrageparameter, der mit metadata_ beginnt, wird als Metadaten weitergegeben.

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

Antwortformat

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

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

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
- Request body for a Subscription Product

Antwortformat

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

{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

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 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:

{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

Kundenportal-Routen-Handler

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

Abfrageparameter

customer_id

string

erforderlich

Die Kunden-ID für die Portalsitzung (z. B. ?customer_id=cus_123).

send_email

boolean

Wenn auf true gesetzt, sendet es eine E-Mail mit dem Portal-Link an den Kunden.

Gibt 400 zurück, wenn customer_id fehlt.

Webhook-Routen-Handler

Methode: Nur POST-Anfragen werden unterstützt. Andere Methoden geben 405 zurück.
Signaturverifizierung: Überprüft die Webhook-Signatur mit webhookKey. 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

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>;

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

Checkout Handler

Customer Portal

Webhooks

​Installation

​Routenhandler-Beispiele

​Checkout-Routen-Handler

​Unterstützte Abfrageparameter

​Antwortformat

​Antwortformat

​Antwortformat

​Kundenportal-Routen-Handler

​Abfrageparameter

​Webhook-Routen-Handler

​Unterstützte Webhook-Ereignishandler

​Eingabeaufforderung für LLM

Installation

Routenhandler-Beispiele

Checkout-Routen-Handler

Unterstützte Abfrageparameter

Antwortformat

Antwortformat

Antwortformat

Kundenportal-Routen-Handler

Abfrageparameter

Webhook-Routen-Handler

Unterstützte Webhook-Ereignishandler

Eingabeaufforderung für LLM