Overlay Checkout - Dodo Payments Documentation

Översikt

Dodo Payments Checkout SDK erbjuder ett sömlöst sätt att integrera vår betalningsoverlay i din webbapplikation. Byggd med TypeScript och moderna webbstandarder, erbjuder den en robust lösning för att hantera betalningar med realtids-händelsehantering och anpassningsbara teman.

Demo

Interactive Demo

Se överläggskassan i aktion med vår live-demo.

Snabbstart

Kom igång med Dodo Payments Checkout SDK på bara några rader kod:

import { DodoPayments } from "dodopayments-checkout";

// Initialize the SDK
DodoPayments.Initialize({
  mode: "test", // 'test' or 'live'
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
  },
});

// Open checkout
DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Hämta din checkout-URL från create checkout session API.

Steg-för-steg Integrationsguide

Install the SDK

Installera Dodo Payments Checkout SDK med din föredragna paketförvaltare:

npm install dodopayments-checkout

Initialize the SDK

Initiera SDK:n i din applikation, vanligtvis i din huvudkomponent eller appens ingångspunkt:

import { DodoPayments } from "dodopayments-checkout";

DodoPayments.Initialize({
  mode: "test", // Change to 'live' for production
  displayType: "overlay", // Optional: defaults to 'overlay' for overlay checkout
  onEvent: (event) => {
    console.log("Checkout event:", event);
    
    // Handle different events
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.error":
        // Handle errors
        console.error("Checkout error:", event.data?.message);
        break;
    }
  },
});

Initiera alltid SDK:n innan du försöker öppna kassan. Initiering ska ske en gång när din applikation laddas.

Create a Checkout Button Component

Skapa en komponent som öppnar checkout-overlayen:

// components/CheckoutButton.tsx
"use client";

import { Button } from "@/components/ui/button";
import { DodoPayments } from "dodopayments-checkout";
import { useEffect, useState } from "react";

export function CheckoutButton() {
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    // Initialize the SDK
    DodoPayments.Initialize({
      mode: "test",
      displayType: "overlay",
      onEvent: (event) => {
        switch (event.event_type) {
          case "checkout.opened":
            setIsLoading(false);
            break;
          case "checkout.error":
            setIsLoading(false);
            console.error("Checkout error:", event.data?.message);
            break;
        }
      },
    });
  }, []);

  const handleCheckout = async () => {
    try {
      setIsLoading(true);
      await DodoPayments.Checkout.open({
        checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
      });
    } catch (error) {
      console.error("Failed to open checkout:", error);
      setIsLoading(false);
    }
  };

  return (
    <Button 
      onClick={handleCheckout}
      disabled={isLoading}
    >
      {isLoading ? "Loading..." : "Checkout Now"}
    </Button>
  );
}

Add Checkout to Your Page

Använd checkout-knappskomponenten i din applikation:

// app/page.tsx
import { CheckoutButton } from "@/components/CheckoutButton";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1>Welcome to Our Store</h1>
      <CheckoutButton />
    </main>
  );
}

Handle Success and Failure Pages

Skapa sidor för att hantera checkout-omdirigeringar:

// app/success/page.tsx
export default function SuccessPage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Successful!</h1>
      <p>Thank you for your purchase.</p>
    </div>
  );
}

// app/failure/page.tsx
export default function FailurePage() {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      <h1>Payment Failed</h1>
      <p>Please try again or contact support.</p>
    </div>
  );
}

Test Your Integration

Starta din utvecklingsserver:

npm run dev

Testa checkout-flödet:
- Klicka på checkout-knappen
- Verifiera att overlayen visas
- Testa betalningsflödet med testuppgifter
- Bekräfta att omdirigeringar fungerar korrekt

Du bör se kassahändelser loggas i din webbläsares konsol.

Go Live

När du är redo för produktion:

Ändra läget till 'live':

DodoPayments.Initialize({
  mode: "live",
  displayType: "overlay",
  onEvent: (event) => {
    console.log("Checkout event:", event);
  }
});

Uppdatera dina checkout-URL:er för att använda live checkout-sessioner från din backend
Testa hela flödet i produktion
Övervaka händelser och fel

API Referens

Konfiguration

Initieringsalternativ

