Översikt

Den Better Auth Adapter för Dodo Payments erbjuder:

Automatisk kundskapande vid registrering
Checkout Sessions (föredraget) med produkt-slug-mappning
Självbetjäningsportal för kunder
Metered usage-ingestion och rapporteringsändpunkter för användningsbaserad fakturering
Realtids-webhook-händelsebehandling med signaturverifiering
Full TypeScript-stöd

Du behöver ett Dodo Payments-konto och API-nycklar för att använda denna integration.

Förutsättningar

Node.js 20+
Tillgång till din Dodo Payments Dashboard
Befintligt projekt som använder better-auth

Installation

Install dependencies

Kör följande kommando i projektets rotmapp:

npm install @dodopayments/better-auth dodopayments better-auth zod

Alla nödvändiga paket är nu installerade.

Konfiguration

Configure environment variables

Lägg till dessa i din .env-fil:

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your_better_auth_secret_here

Förekom aldrig att commita API-nycklar eller hemligheter till versionskontrollen.

Set up server-side integration

Skapa eller uppdatera src/lib/auth.ts:

import { betterAuth } from "better-auth";
import {
  dodopayments,
  checkout,
  portal,
  webhooks,
  usage,
} from "@dodopayments/better-auth";
import DodoPayments from "dodopayments";

export const dodoPayments = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
  environment: "test_mode", // or "live_mode" for production
});

export const { auth, endpoints, client } = BetterAuth({
  plugins: [
    dodopayments({
      client: dodoPayments,
      createCustomerOnSignUp: true,
      use: [
        checkout({
          products: [
            {
              productId: "pdt_xxxxxxxxxxxxxxxxxxxxx",
              slug: "premium-plan",
            },
          ],
          successUrl: "/dashboard/success",
          authenticatedUsersOnly: true,
        }),
        portal(),
        webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
          onPayload: async (payload) => {
            console.log("Received webhook:", payload.event_type);
          },
        }),
        usage(),
      ],
    }),
  ],
});

Ange environment till live_mode för produktion.

Set up client-side integration

Skapa eller uppdatera src/lib/auth-client.ts:

import { createAuthClient } from "better-auth/react";
import { dodopaymentsClient } from "@dodopayments/better-auth/client";

export const authClient = createAuthClient({
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
  plugins: [dodopaymentsClient()],
});

Användningsexempel

Föredra authClient.dodopayments.checkoutSession för nya integrationer. Den äldre checkout-metoden är avskriven och finns kvar endast för bakåtkompatibilitet.

Skapa en Checkout Session (Föredraget)

const { data: session, error } = await authClient.dodopayments.checkoutSession({
  // Option A: use a configured slug
  slug: "premium-plan",

// Your internal id for reference
referenceId: "order_123",
});

if (session) {
window.location.href = session.url;
}

const { data: session, error } = await authClient.dodopayments.checkoutSession({
  // Option B: pass a product cart/product id directly
  product_cart: [
    {
      product_id: "pdt_xxxxxxxxxxxxxxxxxxxxx",
      quantity: 1,
    }
  ],

  // Your internal id for reference
  referenceId: "order_123",
});

if (session) {
  window.location.href = session.url;
}

Till skillnad från den äldre checkout-metoden kräver checkoutSession inte faktureringsinformation i förväg eftersom detta tas från användaren på kassasidan. Du kan fortfarande åsidosätta detta genom att skicka billing-nyckeln i argumentet.

Precis som den äldre checkout-metoden hämtar checkoutSession kundens e-post och namn från deras better-auth-session, men du kan åsidosätta det genom att skicka customer-objektet med e-post och namn.

Du kan skicka samma alternativ i argumentet som i begäran till Create Checkout Session slutpunkt.

Returneringsadressen tas från successUrl som konfigurerats i server-pluginet. Du behöver inte inkludera return_url i klientens payload.

Äldre Checkout (Avvecklad)

Metoden authClient.dodopayments.checkout är avskriven. Använd checkoutSession istället för nya implementationer.

const { data: checkout, error } = await authClient.dodopayments.checkout({
  slug: "premium-plan",
  customer: {
    email: "customer@example.com",
    name: "John Doe",
  },
  billing: {
    city: "San Francisco",
    country: "US",
    state: "CA",
    street: "123 Market St",
    zipcode: "94103",
  },
  referenceId: "order_123",
});

if (checkout) {
  window.location.href = checkout.url;
}

Åtkomst till kundportalen

const { data: customerPortal, error } =
  await authClient.dodopayments.customer.portal();
if (customerPortal && customerPortal.redirect) {
  window.location.href = customerPortal.url;
}

Lista kunddata

// Get subscriptions
const { data: subscriptions, error } =
  await authClient.dodopayments.customer.subscriptions.list({
    query: {
      limit: 10,
      page: 1,
      status: "active",
    },
  });

