Zum Hauptinhalt springen

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

1

Install the package

Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus:
npm install @dodopayments/express
2

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

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

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

​
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.
​
email
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/..."
}

​
Antwortformat

Der dynamische Checkout gibt eine JSON-Antwort mit der Checkout-URL zurück:
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}
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.).