interface InitializeOptions {
  mode: "test" | "live";
  displayType?: "overlay" | "inline";
  onEvent: (event: CheckoutEvent) => void;
}

Alternativ	Typ	Obligatorisk	Beskrivning
`mode`	`"test" \| "live"`	Ja	Miljöläge: `'test'` för utveckling, `'live'` för produktion
`displayType`	`"overlay" \| "inline"`	Nej	Visningstyp: `'overlay'` för modal kassa (standard), `'inline'` för inbäddad kassa
`onEvent`	`function`	Ja	Callback-funktion för att hantera kassahändelser

Checkout-alternativ

interface CheckoutOptions {
  checkoutUrl: string;
  options?: {
    showTimer?: boolean;
    showSecurityBadge?: boolean;
    manualRedirect?: boolean;
  };
}

Alternativ	Typ	Obligatorisk	Beskrivning
`checkoutUrl`	`string`	Ja	Checkout-sessionens URL från create checkout session API
`options.showTimer`	`boolean`	Nej	Visa eller dölj kassatimerna. Som standard är `true`. När den är inaktiverad får du `checkout.link_expired`-händelsen när sessionen löper ut.
`options.showSecurityBadge`	`boolean`	Nej	Visa eller dölj säkerhetsmärket. Som standard är `true`.
`options.manualRedirect`	`boolean`	Nej	När det är aktiverat kommer kassan inte automatiskt att omdirigera efter slutförandet. Istället får du `checkout.status`- och `checkout.redirect_requested`-händelser för att hantera omdirigeringen själv.

Metoder

Öppna Checkout

Öppnar checkout-overlayen med den angivna checkout-session-URL:en.

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
});

Du kan också skicka ytterligare alternativ för att anpassa checkout-beteendet:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: false,
    showSecurityBadge: false,
    manualRedirect: true,
  },
});

När du använder manualRedirect, hantera kassans slutförande i din onEvent-callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event) => {
    if (event.event_type === "checkout.status") {
      const status = event.data?.message?.status;
      // Handle status: "succeeded", "failed", or "processing"
    }
    if (event.event_type === "checkout.redirect_requested") {
      const redirectUrl = event.data?.message?.redirect_to;
      // Redirect the customer manually
      window.location.href = redirectUrl;
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
    }
  },
});

Stäng Checkout

Stänger programatiskt checkout-overlay.

DodoPayments.Checkout.close();

Kontrollera Status

Returnerar om checkout-overlay för närvarande är öppen.

const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean

Händelser

SDK:n tillhandahåller realtidshändelser som du kan lyssna på via onEvent-callbacken:

Checkout Status Händelsedata

När manualRedirect är aktiverat får du checkout.status-händelsen med följande data:

interface CheckoutStatusEventData {
  message: {
    status?: "succeeded" | "failed" | "processing";
  };
}

Checkout Omdirigering Begärd Händelsedata

När manualRedirect är aktiverat får du checkout.redirect_requested-händelsen med följande data:

interface CheckoutRedirectRequestedEventData {
  message: {
    redirect_to?: string;
  };
}

DodoPayments.Initialize({
  onEvent: (event: CheckoutEvent) => {
    switch (event.event_type) {
      case "checkout.opened":
        // Checkout overlay has been opened
        break;
      case "checkout.form_ready":
        // Checkout form is ready for user input
        break;
      case "checkout.payment_page_opened":
        // Payment page has been displayed
        break;
      case "checkout.customer_details_submitted":
        // Customer and billing details submitted
        break;
      case "checkout.closed":
        // Checkout has been closed
        break;
      case "checkout.redirect":
        // Checkout will perform a redirect
        break;
      case "checkout.error":
        // An error occurred
        console.error("Error:", event.data?.message);
        break;
      case "checkout.link_expired":
        // Checkout session has expired (only when showTimer is false)
        break;
      case "checkout.status":
        // Checkout status update (only when manualRedirect is enabled)
        const status = event.data?.message?.status;
        break;
      case "checkout.redirect_requested":
        // Redirect requested (only when manualRedirect is enabled)
        const redirectUrl = event.data?.message?.redirect_to;
        break;
    }
  }
});

