@dodopayments/bun ger din Bun-server tre request-hanterare. Checkout returnerar checkout-URL:er, CustomerPortal skickar en kund till Customer Portal och Webhooks verifierar webhook-händelser och dirigerar dem till din kod. Varje hanterare tar emot en standard-Request och returnerar en Response, så du anropar den från fetch-hanteraren i Bun.serve().
Checkout Handler
Skapa checkout-URL:er med statiska, dynamiska och checkout session-flöden.
Customer Portal
Låt kunder hantera sina prenumerationer och uppgifter.
Webhooks
Ta emot och bearbeta webhook-händelser från Dodo Payments.
Installation
1
Install the Package
Kör det här kommandot i projektets rot:Paketet behöver även
zod 3.25 eller senare, vilket anges som ett peer dependency.2
Set Up Environment Variables
Skapa en Bun läser automatiskt
.env-fil i projektets rot. Skapa API-nyckeln under Developer → API Keys. Lägg till din webhook-endpoint under Developer → Webhooks och kopiera dess Signing secret till DODO_PAYMENTS_WEBHOOK_KEY:.env-filer, så exemplen läser dessa värden från process.env. DODO_PAYMENTS_RETURN_URL är dit kunder kommer efter checkout. Om du inte anger en miljö använder hanterarna live_mode. En API-nyckel för testläge fungerar endast med test_mode.Exempel på route-hanterare
Alla exempel använder Buns inbyggda server,
Bun.serve(), och dirigerar requests efter path och method i dess fetch-hanterare.- Checkout Handler
- Customer Portal Handler
- Webhook Handler
Använd den här hanteraren för att lägga till Dodo Payments checkout i din Bun-server. Den statiska hanteraren hanterar
GET requests. Sessions- och dynamikhanterarna hanterar POST requests. Exemplet med dynamisk checkout förutsätter att servern returnerar dynamicCheckoutHandler(request) för POST requests.Route-hanterare för checkout
Checkout-hanteraren stöder alla tre sätten att ta betalt med Dodo Payments:- Statiska Payment Links: Delbara URL:er som samlar in betalningar utan kod.
- Dynamiska Payment Links: Payment links som du genererar med anpassade uppgifter. De använder föråldrade endpoints.
- Checkout Sessions: Hosted checkout med en produktkundvagn, kunduppgifter och anpassningsalternativ. Detta är det rekommenderade flödet.
Checkout tar emot följande alternativ:
Hanteraren tillhandahåller statisk checkout för
GET requests. För POST requests skapar den en dynamisk payment link när type är dynamic, och annars en checkout session.
Static Checkout (GET)
Static Checkout (GET)
Parametrar som stöds
Fastställer det debiterade beloppet i större valutaenheter, till exempel
12.5 för $12.50. Fungerar endast med Pay What You Want-produkter och ignoreras om beloppet understiger produktens minimipris.Alla query-parametrar som börjar med
metadata_ skickas till checkout som metadata, till exempel metadata_orderId=123.email med disableEmail=true. Hanteraren lägger till returnUrl från sin konfiguration i länken som redirect_url.Svarsformat
Statisk checkout returnerar ett JSON-svar med checkout-URL:en. I testläge använder URL:entest.checkout.dodopayments.com:Dynamic Checkout (POST)
Dynamic Checkout (POST)
- Skicka parametrarna som en JSON body i en POST request.
- Stöder både engångsbetalningar och återkommande betalningar. Hanteraren hämtar produkten och skapar sedan en prenumeration om produkten är återkommande, och annars en engångsbetalning.
- Bodyn behöver
billing(medstreet,city,state,countryochzipcode) ochcustomer, samtproduct_idellerproduct_cart. Prenumerationer behöverproduct_id. - För alla body-fält som stöds, se:
Svarsformat
Dynamisk checkout returnerar ett JSON-svar med payment link som checkout-URL:Checkout Sessions (POST)
Checkout Sessions (POST)
Checkout sessions skapar en hosted checkout för engångsköp och prenumerationer, med full kontroll över anpassningen.
product_cart är det enda obligatoriska fältet och behöver minst en produkt. Om bodyn saknar return_url använder hanteraren returnUrl från sin konfiguration.Varje checkout_url fungerar en gång och upphör efter 24 timmar, eller efter 15 minuter när du skickar confirm: true. En session som skapats med payment_method_id returnerar ingen checkout_url, så hanteraren svarar med 400.Mer information och alla fält som stöds finns i Integrationsguide för Checkout Sessions.Svarsformat
Checkout sessions returnerar ett JSON-svar med checkout-URL:en:Route-hanterare för Customer Portal
Route-hanteraren för Customer Portal skapar en Customer Portal-session för den kund du anger och omdirigerar webbläsaren dit.CustomerPortal tar emot samma bearerToken- och environment-alternativ som Checkout.
Query-parametrar
Hanteraren returnerar 400 omcustomer_id saknas och 500 om portalsessionen inte kan skapas.
Route-hanterare för webhook
Webhook-route-hanteraren verifierar varje request med din webhook-hemlighet, som skickas somwebhookKey, innan den kör din kod:
- Method: Endast POST requests stöds. Andra metoder returnerar 405.
- Signature Verification: Verifierar header-värdena
webhook-id,webhook-timestampochwebhook-signaturemedwebhookKeyenligt specifikationen Standard Webhooks. Returnerar 401 om verifieringen misslyckas. - Payload Validation: Tolkar bodyn som JSON och validerar den med Zod. Returnerar 400 för ogiltig JSON eller en ogiltig payload.
- Error Handling:
- 401: Ogiltig signatur
- 400: Ogiltig payload
- 500: Internt fel under verifieringen
- Event Routing: Anropar
onPayloadför varje händelse, därefter hanteraren för händelsens typ, och returnerar 200.
Bun.serve() och requesten misslyckas.