@dodopayments/bun-Paket stellt deinem Bun-Server drei Request-Handler bereit. Checkout gibt Checkout-URLs zurück, CustomerPortal sendet einen Kunden zum Customer Portal und Webhooks verifiziert Webhook-Ereignisse und leitet sie an deinen Code weiter. Jeder Handler akzeptiert ein standardmäßiges Request und gibt ein Response zurück. Du rufst ihn daher im fetch-Handler von Bun.serve() auf.
Checkout Handler
Erstelle Checkout-URLs mit statischen, dynamischen und Checkout-Session-Abläufen.
Customer Portal
Ermögliche Kunden, ihre Abonnements und Daten zu verwalten.
Webhooks
Empfange und verarbeite Dodo Payments Webhook-Ereignisse.
Installation
1
Install the Package
Führe diesen Befehl im Stammverzeichnis deines Projekts aus:Das Paket benötigt außerdem
zod 3.25 oder höher, das als Peer-Dependency aufgeführt ist.2
Set Up Environment Variables
Erstelle eine Datei Bun liest
.env im Stammverzeichnis deines Projekts. Erstelle den API-Schlüssel unter Developer → API Keys. Füge deinen Webhook-Endpunkt unter Developer → Webhooks hinzu und kopiere sein Signing secret in DODO_PAYMENTS_WEBHOOK_KEY:.env-Dateien automatisch ein, daher lesen die Beispiele diese Werte aus process.env. DODO_PAYMENTS_RETURN_URL ist das Ziel, zu dem Kunden nach dem Checkout gelangen. Wenn du keine Umgebung übergibst, verwenden die Handler live_mode. Ein API-Schlüssel für den Testmodus funktioniert nur mit test_mode.Beispiele für Route-Handler
Alle Beispiele verwenden den nativen Server von Bun,
Bun.serve(), und leiten Requests anhand von Pfad und Methode im fetch-Handler weiter.- Checkout Handler
- Customer Portal Handler
- Webhook Handler
Verwende diesen Handler, um Dodo Payments checkout zu deinem Bun-Server hinzuzufügen. Der statische Handler verarbeitet
GET-Requests. Die Session- und dynamischen Handler verarbeiten POST-Requests. Das dynamische Checkout-Beispiel setzt voraus, dass der Server für POST-Requests dynamicCheckoutHandler(request) zurückgibt.Checkout-Route-Handler
Der Checkout-Handler unterstützt alle drei Möglichkeiten, Zahlungen mit Dodo Payments entgegenzunehmen:- Statische Payment Links: Teilbare URLs, die Zahlungen ohne Code erfassen.
- Dynamische Payment Links: Payment Links, die du mit benutzerdefinierten Daten generierst. Sie verwenden veraltete Endpunkte.
- Checkout Sessions: Gehosteter Checkout mit Produkt-Warenkorb, Kundendaten und Anpassungsoptionen. Dies ist der empfohlene Ablauf.
Checkout akzeptiert diese Optionen:
Der Handler stellt statischen Checkout für
GET-Requests bereit. Für POST-Requests erstellt er einen dynamischen Payment Link, wenn type dynamic entspricht, und andernfalls eine Checkout Session.
Static Checkout (GET)
Static Checkout (GET)
Unterstützte Query-Parameter
Legt den berechneten Betrag in den Haupteinheiten der Währung fest, zum Beispiel
12.5 für $12.50. Funktioniert nur mit Pay What You Want-Produkten und wird ignoriert, wenn der Betrag unter dem Mindestpreis des Produkts liegt.Jeder Query-Parameter, der mit
metadata_ beginnt, wird als Metadaten an den Checkout übergeben, zum Beispiel metadata_orderId=123.email zusammen mit disableEmail=true. Der Handler fügt returnUrl aus seiner Konfiguration als redirect_url zum Link hinzu.Antwortformat
Der statische Checkout gibt eine JSON-Antwort mit der Checkout-URL zurück. Im Testmodus verwendet die URLtest.checkout.dodopayments.com:Dynamic Checkout (POST)
Dynamic Checkout (POST)
- Sende die Parameter als JSON-Body in einem POST-Request.
- Unterstützt sowohl einmalige als auch wiederkehrende Zahlungen. Der Handler ruft das Produkt ab und erstellt anschließend ein Abonnement, wenn es sich um ein wiederkehrendes Produkt handelt, andernfalls eine einmalige Zahlung.
- Der Body benötigt
billing(mitstreet,city,state,countryundzipcode) undcustomersowieproduct_idoderproduct_cart. Abonnements benötigenproduct_id. - Eine Übersicht aller unterstützten Body-Felder findest du hier:
Antwortformat
Der dynamische Checkout gibt eine JSON-Antwort mit dem Payment Link als Checkout-URL zurück:Checkout Sessions (POST)
Checkout Sessions (POST)
Checkout Sessions erstellen einen gehosteten Checkout für einmalige Käufe und Abonnements mit vollständiger Kontrolle über die Anpassung.
product_cart ist das einzige erforderliche Feld und benötigt mindestens ein Produkt. Wenn der Body kein return_url enthält, verwendet der Handler returnUrl aus seiner Konfiguration.Jedes checkout_url kann einmal verwendet werden und läuft nach 24 Stunden ab oder nach 15 Minuten, wenn du confirm: true übergibst. Eine mit payment_method_id erstellte Session gibt kein checkout_url zurück, daher antwortet der Handler mit 400.Weitere Informationen und alle unterstützten Felder findest du im Integrationsleitfaden für Checkout Sessions.Antwortformat
Checkout Sessions geben eine JSON-Antwort mit der Checkout-URL zurück:Customer-Portal-Route-Handler
Der Customer-Portal-Route-Handler erstellt eine Customer-Portal-Session für den angegebenen Kunden und leitet den Browser dorthin weiter.CustomerPortal akzeptiert dieselben Optionen bearerToken und environment wie Checkout.
Query-Parameter
Wenn auf
true gesetzt, sendet Dodo Payments dem Kunden zusätzlich den Portal-Link per E-Mail.customer_id fehlt, und 500, wenn die Portal-Session nicht erstellt werden kann.
Webhook-Route-Handler
Der Webhook-Route-Handler verifiziert jeden Request mit deinem Webhook-Secret, das alswebhookKey übergeben wird, bevor er deinen Code ausführt:
- Methode: Es werden nur POST-Requests unterstützt. Andere Methoden geben 405 zurück.
- Signaturverifizierung: Verifiziert die Header
webhook-id,webhook-timestampundwebhook-signaturemitwebhookKeygemäß der Spezifikation für Standard Webhooks. Bei fehlgeschlagener Verifizierung wird 401 zurückgegeben. - Payload-Validierung: Analysiert den Body als JSON und validiert ihn mit Zod. Bei ungültigem JSON oder einer ungültigen Payload wird 400 zurückgegeben.
- Fehlerbehandlung:
- 401: Ungültige Signatur
- 400: Ungültige Payload
- 500: Interner Fehler während der Verifizierung
- Ereignisweiterleitung: Ruft
onPayloadfür jedes Ereignis auf, anschließend den Handler für den Ereignistyp, und gibt 200 zurück.
Bun.serve() weitergeleitet und der Request schlägt fehl.