Händelsetyp	Beskrivning
`checkout.opened`	Checkout-överlägget har öppnats
`checkout.form_ready`	Checkout-formuläret är redo att ta emot användarinmatning. Användbart för att dölja laddningslägen.
`checkout.payment_page_opened`	Betalningssidan har visats
`checkout.customer_details_submitted`	Kund- och faktureringsuppgifter har skickats in
`checkout.closed`	Checkout-överlägget har stängts
`checkout.redirect`	Kassa kommer att utföra en omdirigering
`checkout.error`	Ett fel inträffade under kassan
`checkout.link_expired`	Utlöses när checkout-sessionen löper ut. Tas endast emot när `showTimer` är satt till `false`.
`checkout.status`	Utlöses när `manualRedirect` är aktiverat. Innehåller kassan status (`succeeded`, `failed` eller `processing`).
`checkout.redirect_requested`	Utlöses när `manualRedirect` är aktiverat. Innehåller URL:en som kunden ska omdirigeras till.

Implementeringsalternativ

Paketmanagerinstallation

Installera via npm, yarn eller pnpm som visas i Steg-för-steg integrationsguiden.

CDN-implementering

För snabb integration utan byggsteg kan du använda vår CDN:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dodo Payments Checkout</title>
    
    <!-- Load DodoPayments -->
    <script src="https://cdn.jsdelivr.net/npm/dodopayments-checkout@latest/dist/index.js"></script>
    <script>
        // Initialize the SDK
        DodoPaymentsCheckout.DodoPayments.Initialize({
            mode: "test", // Change to 'live' for production
            displayType: "overlay",
            onEvent: (event) => {
                console.log('Checkout event:', event);
            }
        });
    </script>
</head>
<body>
    <button onclick="openCheckout()">Checkout Now</button>

    <script>
        function openCheckout() {
            DodoPaymentsCheckout.DodoPayments.Checkout.open({
                checkoutUrl: "https://checkout.dodopayments.com/session/cks_123"
            });
        }
    </script>
</body>
</html>

Temaanpassning

Du kan anpassa kassans utseende genom att skicka ett themeConfig-objekt i options-parametern när du öppnar kassan. Temakonfigurationen stödjer både ljusa och mörka lägen, vilket låter dig anpassa färger, kanter, text, knappar och hörnradie.

Detta avsnitt täcker klientside tema-konfiguration med Checkout SDK. Du kan också konfigurera teman serverside när du skapar en checkout-session via API:et med hjälp av parametern theme_config. Se Checkout Theme Customization för API-nivåkonfiguration, eller använd Design page i kontrollpanelen för att konfigurera teman visuellt med liveförhandsvisning.

Grundläggande temakonfiguration

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#344054",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

Komplett temakonfiguration

Alla tillgängliga temaeigenskaper:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        // Background colors
        bgPrimary: "#FFFFFF",        // Primary background color
        bgSecondary: "#F9FAFB",      // Secondary background color (e.g., tabs)
        
        // Border colors
        borderPrimary: "#D0D5DD",     // Primary border color
        borderSecondary: "#6B7280",  // Secondary border color
        
        // Text colors
        textPrimary: "#344054",       // Primary text color
        textSecondary: "#6B7280",    // Secondary text color
        textPlaceholder: "#667085",  // Placeholder text color
        textError: "#D92D20",        // Error text color
        textSuccess: "#10B981",      // Success text color
        
        // Button colors
        buttonPrimary: "#A6E500",           // Primary button background
        buttonPrimaryHover: "#8CC500",      // Primary button hover state
        buttonTextPrimary: "#0D0D0D",       // Primary button text color
        buttonSecondary: "#F3F4F6",         // Secondary button background
        buttonSecondaryHover: "#E5E7EB",     // Secondary button hover state
        buttonTextSecondary: "#344054",     // Secondary button text color
      },
      dark: {
        // Background colors
        bgPrimary: "#0D0D0D",
        bgSecondary: "#1A1A1A",
        
        // Border colors
        borderPrimary: "#323232",
        borderSecondary: "#D1D5DB",
        
        // Text colors
        textPrimary: "#FFFFFF",
        textSecondary: "#909090",
        textPlaceholder: "#9CA3AF",
        textError: "#F97066",
        textSuccess: "#34D399",
        
        // Button colors
        buttonPrimary: "#A6E500",
        buttonPrimaryHover: "#8CC500",
        buttonTextPrimary: "#0D0D0D",
        buttonSecondary: "#2A2A2A",
        buttonSecondaryHover: "#3A3A3A",
        buttonTextSecondary: "#FFFFFF",
      },
      radius: "8px", // Border radius for inputs, buttons, and tabs
    },
  },
});

