Express Adaptor - Dodo Payments Documentation

Checkout Handler

Integrera Dodo Payments checkout i din Express-app.

Customer Portal

Låt kunder hantera prenumerationer och uppgifter.

Webhooks

Ta emot och bearbeta webhook-händelser från Dodo Payments.

Installation

Install the package

Kör följande kommando i projektroten:

npm install @dodopayments/express

Set up environment variables

Skapa en .env-fil i projektroten:

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

Lägg aldrig upp din .env-fil eller hemligheter i versionskontroll.

Exempel på Routhanterare

Checkout Handler
Customer Portal Handler
Webhook Handler

Använd den här hanteraren för att integrera Dodo Payments checkout i din Express-app. Stöder statiska (GET), dynamiska (POST) och sessionbaserade (POST) betalflöden.

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

Använd den här hanteraren för att låta kunder hantera sina prenumerationer och uppgifter via Dodo Payments kundportal.

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

Använd den här hanteraren för att ta emot och bearbeta webhook-händelser från Dodo Payments säkert i din Express-app.

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

Kassa Routhanterare

Dodo Payments stöder tre typer av betalningsflöden för att integrera betalningar på din webbplats, och denna adapter stöder alla typer av betalflöden.

Statiska Betalningslänkar: Omedelbart delbara URL:er för snabb, kodfri insamling av betalningar.
Dynamiska Betalningslänkar: Programmatisk generering av betalningslänkar med anpassade detaljer med hjälp av API eller SDK:er.
Kassa Sessioner: Skapa säkra, anpassningsbara kassaupplevelser med förkonfigurerade produktvagnar och kunddetaljer.

Static Checkout (GET)

Supported Query Parameters

productId

string

obligatorisk

Produktidentifierare (t.ex. ?productId=pdt_nZuwz45WAs64n3l07zpQR).

quantity

integer

Antal av produkten.

fullName

string

Kundens fullständiga namn.

firstName

string

Kundens förnamn.

lastName

string

Kundens efternamn.

string

Kundens e-postadress.

country

string

Kundens land.

addressLine

string

Kundens adressrad.

city

string

Kundens stad.

state

string

Kundens delstat/region.

zipCode

string

Kundens postnummer.

disableFullName

boolean

Inaktivera fältet för fullständigt namn.

disableFirstName

boolean

Inaktivera fältet för förnamn.

disableLastName

boolean

Inaktivera fältet för efternamn.

disableEmail

boolean

Inaktivera e-postfältet.

disableCountry

boolean

Inaktivera landsfältet.

disableAddressLine

boolean

Inaktivera adressfältet.

disableCity

boolean

Inaktivera stadsfältet.

disableState

boolean

Inaktivera fältet för delstat.

disableZipCode

boolean

Inaktivera fältet för postnummer.

paymentCurrency

string

Ange betalningsvalutan (t.ex. USD).

showCurrencySelector

boolean

Visa valutaväljare.

paymentAmount

integer

Ange betalningsbeloppet (t.ex. 1000 för $10,00).

showDiscounts

boolean

Visa rabattfält.

metadata_*

string

Alla query-parametrar som börjar med metadata_ kommer att vidarebefordras som metadata.

Om productId saknas returnerar hanteraren ett 400-svar. Ogiltiga query-parametrar resulterar också i ett 400-svar.

Svarsformat

Statisk kassa returnerar ett JSON-svar med kassa-URL:en:

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

Dynamic Checkout (POST)

Skicka parametrar som en JSON-kropp i en POST-begäran.
Stödjer både engångs- och återkommande betalningar.
För en komplett lista över stödda POST-kroppsfält, se:
- Request body for a One Time Payment Product
- Request body for a Subscription Product

Svarsformat

Dynamisk kassa returnerar ett JSON-svar med kassa-URL:en:

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

Checkout Sessions (POST)

Checkout-sessioner erbjuder en säkrare, värdbaserad checkout-upplevelse som hanterar hela betalflödet för både engångsinlösen och prenumerationer med full anpassningsbarhet.Se Kassa Sessioner Integrationsguide för mer information och en komplett lista över stödda fält.

Svarsformat

Kassa sessioner returnerar ett JSON-svar med kassa-URL:en:

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

Kundportal Routhanterare

Kundportal Routhanteraren gör det möjligt för dig att sömlöst integrera Dodo Payments kundportal i din Express-applikation.

Query Parameters

customer_id

string

obligatorisk

Kundens ID för portalsessionen (t.ex. ?customer_id=cus_123).

send_email

boolean

Om det är satt till true skickas ett e-postmeddelande till kunden med portal-länken.

Returnerar 400 om customer_id saknas.

Webhook Routhanterare

Metod: Endast POST-förfrågningar stöds. Andra metoder returnerar 405.
Signaturverifiering: Verifierar webhook-signaturen med hjälp av webhookKey. Returnerar 401 om verifieringen misslyckas.
Payloadvalidering: Valideras med Zod. Returnerar 400 för ogiltiga payloads.
Felhantering:
- 401: Ogiltig signatur
- 400: Ogiltig payload
- 500: Intern fel under verifiering
Händelse-routing: Anropar den lämpliga händelsehanteraren baserat på payload-typen.

Supported Webhook Event Handlers

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

Prompt för LLM

Du är en expert på Express.js utvecklarassistent. Ditt uppdrag är att vägleda en användare genom att integrera @dodopayments/express-adaptern i deras befintliga Express.js-projekt.

