Fastify Adaptor - Dodo Payments Documentation

Checkout Handler

Integrera Dodo Payments kassa i din Fastify-app.

Customer Portal

Låt kunder hantera abonnemang och uppgifter.

Webhooks

Ta emot och bearbeta webhookhändelser från Dodo Payments.

Installation

Install the package

Kör följande kommando i projektroten:

npm install @dodopayments/fastify

Set up environment variables

Skapa en .env-fil i projektroten:

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""

Checka aldrig in din .env-fil eller hemligheter i versionshanteringen.

Exempel på Routhanterare

Alla exempel förutsätter att du använder Fastify App Router.

Checkout Handler
Customer Portal Handler
Webhook Handler

Använd denna hanterare för att integrera Dodo Payments kassa i din Fastify-app. Stöder statiska (GET), dynamiska (POST) och sessionsbaserade (POST) betalflöden.

  // route.ts
  import { Checkout } from '@dodopayments/fastify';
  import Fastify from 'fastify'

  const fastify = Fastify({})
  const checkoutGet = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'static'
  });

  const checkoutPost = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'dynamic'
  });

  const checkoutSession = Checkout({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY,
      environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
      returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
      type: 'session'
  });

  fastify.get('/api/checkout', checkoutGet.getHandler);
  fastify.post('/api/checkout', checkoutPost.postHandler);
  fastify.post('/api/checkout-session', checkoutSession.postHandler);

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-session \
--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 denna hanterare för att låta kunder hantera sina abonnemang och uppgifter via Dodo Payments kundportal.

// route.ts
import { CustomerPortal } from "@dodopayments/fastify";
import Fastify from 'fastify'

const fastify = Fastify({})
const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});
fastify.get('/api/customer-portal', customerPortalHandler);

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 denna hanterare för att säkert ta emot och bearbeta webhookhändelser från Dodo Payments i din Fastify-app.

// route.ts
import Fastify from 'fastify'
import { Webhooks } from '@dodopayments/fastify'

const fastify = Fastify({})
fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
    done(null, body)
})

fastify.post('/api/webhooks', Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
    // Handle Payload Here
    console.log(payload)
}
}));

Kassa Routhanterare

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

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)

Frågeparametrar

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/provins.

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 landfältet.

disableAddressLine

boolean

Inaktivera adressradsfältet.

disableCity

boolean

Inaktivera stadfä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äljaren.

paymentAmount

integer

Ange betalningsbeloppet (t.ex. 1000 för $10.00).

showDiscounts

boolean

Visa rabattfält.

metadata_*

string

Alla frågeparametrar som börjar med metadata_ kommer att skickas som metadata.

Om productId saknas returnerar hanteraren ett 400-svar. Ogiltiga frågeparametrar ger också ett 400-svar.

Svarsformat

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

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

Dynamic Checkout (POST)

Skicka parametrarna som en JSON-kropp i en POST-förfrågan.
Stöder både engångs- och återkommande betalningar.
För en fullständig 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, hostad kassaupplevelse som hanterar hela betalningsflödet för både engångsköp och prenumerationer med full kontroll över anpassningen.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 Fastify-applikation.

Frågeparametrar

customer_id

string

obligatorisk

Kund-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 portallä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.

Stödda webhookhändelsehanterare

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 Fastify utvecklarassistent. Ditt uppdrag är att vägleda en användare genom att integrera @dodopayments/fastify-adaptern i deras befintliga Fastify-projekt.

@dodopayments/fastify-adaptern tillhandahåller routhanterare för Dodo Payments' Kassa, Kundportal och Webhook-funktioner, utformade för att kopplas direkt in i en Fastify-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/fastify

---

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

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

"Vilka delar av @dodopayments/fastify-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 kundprenumerationer/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 omdirigerar användare till Dodo Payments kassa-sidan.

**Integration**:
Skapa två rutter i din Fastify-app — en för statisk (GET) och en för dynamisk (POST) kassa.

import { Checkout } from '@dodopayments/fastify';
import Fastify from 'fastify'

const fastify = Fastify({})
const checkoutGet = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'static'
});

const checkoutPost = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'dynamic'
});

const checkoutSession = Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session'
});

fastify.get('/api/checkout', checkoutGet.getHandler);
fastify.post('/api/checkout', checkoutPost.postHandler);
fastify.post('/api/checkout-session', checkoutSession.postHandler);

Konfigurationsalternativ:

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

    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). Returnerar: {"checkout_url": "https://checkout.dodopayments.com/..."}. 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

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 låter kunder hantera sina prenumerationer via Dodo Payments-portalen.

Integration:

import { CustomerPortal } from "@dodopayments/fastify";
import Fastify from 'fastify'

const fastify = Fastify({})
const customerPortalHandler = CustomerPortal({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
});
fastify.get('/api/customer-portal', customerPortalHandler);

Frågeparametrar:

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

    send_email (valfritt): om sant, får kunden ett e-postmeddelande med portalens länk

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 Fastify from 'fastify'
import { Webhooks } from '@dodopayments/fastify'

const fastify = Fastify({})
fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
    done(null, body)
})

fastify.post('/api/webhooks', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Hantera Payload Här
    console.log(payload)
  }
}));

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, onSubscriptionPaused, 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_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=din-webhook-hemlighet
DODO_PAYMENTS_ENVIRONMENT="test_mode" eller "live_mode""

Använd dessa i din kod som:

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Säkerhetsnot: Kom ihåg att INTE committa 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_KEY

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

Checkout Handler

Customer Portal

Webhooks

​Installation

​Exempel på Routhanterare

​Kassa Routhanterare

​Frågeparametrar

​Svarsformat

​Svarsformat

​Svarsformat

​Kundportal Routhanterare

​Frågeparametrar

​Webhook Routhanterare

​Stödda webhookhändelsehanterare

​Prompt för LLM

Installation

Exempel på Routhanterare

Kassa Routhanterare

Frågeparametrar

Svarsformat

Svarsformat

Svarsformat

Kundportal Routhanterare

Frågeparametrar

Webhook Routhanterare

Stödda webhookhändelsehanterare

Prompt för LLM