Endast ljus läge

Om du bara vill anpassa det ljusa temat:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        textPrimary: "#000000",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Endast mörkt läge

Om du bara vill anpassa det mörka temat:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      dark: {
        bgPrimary: "#000000",
        textPrimary: "#FFFFFF",
        buttonPrimary: "#0070F3",
      },
      radius: "12px",
    },
  },
});

Delvis temainställning

Du kan skriva över endast specifika egenskaper. Kassa använder standardvärden för egenskaper du inte anger:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    themeConfig: {
      light: {
        buttonPrimary: "#FF6B6B", // Only override primary button color
      },
      radius: "16px", // Override border radius
    },
  },
});

Temakonfiguration med andra alternativ

Du kan kombinera temakonfiguration med andra kassaalternativ:

DodoPayments.Checkout.open({
  checkoutUrl: "https://checkout.dodopayments.com/session/cks_123",
  options: {
    showTimer: true,
    showSecurityBadge: true,
    manualRedirect: false,
    themeConfig: {
      light: {
        bgPrimary: "#FFFFFF",
        buttonPrimary: "#A6E500",
      },
      dark: {
        bgPrimary: "#0D0D0D",
        buttonPrimary: "#A6E500",
      },
      radius: "8px",
    },
  },
});

TypeScript-typer

För TypeScript-användare exporteras alla temakonfigurationstyper:

import { ThemeConfig, ThemeModeConfig } from "dodopayments-checkout";

const themeConfig: ThemeConfig = {
  light: {
    bgPrimary: "#FFFFFF",
    // ... other properties
  },
  dark: {
    bgPrimary: "#0D0D0D",
    // ... other properties
  },
  radius: "8px",
};

Felhantering

SDK:n tillhandahåller detaljerad felinformation genom händelsesystemet. Implementera alltid korrekt felhantering i din onEvent-callback:

DodoPayments.Initialize({
  mode: "test",
  displayType: "overlay",
  onEvent: (event: CheckoutEvent) => {
    if (event.event_type === "checkout.error") {
      console.error("Checkout error:", event.data?.message);
      // Handle error appropriately
      // You may want to show a user-friendly error message
      // or retry the checkout process
    }
    if (event.event_type === "checkout.link_expired") {
      // Handle expired checkout session
      console.warn("Checkout session has expired");
    }
  }
});

Hantera alltid checkout.error-händelsen för att ge en bra användarupplevelse när fel uppstår.

Bästa praxis

Initiera endast en gång: Initiera SDK:n en gång när din applikation laddas, inte vid varje försök att öppna kassan
Felhantering: Implementera alltid korrekt felhantering i din event-callback
Testläge: Använd test-läget under utveckling och växla till live först när du är redo för produktion
Händelsehantering: Hantera alla relevanta händelser för en komplett användarupplevelse
Giltiga URL:er: Använd alltid giltiga checkout-URL:er från create checkout session API
TypeScript: Använd TypeScript för bättre typkontroll och utvecklarupplevelse
Laddningstillstånd: Visa laddningstillstånd medan kassan öppnas för att förbättra UX
Manuella omdirigeringar: Använd manualRedirect när du behöver anpassad kontroll över navigeringen efter kassan
Timerhantering: Inaktivera timern (showTimer: false) om du vill hantera sessionens utgång manuellt

Felsökning

Checkout not opening

Möjliga orsaker:

SDK:n initierades inte innan open() kallades
Ogiltig checkout-URL
JavaScript-fel i konsolen
Nätverksanslutningsproblem

Lösningar:

Verifiera att SDK-initiering sker innan kassan öppnas
Kontrollera konsolfel
Säkerställ att checkout-URL är giltig och kommer från create checkout session API
Kontrollera nätverksanslutning

Events not firing

Möjliga orsaker:

