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

yarn add dodopayments-checkout

pnpm add 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;
  };
}

Alternativ	Typ	Obligatorisk	Beskrivning
`checkoutUrl`	`string`	Ja	Kassa session URL från create checkout session API
`options.showTimer`	`boolean`	Nej	Visa eller dölj kassatimer. Standard är `true`. När inaktiverad, får du eventet `checkout.link_expired` när sessionen går ut.
`options.showSecurityBadge`	`boolean`	Nej	Visa eller dölj säkerhetsmärket. Standard är `true`.

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

Stäng Kassa

Stänger programatiskt kassaöverlägget.

DodoPayments.Checkout.close();

Kontrollera Status

Returnerar om kassaöverlägget för närvarande är öppet.

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

Händelser

SDK:et tillhandahåller realtids händelser som du kan lyssna på genom callbacken onEvent:

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

Händelsetyp	Beskrivning
`checkout.opened`	Kassaöverlägget har öppnats
`checkout.form_ready`	Kassans formulär är redo att ta emot användarinmatning. Användbart för att dölja laddningstillstånd.
`checkout.payment_page_opened`	Betalningssidan har visats
`checkout.customer_details_submitted`	Kund- och faktureringsdetaljer har skickats in
`checkout.closed`	Kassaö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`	Aktiveras när kassa sessionen går ut. Endast mottaget när `showTimer` är inställd på `false`.

Implementeringsalternativ

Installation via Paket Manager

Installera via npm, yarn eller pnpm enligt Steg-för-Steg Integrationsguiden.

CDN-Implementation

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 kassaens utseende genom att föra vidare ett objekt themeConfig i parametern options när kassan öppnas. Temakonfigurationen stöder både ljusa och mörka lägen, vilket tillåter dig att anpassa färger, kanter, text, knappar och kantbredder.

Denna sektion täcker klient-sida tema konfiguration som använder Kassa SDK. Du kan också konfigurera teman server-sida när du skapar en kassa session via API:et med parametern theme_config. Se Kassa Temaanpassning för API-nivå konfiguration, eller använd Designsidan i instrumentpanelen för att visuellt konfigurera teman med livepreview.

Grundläggande Tema Konfiguration

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

Fullständig Tema Konfiguration

Alla tillgängliga temeegenskaper:

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 Ljust Läge

Om du endast 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 endast 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 Tema Överskrivning

Du kan överskrida endast specifika egenskaper. Kassaen kommer att använda standardvärden för egenskaper du inte specificerar:

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

Teme Konfiguration 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,
    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:et tillhandahåller detaljerad felinformation genom händelsesystemet. Implementera alltid korrekt felhantering i din callback onEvent:

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 eventet checkout.error för att ge en bra användarupplevelse när fel inträffar.

Bästa Praxis

Initiera en gång: Initiera SDK:et en gång när din applikation laddas, inte vid varje kassa försök
Felhantering: Implementera alltid korrekt felhantering i din händelsecallback
Testläge: Använd test läge 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 URLs: Använd alltid giltiga kassa URLs från create checkout session API
TypeScript: Använd TypeScript för bättre typsäkerhet och utvecklarupplevelse
Laddningstillstånd: Visa laddningstillstånd medan kassan öppnas för att förbättra UX
Timer hantering: Inaktivera timern (showTimer: false) om du vill hantera sessionens utgångsdatum manuellt

Felsökning

Checkout not opening

Möjliga orsaker:

SDK inte initierad före anrop av open()
Ogiltig kassa URL
JavaScript-fel i konsolen
Nätverksanslutningsproblem

Lösningar:

Verifiera att SDK-initieringen sker innan kassan öppnas
Kontrollera konsolens fel
Säkerställ att kassa URL är giltig och kommer från create checkout session API
Verifiera nätverksanslutningen

Events not firing

Möjliga orsaker:

Händelsehanterare inte korrekt inställd
JavaScript-fel som hindrar händelsefortplantning
SDK inte korrekt initierad

Lösningar:

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

Styling issues

Möjliga orsaker:

CSS-konflikter med applikationsstilar
Tema inställningarna inte korrekt tillämpade
Responsiv designfrågor

Lösningar:

Kontrollera för CSS-konflikter i webbläsarens DevTools
Verifiera att tema instä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 man ställer in Google Pay och andra digitala plånböcker, se sidan Digitala Plånböcker.

Apple Pay stöds ännu inte i kassaöverlägget. 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+

Overlay vs Inline Checkout

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

Funktion	Overlay Checkout	Inline Checkout
Integrationsdjup	Modal ovanpå sidan	Fullt inbäddad i sidan
Layout kontroll	Begränsad	Full kontroll
Varumärkesprofilering	Separat från sidan	Sömlös
Implementationsinsats	Lägre	Högre
Bäst för	Snabb integration, befintliga sidor	Anpassade kassasidor, högkonvertibla flöden

Använd overlay checkout för snabbare integration med minimala förändringar av dina befintliga sidor. Använd inline checkout när du vill ha maximal kontroll över kassaupplevelsen och sömlös varumärkesprofilering.

Relaterade Resurser

Inline Checkout

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

Checkout Sessions API

Skapa kassasessioner för att driva dina kassa upplevelser.

Webhooks

Hantera betalningshändelser server-sida med webhooks.

Integration Guide

Komplett guide för att integrera Dodo Payments.

För mer hjälp, besök vår Discord community eller kontakta vårt utvecklar support team.

​Översikt

​Demo

Interactive Demo

​Snabbstart

​Steg-för-steg Integrationsguide

​API Referens

​Konfiguration

​Initieringsalternativ

​Checkout-alternativ

​Metoder

​Öppna Checkout

​Stäng Kassa

​Kontrollera Status

​Händelser

​Implementeringsalternativ

​Installation via Paket Manager

​CDN-Implementation

​Temaanpassning

​Grundläggande Tema Konfiguration

​Fullständig Tema Konfiguration

​Endast Ljust Läge

​Endast Mörkt Läge

​Delvis Tema Överskrivning

​Teme Konfiguration med Andra Alternativ

​TypeScript Typer

​Felhantering

​Bästa Praxis

​Felsökning

​Aktivera Digitala Plånböcker

​Webbläsarstöd

​Overlay vs Inline Checkout

​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 Kassa

Kontrollera Status

Händelser

Implementeringsalternativ

Installation via Paket Manager

CDN-Implementation

Temaanpassning

Grundläggande Tema Konfiguration

Fullständig Tema Konfiguration

Endast Ljust Läge

Endast Mörkt Läge

Delvis Tema Överskrivning

Teme Konfiguration med Andra Alternativ

TypeScript Typer

Felhantering

Bästa Praxis

Felsökning

Aktivera Digitala Plånböcker

Webbläsarstöd

Overlay vs Inline Checkout

Relaterade Resurser