// Get payment history
const { data: payments, error } =
  await authClient.dodopayments.customer.payments.list({
    query: {
      limit: 10,
      page: 1,
      status: "succeeded",
    },
  });

Spåra mätanvändning

Aktivera usage()-pluginet på servern för att fånga mätade händelser och låta kunder inspektera sin användningsbaserade fakturering.

authClient.dodopayments.usage.ingest tar emot händelser för den inloggade, e-postverifierade användaren.
authClient.dodopayments.usage.meters.list listar senaste användningen för de mätare som är kopplade till den kundens prenumerationer.

// Record a metered event (e.g., an API request)
const { error: ingestError } = await authClient.dodopayments.usage.ingest({
  event_id: crypto.randomUUID(),
  event_name: "api_request",
  metadata: {
    route: "/reports",
    method: "GET",
  },
  // Optional Date; defaults to now if omitted
  timestamp: new Date(),
});

if (ingestError) {
  console.error("Failed to record usage", ingestError);
}

// List recent usage for the current customer
const { data: usage, error: usageError } =
  await authClient.dodopayments.usage.meters.list({
    query: {
      page_size: 20,
      meter_id: "mtr_yourMeterId", // optional
    },
  });

if (usage?.items) {
  usage.items.forEach((event) => {
    console.log(event.event_name, event.timestamp, event.metadata);
  });
}

Tidsstämplar äldre än en timme eller mer än fem minuter framåt i tiden avvisas när användning registreras.

Om du utelämnar meter_id när du listar användningsmätare returneras alla mätare som är kopplade till kundens prenumerationer.

Webhooks

Webhooks-pluginen bearbetar realtidsbetalningshändelser från Dodo Payments med säker signaturverifiering. Standard-slutpunkten är /api/auth/dodopayments/webhooks.

Generate and set webhook secret

Generera en webhook-hemlighet för din slutpunkt (t.ex. https://<your-domain>/api/auth/dodopayments/webhooks) i Dodo Payments Dashboard och ange den i din .env-fil:

DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here

Handle webhook events

Exempelhanterare:

webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
  onPayload: async (payload) => {
    console.log("Received webhook:", payload.event_type);
  },
});

Stödda Webhook Hä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>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

Konfigurationsreferens

Plugin Options

client (obligatorisk): DodoPayments klientinstans
createCustomerOnSignUp (valfri): Skapa automatiskt kunder vid användarregistrering
use (obligatorisk): Lista med plugins att aktivera (checkout, portal, användning, webhooks)
getCustomerParams (valfri): Funktion som tar emot BetterAuth User och returnerar extra fält som ska bifogas DodoPayments-kunden vid skapande och uppdatering (t.ex. metadata, phone_number)

dodopayments({
  client: dodoPayments,
  createCustomerOnSignUp: true,
  use: [portal()],
  getCustomerParams: (user) => ({
    metadata: { userId: user.id },
    phone_number: user.phoneNumber ?? null,
  }),
})

Checkout Plugin Options

products: Lista med produkter eller asynkron funktion som returnerar produkter - successUrl: URL att omdirigera till efter lyckad betalning - authenticatedUsersOnly: Kräver användarautentisering (standard: false)

Felsökning och tips

Common Issues

Ogiltig API-nyckel: Kontrollera din DODO_PAYMENTS_API_KEY i .env. - Webhook-signaturfel: Se till att webhook-hemligheten matchar den som är inställd i Dodo Payments Dashboard. - Kund inte skapad: Bekräfta createCustomerOnSignUp är satt till true.

Best Practices

Använd miljövariabler för alla hemligheter och nycklar. - Testa i test_mode innan du byter till live_mode. - Logga webhook-händelser för felsökning och revision.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Better-Auth Adapter

Översikt

Förutsättningar

Installation

Konfiguration

Användningsexempel

Skapa en Checkout Session (Föredraget)

Äldre Checkout (Avvecklad)

Åtkomst till kundportalen

Lista kunddata

Spåra mätanvändning

Webhooks

Stödda Webhook Händelsehanterare

Konfigurationsreferens

Felsökning och tips

​Översikt

​Förutsättningar

​Installation

​Konfiguration

​Användningsexempel

​Skapa en Checkout Session (Föredraget)

​Äldre Checkout (Avvecklad)

​Åtkomst till kundportalen

​Lista kunddata

​Spåra mätanvändning

​Webhooks

​Stödda Webhook Händelsehanterare

​Konfigurationsreferens

​Felsökning och tips

Översikt

Förutsättningar

Installation

Konfiguration

Användningsexempel

Skapa en Checkout Session (Föredraget)

Äldre Checkout (Avvecklad)

Åtkomst till kundportalen

Lista kunddata

Spåra mätanvändning

Webhooks

Stödda Webhook Händelsehanterare

Konfigurationsreferens

Felsökning och tips