@dodopayments/express-adaptern tillhandahåller routhanterare för Dodo Payments' Kassa, Kundportal och Webhook-funktioner, designade för att kopplas direkt in i en Express-app.

Först, installera det nödvändiga paketet. Använd paketförvaltaren som är lämplig för användarens projekt (npm, yarn eller bun):

npm install @dodopayments/express

---

Så här bör du strukturera ditt svar:

1. Fråga användaren vilka funktioner de vill integrera.

"Vilka delar av @dodopayments/express-adaptern skulle du vilja integrera i ditt projekt? Du kan välja en eller flera av följande:

- Kassa Routhanterare (för att hantera produktkassor)
- Kundportal Routhanterare (för att hantera kundens prenumerationer/detaljer)
- Webhook Routhanterare (för att ta emot Dodo Payments webhook-händelser)
- Alla (integrera alla tre)"

---

2. Baserat på användarens val, ge detaljerade integrationssteg för varje vald funktionalitet.

---

**Om Kassa Routhanterare är vald:**

**Syfte**: Denna hanterare hanterar olika typer av kassa-flöden. Alla kassatyp (statisk, dynamisk och sessioner) returnerar JSON-svar med kassa-URL:er för programmatisk hantering.

**Integration**:
Skapa rutter i din Express-app för statiska (GET), dynamiska (POST) och kassa sessioner (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 kassa sessioner
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"
}));

Konfigurationsalternativ:

    bearerToken: Din Dodo Payments API-nyckel (rekommenderas att lagras i DODO_PAYMENTS_API_KEY miljövariabel).

    returnUrl (valfritt): URL för att omdirigera användaren efter en lyckad kassa.

    environment: "test_mode" eller "live_mode"

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

GET (statisk kassa) förväntar sig frågeparametrar:

    productId (obligatorisk)

    quantity, kundfält (fullName, email, etc.), och metadata (metadata_*) är valfria.

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

POST (dynamisk kassa) förväntar sig en JSON-kropp med betalningsdetaljer (engångs eller prenumeration). Referera till dokumentationen för hela POST-schemat:

    Engångsbetalningar: https://docs.dodopayments.com/api-reference/payments/post-payments

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

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

POST (kassa sessioner) - (Rekommenderas) En mer anpassningsbar kassaupplevelse. Returnerar JSON med checkout_url: Parametrar skickas som en JSON-kropp. Stöder både engångs- och återkommande betalningar. Returnerar: {"checkout_url": "https://checkout.dodopayments.com/session/..."}. För en komplett lista över stödda fält, se:

  Kassa Sessioner Integrationsguide: https://docs.dodopayments.com/developer-resources/checkout-session

Om Kundportal Routhanterare är vald:

Syfte: Denna rutt tillåter kunder att hantera sina prenumerationer via Dodo Payments-portalen.

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

Frågeparametrar:

    customer_id (obligatorisk): t.ex. ?customer_id=cus_123

    send_email (valfritt): om sant, skickas kunden portalens länk via e-post

Returnerar 400 om customer_id saknas.

Om Webhook Routhanterare är vald:

Syfte: Bearbetar inkommande webhook-händelser från Dodo Payments för att utlösa händelser i din app.

Integration:

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

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Hantera generisk payload
  },
  // Du kan också tillhandahålla detaljerade hanterare för varje händelsetyp nedan
}));

Funktioner:

    Endast POST-metod är tillåten — andra returnerar 405

    Signaturverifiering utförs med hjälp av webhookKey. Returnerar 401 om ogiltig.

    Zod-baserad payloadvalidering. Returnerar 400 om ogiltig schema.

    Alla hanterare är asynkrona funktioner.

Stödda Webhook Händelsehanterare:

Du kan skicka in någon av följande hanterare:

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

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

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

    onLicenseKeyCreated

Miljövariabelinställning:

Se till att definiera dessa miljövariabler i ditt projekt:

DODO_PAYMENTS_API_KEY=din-api-nyckel
DODO_PAYMENTS_WEBHOOK_KEY=din-webhook-hemlighet
DODO_PAYMENTS_ENVIRONMENT="test_mode" eller "live_mode"
DODO_PAYMENTS_RETURN_URL=din-retur-url

Använd dessa i din kod som:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Säkerhetsnot: Kom ihåg att INTE begå hemligheter till versionskontroll. Använd .env-filer lokalt och hemlighetsförvaltare i distributionsmiljöer (t.ex. AWS, Vercel, Heroku, etc.).

Använd dessa i din kod som:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Säkerhetsnot: Lämna INTE in hemligheter till versionskontroll. Använd .env-filer lokalt och hantera hemligheter i distributionsmiljöer (t.ex. AWS, Vercel, Heroku, etc.).

Checkout Handler

Customer Portal

Webhooks

​Installation

​Exempel på Routhanterare

​Kassa Routhanterare

​Supported Query Parameters

​Svarsformat

​Svarsformat

​Svarsformat

​Kundportal Routhanterare

​Query Parameters

​Webhook Routhanterare

​Supported Webhook Event Handlers

​Prompt för LLM

Installation

Exempel på Routhanterare

Kassa Routhanterare

Supported Query Parameters

Svarsformat

Svarsformat

Svarsformat

Kundportal Routhanterare

Query Parameters

Webhook Routhanterare

Supported Webhook Event Handlers

Prompt för LLM