Händelsehanteraren är inte korrekt konfigurerad
JavaScript-fel som hindrar händelsepropagering
SDK:n initierades inte korrekt

Lösningar:

Bekräfta att händelsehanteraren är korrekt konfigurerad i Initialize()
Kontrollera webbläsarens konsol efter JavaScript-fel
Verifiera att SDK-initieringen slutfördes framgångsrikt
Testa först med en enkel händelsehanterare

Styling issues

Möjliga orsaker:

CSS-konflikter med din applikations stilar
Temainställningarna tillämpas inte korrekt
Responsiva designproblem

Lösningar:

Kontrollera CSS-konflikter i webbläsarens DevTools
Verifiera att temainställningarna är korrekta
Testa på olika skärmstorlekar
Se till att det inte finns z-index-konflikter med överlägget

Aktivera digitala plånböcker

För detaljerad information om hur du ställer in Google Pay och andra digitala plånböcker, se sidan Digital Wallets.

Apple Pay stöds ännu inte i överläggskassan. Stöd för Apple Pay kommer snart.

Webbläsarstöd

Dodo Payments Checkout SDK stöder följande webbläsare:

Chrome (senaste)
Firefox (senaste)
Safari (senaste)
Edge (senaste)
IE11+

Överläggskassa vs inline-kassa

Välj rätt kassamodell för ditt användningsfall:

Funktion	Överläggskassa	Inline-kassa
Integrationsdjup	Modal ovanpå sidan	Fullt inbäddad i sidan
Layouthantering	Begränsad	Full kontroll
Varumärkesprofil	Separat från sidan	Sömlös
Implementationsinsats	Lägre	Högre
Bäst för	Snabb integration, befintliga sidor	Anpassade kassasidor, högkonverterande flöden

Använd överläggskassan för snabbare integration med minimala ändringar på dina befintliga sidor. Använd inline-kassan när du vill ha maximal kontroll över kassaupplevelsen och sömlös varumärkesprofil.

Relaterade resurser

Inline Checkout

Bädda in kassan direkt på din sida för helt integrerade upplevelser.

Checkout Sessions API

Skapa checkout-sessioner för att driva dina kassaupplevelser.

Webhooks

Hantera betalningshändelser på serversidan med webhooks.

Integration Guide

Fullständig guide till att integrera Dodo Payments.

För mer hjälp, besök vår Discord-community eller kontakta vårt utvecklarstödteam.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Översikt

​Demo

Interactive Demo

​Snabbstart

​Steg-för-steg Integrationsguide

​API Referens

​Konfiguration

​Initieringsalternativ

​Checkout-alternativ

​Metoder

​Öppna Checkout

​Stäng Checkout

​Kontrollera Status

​Händelser

​Checkout Status Händelsedata

​Checkout Omdirigering Begärd Händelsedata

​Implementeringsalternativ

​Paketmanagerinstallation

​CDN-implementering

​Temaanpassning

​Grundläggande temakonfiguration

​Komplett temakonfiguration

​Endast ljus läge

​Endast mörkt läge

​Delvis temainställning

​Temakonfiguration med andra alternativ

​TypeScript-typer

​Felhantering

​Bästa praxis

​Felsökning

​Aktivera digitala plånböcker

​Webbläsarstöd

​Överläggskassa vs inline-kassa

​Relaterade resurser

Inline Checkout

Checkout Sessions API

Webhooks

Integration Guide

Översikt

Demo

Snabbstart

Steg-för-steg Integrationsguide

API Referens

Konfiguration

Initieringsalternativ

Checkout-alternativ

Metoder

Öppna Checkout

Stäng Checkout

Kontrollera Status

Händelser

Checkout Status Händelsedata

Checkout Omdirigering Begärd Händelsedata

Implementeringsalternativ

Paketmanagerinstallation

CDN-implementering

Temaanpassning

Grundläggande temakonfiguration

Komplett temakonfiguration

Endast ljus läge

Endast mörkt läge

Delvis temainställning

Temakonfiguration med andra alternativ

TypeScript-typer

Felhantering

Bästa praxis

Felsökning

Aktivera digitala plånböcker

Webbläsarstöd

Överläggskassa vs inline-kassa

Relaterade resurser